feat: complete OpenClaw plugin migration with SQLite persistence

- Migrate to OpenClaw Plugin SDK with definePluginEntry and api.registerTool - Rewrite GraphDatabase with better-sqlite3 for persistent storage - Implement recall depth traversal, timeRange filtering, supersede mode - Add archive and cleanup data management features - Fix SKILL.md frontmatter to OpenClaw single-line format (kebab-case names) - Add ToolLimiter for per-turn rate limiting - Add TypeBox parameter schemas for OpenClaw tool registration - Add 110 tests across 4 test files (GraphDatabase, MemoryService, Tool, Limiter) - Update README for OpenClaw plugin installation and usage
2026-10-15 12:15:32 +00:00 · 2026-04-16 18:26:19 +08:00
parent 4caf115ec9
commit 85c3431b52
27 changed files with 3574 additions and 1017 deletions
--- a/README.md
+++ b/README.md
@ -1,113 +1,30 @@
-# TrulyMEM - OpenClaw 适配版
+# TrulyMEM - OpenClaw Graph Memory Plugin

-让 AI 拥有真正的长期记忆能力 - OpenClaw 框架适配版
+让 AI 拥有真正的长期记忆能力 - OpenClaw 框架插件版

 [English Version](./README_EN.md)

 ---

-## 🤖 AI 自行安装指南
-
-> 本节面向 AI Agent，指导其如何自主安装此 Skill 到 OpenClaw 框架
-
-### 安装步骤
-
-#### 步骤 1：定位 Skill 目录
-
-OpenClaw 的 Skill 优先级：`/.agents/skills/` > `~/.agents/skills/` > `~/.openclaw/skills/`
-
-将本项目的 `skills/` 目录复制到高优先级位置：
-
-```bash
-# 方式 1: 用户级安装 (推荐)
-cp -r skills/ ~/.agents/skills/graph_memory
-
-# 方式 2: 系统级安装
-sudo cp -r skills/ /.agents/skills/graph_memory
-```
-
-#### 步骤 2：验证安装
-
-在 OpenClaw 中调用 Skill：
-
-```
-记得: 我喜欢编程，正在学习 TypeScript
-```
-
-AI 应收到确认消息。
-
-#### 步骤 3：使用 Skill
-
-安装成功后，AI 可以使用以下命令：
-
-| 命令 | 功能 |
-|------|------|
-| `commit` | 写入记忆 |
-| `recall` | 检索记忆 |
-| `purge` | 删除记忆 |
-| `introspect` | 查看状态 |
-| `persona_update/clear` | 人设管理 |
-| `task_create/set_state/delete` | 任务管理 |
-
---
-
 ## 简介

-本项目是将 TrulyMEM 的图记忆能力迁移到 OpenClaw 框架的 TypeScript 实现。
+本项目是 OpenClaw 的图记忆插件，基于 SQLite 实现持久化图数据库。

-作为 OpenClaw 的 Skill 模块，提供图记忆功能：
- **recall**: 检索记忆
- **commit**: 写入记忆
- **purge**: 删除记忆
- **introspect**: 查看状态
+**核心功能：**
+- **recall**: 检索记忆（支持关键词、种子实体、多跳遍历、时间过滤）
+- **commit**: 写入记忆（三元组批量写入）
+- **purge**: 删除记忆（软删除/硬删除/纠错替代）
+- **introspect**: 查看记忆状态
+- **archive**: 归档旧记忆
+- **cleanup**: 清理无效数据
 - **persona_update/clear**: 人设管理
- **task_create/set_state/delete**: 任务管理
+- **task_create/set_state/delete/link_info**: 任务管理

 ---

-## 目录结构
+## 安装

