TrulyMEM - WaterFlow Adapter

Give AI true long-term memory capability - WaterFlow framework adapter version

中文版本

---

Introduction

This project ports TrulyMEM's graph memory capability to TypeScript for the WaterFlow framework.

As a built-in module for WaterFlow, it provides graph memory functionality:

• recall: Retrieve memories
• commit: Commit memories
• purge: Delete memories
• introspect: Inspect status
• persona_update/clear: Persona management
• task_create/set_state/delete: Task management

---

Directory Structure

ts/
├── src/runtime/core/
│   ├── graph_memory/           # Graph memory core module
│   │   ├── types.ts            # Type definitions
│   │   ├── graph_database.ts   # Graph database
│   │   ├── memory_service.ts   # Memory service
│   │   └── index.ts            # Module exports
│   └── tools/
│       └── builtin/
│           └── graph_memory_tool.ts  # Tool implementation
│
├── bundled-skills/             # Skill definitions
│   └── graph_memory/
│       ├── SKILL.md            # Memory operations
│       ├── persona/SKILL.md   # Persona management
│       └── task/SKILL.md       # Task management
│
├── package.json                # Project config
└── tsconfig.json               # TypeScript config

---

Usage in WaterFlow

This module requires zero changes to WaterFlow source code. Just register it in your entry file.

Quick Start (Recommended)

Step 1: Install

npm install /path/to/TrulyMEM-TrueHumanMEM/ts

Or add to package.json:

{
  "dependencies": {
    "trulymem-waterflow": "file:../TrulyMEM-TrueHumanMEM/ts"
  }
}

Then run:

npm install

Step 2: Register in your entry file

Just two lines, zero changes to WaterFlow:

import { getPlatform } from 'waterflow/platform';
import { installTrulyMEM } from 'trulymem/tools';

// One-line install, returns configured ToolRegistry
const registry = installTrulyMEM(getPlatform(), 'my-session-id');

// Continue assembling WaterFlow...
const toolExecutor = new ToolExecutor(registry);

Manual Registration (More control)

If you want to control ToolRegistry creation yourself:

import { getPlatform } from 'waterflow/platform';
import { initializeToolRegistry } from 'waterflow/runtime/core/tools/builtin';
import { registerGraphMemoryTool } from 'trulymem/tools';

const platform = getPlatform();
const registry = initializeToolRegistry(platform);

// Register graph memory tool
registerGraphMemoryTool(registry, 'my-session-id');

// Continue assembling...

Use Skill (AI Agent)

Step 1: Configure Skill source

const config = {
  ...DEFAULT_SKILL_LOADER_CONFIG,
  sources: {
    ...DEFAULT_SKILL_LOADER_CONFIG.sources,
    bundled: './node_modules/trulymem-waterflow/bundled-skills'
  },
  enabledSources: ['project', 'bundled']
};

Step 2: Call via Agent

AI Agent automatically reads SKILL.md and calls builtin:graph_memory tool.

Available Skills

Skill Name	Function	Use Case
graph_memory	Memory CRUD	Read/Write/Delete memories
persona	Persona management	Set AI role/personality
task	Task management	Create/update long-term tasks

Skill Definition Format

WaterFlow's SkillLoader extracts from SKILL.md:

• name: Extracted from directory name (e.g., graph_memory, persona, task)
• description: Extracted from first Markdown # heading
• allowed-tools: Converted to allowedTools field
• arguments: Properly mapped to SkillDefinition.arguments
• user-invocable: Converted to userInvocable field

Note: when_to_use info is integrated into Markdown body, searchable via SkillRegistry.search().

---

API

GraphMemoryTool

const tool = new GraphMemoryTool(sessionId?: string);

Actions

Action	Description	Parameters
recall	Retrieve memories	queryIntent, seedEntities, sessionFilter
commit	Commit memories	triplets, sessionId, turnId
purge	Delete memories	criteria, mode
introspect	Inspect status	-
persona_update	Update persona	attributes, mode
persona_clear	Clear persona	confirm
task_create	Create task	task_id, description, info_nodes
task_set_state	Set state	task_id, state
task_delete	Delete task	task_id

---

Examples

Commit Memory

{
  "action": "commit",
  "params": {
    "triplets": [
      { "subject": "User", "relation": "likes", "object": "TypeScript" },
      { "subject": "User", "relation": "is learning", "object": "WaterFlow" }
    ]
  }
}

Recall Memory

{
  "action": "recall",
  "params": {
    "queryIntent": "User learning"
  }
}

Create Task

{
  "action": "task_create",
  "params": {
    "task_id": "Task_LearnTypeScript",
    "description": "Learn TypeScript and complete project",
    "info_nodes": ["Documentation", "Tutorial"]
  }
}

---

License

GNU General Public License v3.0 (GPLv3)