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 supports two usage methods: import as module or use as Skill.

Method 1: Import as Module (for developer integration)

Step 1: Copy source files

Copy the ts/ directory to your WaterFlow project, for example:

your-waterflow-project/
├── src/
│   └── runtime/
│       └── core/
│           └── graph_memory/    # Copy from ts/src/runtime/core/
└── ts/                          # Or place in project root
    └── bundled-skills/          # Skill files

Step 2: Build TypeScript

cd ts/
npm install
npm run build

Compiled files will be output to ts/dist/.

Step 3: Import in your code

import { createGraphMemoryTool } from './runtime/core/tools/builtin/graph_memory_tool';

// Create tool instance, can pass sessionId to distinguish different sessions
const tool = createGraphMemoryTool('my-session-id');

// Prepare execution context
const context = {
  toolCallId: 'call-123',
  workingDirectory: '/project',
  abortController: { signal: {} },
  config: { timeout: 30000 },
  logger: {
    info: console.log,
    warn: console.warn,
    error: console.error,
    debug: console.debug
  }
};

// Commit memory example
const commitResult = await tool.handler({
  action: 'commit',
  params: {
    triplets: [
      { subject: 'User', relation: 'likes', object: 'Programming' },
      { subject: 'User', relation: 'is learning', object: 'TypeScript' }
    ]
  }
}, context);

console.log(commitResult);
// Output: {"success":true,"data":{"createdEntities":4,"createdRelations":2}}

// Recall memory example
const recallResult = await tool.handler({
  action: 'recall',
  params: {
    queryIntent: 'User Programming'
  }
}, context);

console.log(recallResult);
// Output: {"success":true,"data":{"entities":[...],"relations":[...],"message":"Found X entities, Y relations"}}

Method 2: Use Skill (recommended for AI Agent)

Step 1: Configure Skill source

In your WaterFlow project, find the Skill configuration file and add bundled source pointing to this project's Skill directory:

// skill_interface.ts or config file
import { DEFAULT_SKILL_LOADER_CONFIG } from './skill_interface';

const config = {
  ...DEFAULT_SKILL_LOADER_CONFIG,
  sources: {
    ...DEFAULT_SKILL_LOADER_CONFIG.sources,
    bundled: './ts/bundled-skills'  // Point to this project's Skill directory
  },
  enabledSources: ['project', 'bundled']
};

Step 2: Call Skill via Agent

In your Agent or Workflow, call Skill via Tool:

Use skill:graph_memory for:

1. Commit memory: I like programming, learning TypeScript
2. Recall memory: Find memories related to me and programming

Or call via code:

// Call via SkillTool
const skillResult = await skillTool.handler({
  skill: 'graph_memory',
  args: 'recall - queryIntent: "User learning"'
}, context);

Available Skills

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

---

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)