-```
-ts/
-├── src/runtime/core/
-│   ├── graph_memory/           # 图记忆核心模块
-│   │   ├── types.ts            # 类型定义
-│   │   ├── graph_database.ts   # 图数据库
-│   │   ├── memory_service.ts  # 记忆服务
-│   │   └── index.ts         # 模块导出
-│   └── tools/
-│       └── builtin/
-│           └── graph_memory_tool.ts  # Tool 实现
-│
-├── package.json            # 项目配置
-└── tsconfig.json           # TypeScript 配置
-
-skills/                     # OpenClaw Skill 定义
-└── graph_memory/
-    ├── SKILL.md            # 记忆操作
-    ├── persona/SKILL.md    # 人设管理
-    └── task/SKILL.md        # 任务管理
-```
-
---
-
-## 在 OpenClaw 中使用
-
-### 方式一：作为模块直接引用（适合开发者集成）
-
-#### 步骤 1：复制源码
-
-将本项目的 `ts/` 目录复制到你的 OpenClaw 项目中：
-
-```
-你的OpenClaw项目/
-└── src/
-    └── runtime/
-        └── core/
-            └── graph_memory/    # 从 ts/src/runtime/core/ 复制
-```
-
-#### 步骤 2：编译 TypeScript
+### 方式一：作为 OpenClaw 插件安装

 ```bash
 cd ts/
@ -115,18 +32,77 @@ npm install
 npm run build
 ```

-编译后的文件会输出到 `ts/dist/` 目录。
+将插件目录添加到 OpenClaw 配置中，或使用 `openclaw plugins install` 安装。

-#### 步骤 3：在代码中引用
+### 方式二：作为 Skill 安装（推荐）
+
+将 `skills/` 目录复制到 OpenClaw 的 Skill 目录：
+
+```bash
+cp -r skills/graph-memory ~/.agents/skills/graph-memory
+cp -r skills/graph-memory/persona ~/.agents/skills/graph-memory-persona
+cp -r skills/graph-memory/task ~/.agents/skills/graph-memory-task
+```
+
+---
+
+## 目录结构
+
+```
+ts/
+├── src/
+│   ├── plugin-entry.ts              # OpenClaw Plugin 入口
+│   └── runtime/core/
+│       ├── graph_memory/
+│       │   ├── types.ts             # 类型定义
+│       │   ├── graph_database.ts    # SQLite 图数据库
+│       │   ├── memory_service.ts    # 记忆服务
+│       │   └── index.ts             # 模块导出
+│       └── tools/
+│           ├── builtin/
+│           │   └── graph_memory_tool.ts  # Tool 实现
+│           └── tool_limiter.ts      # 调用限制器
+├── bundled-skills/
+│   └── graph-memory/                # 内置 Skill 定义
+│       ├── SKILL.md
+│       ├── persona/SKILL.md
+│       └── task/SKILL.md
+├── package.json
+├── tsconfig.json
+└── openclaw.plugin.json             # Plugin Manifest
+
+skills/                              # 独立 Skill 定义
+└── graph-memory/
+    ├── SKILL.md
+    ├── persona/SKILL.md
+    └── task/SKILL.md
+```
+
+---
+
+## 在 OpenClaw 中使用
+
+### 作为 Plugin

 ```typescript
-import { createGraphMemoryTool } from './runtime/core/tools/builtin/graph_memory_tool';
+import registerGraphMemoryPlugin from './dist/plugin-entry.js';

-// 创建工具实例
-const tool = createGraphMemoryTool('my-session-id');
+registerGraphMemoryPlugin({
+  registerTool(tool) {
+    // OpenClaw 会自动注册工具
+  }
+});
+```

-// 写入记忆示例
-const commitResult = await tool.handler({
+### 作为独立模块
+
+```typescript
+import { createGraphMemoryTool } from './dist/runtime/core/tools/builtin/graph_memory_tool.js';
+
+const tool = createGraphMemoryTool('graph_memory.db', 'my-session-id');
+
+// 写入记忆
+const result = await tool.execute('call-1', {
  action: 'commit',
  params: {
    triplets: [
@ -134,111 +110,59 @@ const commitResult = await tool.handler({
      { subject: '用户', relation: '正在学习', object: 'TypeScript' }
    ]
  }
-}, context);
+});

-// 检索记忆示例
-const recallResult = await tool.handler({
+// 检索记忆
+const recallResult = await tool.execute('call-2', {
  action: 'recall',
-  params: {
-    queryIntent: '用户 编程'
-  }
-}, context);
+  params: { queryIntent: '用户 编程' }
+});
 ```

-### 方式二：使用 Skill（推荐，适合 AI Agent 调用）
-
-#### 步骤 1：放置 Skill 文件
-
-将 `skills/` 目录复制到 OpenClaw 的 Skill 目录：
-
-```bash
-cp -r skills/ ~/.agents/skills/graph_memory
-```
-
-#### 步骤 2：通过 Agent 调用 Skill
-
-在 OpenClaw 中直接调用：
-
-```
-使用 graph_memory 记住: 我喜欢编程，正在学习 TypeScript
-```
-
-#### 可用 Skill 列表
-
-| Skill 名称 | 功能 | 使用场景 |
-|------------|------|----------|
-| `graph_memory` | 记忆 CRUD | 读取/写入/删除记忆 |
-| `graph_memory_persona` | 人设管理 | 设置 AI 角色性格 |
-| `graph_memory_task` | 任务管理 | 创建/更新长期任务 |
-
 ---

 ## API

-### GraphMemoryTool
-
-```typescript
-const tool = new GraphMemoryTool(sessionId?: string);
-```
-
-#### Actions
+### Actions

 | Action | 说明 | 参数 |
 |--------|------|------|
-| `recall` | 检索记忆 | `queryIntent`, `seedEntities`, `sessionFilter` |
+| `recall` | 检索记忆 | `queryIntent`, `seedEntities`, `depth`, `sessionFilter`, `timeRange` |
 | `commit` | 写入记忆 | `triplets`, `sessionId`, `turnId` |
-| `purge` | 删除记忆 | `criteria`, `mode` |
+| `purge` | 删除记忆 | `criteria`, `mode` (soft/hard/supersede), `newRelation` |
 | `introspect` | 查看状态 | - |
-| `persona_update` | 更新人设 | `attributes`, `mode` |
+| `archive` | 归档旧记忆 | `days` (默认 30) |
+| `cleanup` | 清理无效数据 | `dry_run` (默认 true) |
+| `persona_update` | 更新人设 | `attributes`, `mode` (merge/replace) |
 | `persona_clear` | 清除人设 | `confirm` |
 | `task_create` | 创建任务 | `task_id`, `description`, `info_nodes` |
 | `task_set_state` | 设置状态 | `task_id`, `state` |
 | `task_delete` | 删除任务 | `task_id` |
+| `task_link_info` | 关联信息 | `task_id`, `info_node` |

 ---

-## 示例
+## Skill 列表

-### 写入记忆
+| Skill 名称 | 功能 | 使用场景 |
+|------------|------|----------|
+| `graph-memory` | 记忆 CRUD | 读取/写入/删除记忆 |
+| `graph-memory-persona` | 人设管理 | 设置 AI 角色性格 |
+| `graph-memory-task` | 任务管理 | 创建/更新长期任务 |

-```json
-{
-  "action": "commit",
-  "params": {
-    "triplets": [
-      { "subject": "用户", "relation": "喜欢", "object": "TypeScript" },
-      { "subject": "用户", "relation": "正在学习", "object": "OpenClaw" }
-    ]
-  }
-}
-```
+---

-### 检索记忆
+## 开发

-```json
-{
-  "action": "recall",
-  "params": {
-    "queryIntent": "用户 学习"
-  }
-}
-```
-
-### 创建任务
-
-```json
-{
-  "action": "task_create",
-  "params": {
-    "task_id": "Task_学习TypeScript",
-    "description": "学习 TypeScript 并完成项目",
-    "info_nodes": ["文档链接", "教程链接"]
-  }
-}
+```bash
+cd ts/
+npm install
+npm run build    # 编译
+npm test         # 运行测试
 ```

 ---

 ## 许可证

-[GNU General Public License v3.0 (GPLv3)](LICENSE)
+[GNU General Public License v3.0 (GPLv3)](LICENSE)