openclaw-cortex-memory 0.1.0-Alpha.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +198 -0
- package/SKILL.md +263 -0
- package/dist/index.d.ts +90 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +1871 -0
- package/dist/index.js.map +1 -0
- package/dist/openclaw.plugin.json +295 -0
- package/dist/src/engine/memory_engine.d.ts +20 -0
- package/dist/src/engine/memory_engine.d.ts.map +1 -0
- package/dist/src/engine/memory_engine.js +3 -0
- package/dist/src/engine/memory_engine.js.map +1 -0
- package/dist/src/engine/ts_engine.d.ts +69 -0
- package/dist/src/engine/ts_engine.d.ts.map +1 -0
- package/dist/src/engine/ts_engine.js +390 -0
- package/dist/src/engine/ts_engine.js.map +1 -0
- package/dist/src/engine/types.d.ts +53 -0
- package/dist/src/engine/types.d.ts.map +1 -0
- package/dist/src/engine/types.js +3 -0
- package/dist/src/engine/types.js.map +1 -0
- package/dist/src/reflect/reflector.d.ts +32 -0
- package/dist/src/reflect/reflector.d.ts.map +1 -0
- package/dist/src/reflect/reflector.js +124 -0
- package/dist/src/reflect/reflector.js.map +1 -0
- package/dist/src/rules/rule_store.d.ts +22 -0
- package/dist/src/rules/rule_store.d.ts.map +1 -0
- package/dist/src/rules/rule_store.js +102 -0
- package/dist/src/rules/rule_store.js.map +1 -0
- package/dist/src/session/session_end.d.ts +30 -0
- package/dist/src/session/session_end.d.ts.map +1 -0
- package/dist/src/session/session_end.js +209 -0
- package/dist/src/session/session_end.js.map +1 -0
- package/dist/src/store/read_store.d.ts +44 -0
- package/dist/src/store/read_store.d.ts.map +1 -0
- package/dist/src/store/read_store.js +239 -0
- package/dist/src/store/read_store.js.map +1 -0
- package/dist/src/store/write_store.d.ts +31 -0
- package/dist/src/store/write_store.d.ts.map +1 -0
- package/dist/src/store/write_store.js +138 -0
- package/dist/src/store/write_store.js.map +1 -0
- package/dist/src/sync/session_sync.d.ts +28 -0
- package/dist/src/sync/session_sync.d.ts.map +1 -0
- package/dist/src/sync/session_sync.js +214 -0
- package/dist/src/sync/session_sync.js.map +1 -0
- package/index.ts +2071 -0
- package/openclaw.plugin.json +295 -0
- package/package.json +55 -0
- package/scripts/cli.js +262 -0
- package/scripts/install.js +27 -0
- package/scripts/uninstall.js +212 -0
package/README.md
ADDED
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# OpenClaw Cortex Memory
|
|
2
|
+
|
|
3
|
+
OpenClaw 长期记忆插件,提供跨会话检索、事件存储、规则反思、增量同步与运行诊断能力。
|
|
4
|
+
可作为 OpenClaw 的 memory slot 直接接入,支持从历史会话持续沉淀可复用记忆。
|
|
5
|
+
|
|
6
|
+
## 功能特性
|
|
7
|
+
|
|
8
|
+
| 特性 | 说明 |
|
|
9
|
+
|------|------|
|
|
10
|
+
| 语义检索 | `search_memory` 支持 query + top_k |
|
|
11
|
+
| 事件存储 | `store_event` 将摘要写入归档 |
|
|
12
|
+
| 上下文注入 | `get_hot_context` / `get_auto_context` |
|
|
13
|
+
| 增量同步 | `sync_memory` 按状态文件增量导入 |
|
|
14
|
+
| 规则演进 | `reflect_memory` 更新 `CORTEX_RULES.md` |
|
|
15
|
+
| 运行诊断 | `diagnostics` 检查本地存储状态 |
|
|
16
|
+
|
|
17
|
+
## 安装
|
|
18
|
+
|
|
19
|
+
### 前置要求
|
|
20
|
+
|
|
21
|
+
- Node.js 22+
|
|
22
|
+
- OpenAI API Key(或其他兼容 API)
|
|
23
|
+
|
|
24
|
+
### 安装步骤
|
|
25
|
+
|
|
26
|
+
快速安装(推荐):
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
git clone https://github.com/deki18/openclaw-cortex-memory.git ~/openclaw-cortex-memory-src
|
|
30
|
+
cd ~/openclaw-cortex-memory-src
|
|
31
|
+
npm install && npm run build && npm pack
|
|
32
|
+
cd ~/openclaw
|
|
33
|
+
pnpm openclaw plugins install ~/openclaw-cortex-memory-src/openclaw-cortex-memory-0.1.0-Alpha.1.tgz
|
|
34
|
+
pnpm openclaw plugins enable openclaw-cortex-memory
|
|
35
|
+
pnpm openclaw gateway restart
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
后续更新(同一套流程):
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
cd ~/openclaw-cortex-memory-src
|
|
42
|
+
git pull && npm install && npm run build && npm pack
|
|
43
|
+
cd ~/openclaw
|
|
44
|
+
pnpm openclaw plugins install ~/openclaw-cortex-memory-src/openclaw-cortex-memory-0.1.0-Alpha.1.tgz
|
|
45
|
+
pnpm openclaw gateway restart
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
安装前如果 `openclaw.json` 已经提前写了 `allow/slots/entries` 指向本插件,先临时移除,安装后再加回,避免安装前校验报 `plugin not found`。
|
|
49
|
+
|
|
50
|
+
### 本地开发模式(无安装记录)
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
cd ~/.openclaw/extensions
|
|
54
|
+
git clone https://github.com/deki18/openclaw-cortex-memory.git
|
|
55
|
+
cd openclaw-cortex-memory
|
|
56
|
+
npm install
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`npm install` 会自动执行 TypeScript 构建并生成 `dist/`,但这种方式默认不写 OpenClaw 安装记录。
|
|
60
|
+
|
|
61
|
+
## 配置
|
|
62
|
+
|
|
63
|
+
在 `openclaw.json` 中添加:
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
{
|
|
67
|
+
"plugins": {
|
|
68
|
+
"slots": { "memory": "openclaw-cortex-memory" },
|
|
69
|
+
"entries": {
|
|
70
|
+
"openclaw-cortex-memory": {
|
|
71
|
+
"enabled": true,
|
|
72
|
+
"config": {
|
|
73
|
+
"engineMode": "ts",
|
|
74
|
+
"dbPath": "<optional-memory-dir>",
|
|
75
|
+
"autoSync": true,
|
|
76
|
+
"autoReflect": true,
|
|
77
|
+
"embedding": {
|
|
78
|
+
"provider": "api",
|
|
79
|
+
"model": "text-embedding-3-large",
|
|
80
|
+
"apiKey": "${EMBEDDING_API_KEY}",
|
|
81
|
+
"baseURL": "https://your-embedding-endpoint/v1",
|
|
82
|
+
"dimensions": 3072
|
|
83
|
+
},
|
|
84
|
+
"llm": {
|
|
85
|
+
"provider": "api",
|
|
86
|
+
"model": "gpt-4",
|
|
87
|
+
"apiKey": "${LLM_API_KEY}",
|
|
88
|
+
"baseURL": "https://your-llm-endpoint/v1"
|
|
89
|
+
},
|
|
90
|
+
"reranker": {
|
|
91
|
+
"provider": "api",
|
|
92
|
+
"model": "BAAI/bge-reranker-v2-m3",
|
|
93
|
+
"apiKey": "${RERANKER_API_KEY}",
|
|
94
|
+
"baseURL": "https://your-reranker-endpoint/v1/rerank"
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### 配置项说明
|
|
104
|
+
|
|
105
|
+
| 配置项 | 必填 | 说明 |
|
|
106
|
+
|--------|------|------|
|
|
107
|
+
| `embedding.provider` | 是 | 建议使用 `api`(统一第三方接口模式) |
|
|
108
|
+
| `embedding.model` | 是 | 嵌入模型名称 |
|
|
109
|
+
| `embedding.dimensions` | 否 | 向量维度,需与模型匹配 |
|
|
110
|
+
| `embedding.apiKey` | 是 | Embedding API Key(建议 `${EMBEDDING_API_KEY}`) |
|
|
111
|
+
| `embedding.baseURL` | 是 | Embedding API 端点 |
|
|
112
|
+
| `llm.provider` | 是 | 建议使用 `api` |
|
|
113
|
+
| `llm.model` | 是 | LLM 模型名称 |
|
|
114
|
+
| `llm.apiKey` | 是 | LLM API Key(建议 `${LLM_API_KEY}`) |
|
|
115
|
+
| `llm.baseURL` | 是 | LLM API 端点 |
|
|
116
|
+
| `reranker.provider` | 否 | 建议使用 `api` |
|
|
117
|
+
| `reranker.model` | 是 | Reranker 模型名称 |
|
|
118
|
+
| `reranker.apiKey` | 是 | Reranker API Key(建议 `${RERANKER_API_KEY}`) |
|
|
119
|
+
| `reranker.baseURL` | 是 | Reranker API 端点 |
|
|
120
|
+
| `engineMode` | 否 | 固定 `ts` |
|
|
121
|
+
| `dbPath` | 否 | 数据目录,默认 `<plugin-dir>/data/memory` |
|
|
122
|
+
| `autoSync` | 否 | 会话结束时自动同步历史记录,默认 `true` |
|
|
123
|
+
| `autoReflect` | 否 | 自动触发记忆反思,默认 `false` |
|
|
124
|
+
|
|
125
|
+
### 启动
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
openclaw config validate
|
|
129
|
+
openclaw gateway restart
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### 主 Agent 注入说明
|
|
133
|
+
|
|
134
|
+
首次接入后,建议把下面这段发给主 Agent,确保其按记忆工作流执行:
|
|
135
|
+
|
|
136
|
+
```text
|
|
137
|
+
你已接入 Cortex Memory。请遵循以下规则:
|
|
138
|
+
1) 当用户询问历史对话、偏好、项目上下文时,先调用 search_memory 再回答。
|
|
139
|
+
2) 需要当前会话热上下文时调用 get_hot_context。
|
|
140
|
+
3) 需要自动召回相关记忆时调用 get_auto_context。
|
|
141
|
+
4) 在一件重要事情结束并形成明确结果后,再调用 store_event 记录(不要在过程进行中频繁记录)。
|
|
142
|
+
5) 需要实体关联关系时调用 query_graph。
|
|
143
|
+
6) 当任务经历“失败→调整→最终成功”时,优先用 store_event 记录失败原因与成功方案,再调用 reflect_memory 沉淀可复用规则。
|
|
144
|
+
7) 需要导入历史会话时调用 sync_memory。
|
|
145
|
+
8) 出现配置校验失败、记忆读写异常、检索结果异常或数据目录问题时,优先调用 diagnostics。
|
|
146
|
+
9) 同一任务内不要反复调用 store_event 或 reflect_memory;仅在关键节点或任务收尾时触发一次。
|
|
147
|
+
10) 不要臆造历史事实;无法确认时必须先检索。
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
## 可用工具
|
|
151
|
+
|
|
152
|
+
| 工具 | 说明 |
|
|
153
|
+
|------|------|
|
|
154
|
+
| `search_memory` | 语义搜索记忆库,支持 top_k 参数 |
|
|
155
|
+
| `store_event` | 存储事件,可包含实体和关系 |
|
|
156
|
+
| `query_graph` | 查询实体关系图谱 |
|
|
157
|
+
| `get_hot_context` | 获取热上下文(CORTEX_RULES.md + 近期会话) |
|
|
158
|
+
| `get_auto_context` | 自动检索相关记忆 + 热上下文 |
|
|
159
|
+
| `reflect_memory` | 触发记忆反思,将事件转化为规则 |
|
|
160
|
+
| `sync_memory` | 同步 OpenClaw 历史会话(增量) |
|
|
161
|
+
| `delete_memory` | 删除指定记忆 |
|
|
162
|
+
| `diagnostics` | 系统诊断 |
|
|
163
|
+
|
|
164
|
+
## CLI 命令
|
|
165
|
+
|
|
166
|
+
CLI 命令需在插件目录运行:
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
npx cortex-memory status # 查看插件状态
|
|
170
|
+
npx cortex-memory enable # 启用插件
|
|
171
|
+
npx cortex-memory disable # 禁用插件(回退到内置记忆)
|
|
172
|
+
npx cortex-memory uninstall # 卸载插件
|
|
173
|
+
npx cortex-memory uninstall --keep-data # 卸载但保留数据
|
|
174
|
+
npx cortex-memory help # 查看命令帮助
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
## 数据存储
|
|
178
|
+
|
|
179
|
+
| 路径 | 说明 |
|
|
180
|
+
|------|------|
|
|
181
|
+
| `<dbPath>/MEMORY.md` | 记忆说明 |
|
|
182
|
+
| `<dbPath>/CORTEX_RULES.md` | 规则文件 |
|
|
183
|
+
| `<dbPath>/sessions/active/sessions.jsonl` | 活跃会话 |
|
|
184
|
+
| `<dbPath>/sessions/archive/sessions.jsonl` | 归档事件 |
|
|
185
|
+
| `<dbPath>/.sync_state.json` | 同步增量状态 |
|
|
186
|
+
| `<dbPath>/.session_end_state.json` | session_end 幂等状态 |
|
|
187
|
+
| `<dbPath>/.rule_store_state.json` | 规则去重状态 |
|
|
188
|
+
|
|
189
|
+
## 注意事项
|
|
190
|
+
|
|
191
|
+
1. **API Key 安全**:使用环境变量 `${OPENAI_API_KEY}` 而非硬编码
|
|
192
|
+
2. **向量维度**:必须与嵌入模型匹配,如 `text-embedding-3-large` 为 3072
|
|
193
|
+
3. **重排序**:可选配置 `reranker` 以提升检索精度
|
|
194
|
+
4. **单栈运行**:当前版本为纯 TS,无 Python 运行时依赖
|
|
195
|
+
|
|
196
|
+
## 许可证
|
|
197
|
+
|
|
198
|
+
MIT License
|
package/SKILL.md
ADDED
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cortex-memory
|
|
3
|
+
description: 长期记忆系统(纯 TypeScript)。Use when user asks about past conversations, preferences, project history, or needs to remember information across sessions.
|
|
4
|
+
homepage: https://github.com/deki18/openclaw-cortex-memory
|
|
5
|
+
metadata:
|
|
6
|
+
{
|
|
7
|
+
"openclaw": {
|
|
8
|
+
"emoji": "🧠",
|
|
9
|
+
"os": ["darwin", "linux", "win32"],
|
|
10
|
+
"requires": {
|
|
11
|
+
"env": ["OPENAI_API_KEY"]
|
|
12
|
+
},
|
|
13
|
+
"primaryEnv": "OPENAI_API_KEY"
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
# Cortex Memory - 长期记忆系统
|
|
19
|
+
|
|
20
|
+
为 OpenClaw Agent 提供持久化记忆能力,当前为纯 TypeScript 单栈实现。
|
|
21
|
+
|
|
22
|
+
## 使用场景
|
|
23
|
+
|
|
24
|
+
**USE when:**
|
|
25
|
+
- 用户询问过去的对话内容或决策
|
|
26
|
+
- 需要记住用户偏好、项目信息
|
|
27
|
+
- 跨会话保持上下文
|
|
28
|
+
- 查询实体关系(人物、项目、技术)
|
|
29
|
+
- 存储重要事件或里程碑
|
|
30
|
+
|
|
31
|
+
**DON'T use when:**
|
|
32
|
+
- 仅需当前会话的临时信息
|
|
33
|
+
- 查询实时数据(天气、新闻等)
|
|
34
|
+
|
|
35
|
+
## 快速开始
|
|
36
|
+
|
|
37
|
+
### 安装
|
|
38
|
+
|
|
39
|
+
快速安装(推荐):
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
git clone https://github.com/deki18/openclaw-cortex-memory.git ~/openclaw-cortex-memory-src
|
|
43
|
+
cd ~/openclaw-cortex-memory-src
|
|
44
|
+
npm install && npm run build && npm pack
|
|
45
|
+
cd ~/openclaw
|
|
46
|
+
pnpm openclaw plugins install ~/openclaw-cortex-memory-src/openclaw-cortex-memory-0.1.0-Alpha.1.tgz
|
|
47
|
+
pnpm openclaw plugins enable openclaw-cortex-memory
|
|
48
|
+
pnpm openclaw gateway restart
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### 后续更新
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
cd ~/openclaw-cortex-memory-src
|
|
55
|
+
git pull && npm install && npm run build && npm pack
|
|
56
|
+
|
|
57
|
+
cd ~/openclaw
|
|
58
|
+
pnpm openclaw plugins install ~/openclaw-cortex-memory-src/openclaw-cortex-memory-0.1.0-Alpha.1.tgz
|
|
59
|
+
pnpm openclaw gateway restart
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
安装前如果 `openclaw.json` 已经提前写了 `allow/slots/entries` 指向本插件,先临时移除,安装后再加回,避免安装前校验报 `plugin not found`。
|
|
63
|
+
|
|
64
|
+
### 本地开发模式(无安装记录)
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
cd ~/.openclaw/extensions
|
|
68
|
+
git clone https://github.com/deki18/openclaw-cortex-memory.git
|
|
69
|
+
cd openclaw-cortex-memory
|
|
70
|
+
npm install
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### 配置
|
|
74
|
+
|
|
75
|
+
在 `openclaw.json` 中配置插件:
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
{
|
|
79
|
+
"plugins": {
|
|
80
|
+
"slots": { "memory": "openclaw-cortex-memory" },
|
|
81
|
+
"entries": {
|
|
82
|
+
"openclaw-cortex-memory": {
|
|
83
|
+
"enabled": true,
|
|
84
|
+
"config": {
|
|
85
|
+
"engineMode": "ts",
|
|
86
|
+
"dbPath": "<optional-memory-dir>",
|
|
87
|
+
"autoSync": true,
|
|
88
|
+
"autoReflect": true,
|
|
89
|
+
"embedding": {
|
|
90
|
+
"provider": "api",
|
|
91
|
+
"model": "text-embedding-3-large",
|
|
92
|
+
"apiKey": "${EMBEDDING_API_KEY}",
|
|
93
|
+
"baseURL": "https://your-embedding-endpoint/v1",
|
|
94
|
+
"dimensions": 3072
|
|
95
|
+
},
|
|
96
|
+
"llm": {
|
|
97
|
+
"provider": "api",
|
|
98
|
+
"model": "gpt-4",
|
|
99
|
+
"apiKey": "${LLM_API_KEY}",
|
|
100
|
+
"baseURL": "https://your-llm-endpoint/v1"
|
|
101
|
+
},
|
|
102
|
+
"reranker": {
|
|
103
|
+
"provider": "api",
|
|
104
|
+
"model": "BAAI/bge-reranker-v2-m3",
|
|
105
|
+
"apiKey": "${RERANKER_API_KEY}",
|
|
106
|
+
"baseURL": "https://your-reranker-endpoint/v1/rerank"
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### 启动
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
openclaw config validate
|
|
119
|
+
openclaw gateway restart
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### 主Agent注入说明
|
|
123
|
+
|
|
124
|
+
首次接入后,建议把下面这段发给主 Agent,确保它会主动使用记忆工具:
|
|
125
|
+
|
|
126
|
+
```text
|
|
127
|
+
你已接入 Cortex Memory。请遵循以下规则:
|
|
128
|
+
1) 当用户询问历史对话、偏好、项目上下文时,先调用 search_memory 再回答。
|
|
129
|
+
2) 需要当前会话热上下文时调用 get_hot_context。
|
|
130
|
+
3) 需要自动召回相关记忆时调用 get_auto_context。
|
|
131
|
+
4) 在一件重要事情结束并形成明确结果后,再调用 store_event 记录(不要在过程进行中频繁记录)。
|
|
132
|
+
5) 需要实体关联关系时调用 query_graph。
|
|
133
|
+
6) 当任务经历“失败→调整→最终成功”时,优先用 store_event 记录失败原因与成功方案,再调用 reflect_memory 沉淀可复用规则。
|
|
134
|
+
7) 需要导入历史会话时调用 sync_memory。
|
|
135
|
+
8) 出现配置校验失败、记忆读写异常、检索结果异常或数据目录问题时,优先调用 diagnostics。
|
|
136
|
+
9) 同一任务内不要反复调用 store_event 或 reflect_memory;仅在关键节点或任务收尾时触发一次。
|
|
137
|
+
10) 不要臆造历史事实;无法确认时必须先检索。
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## 可用工具
|
|
141
|
+
|
|
142
|
+
### search_memory
|
|
143
|
+
|
|
144
|
+
语义搜索长期记忆。
|
|
145
|
+
|
|
146
|
+
**参数:**
|
|
147
|
+
| 参数 | 类型 | 必需 | 说明 |
|
|
148
|
+
|------|------|------|------|
|
|
149
|
+
| query | string | 是 | 搜索查询 |
|
|
150
|
+
| top_k | number | 否 | 返回数量,默认 3 |
|
|
151
|
+
|
|
152
|
+
### store_event
|
|
153
|
+
|
|
154
|
+
写入事件摘要到归档记忆。
|
|
155
|
+
|
|
156
|
+
**参数:**
|
|
157
|
+
| 参数 | 类型 | 必需 | 说明 |
|
|
158
|
+
|------|------|------|------|
|
|
159
|
+
| summary | string | 是 | 事件摘要 |
|
|
160
|
+
| entities | array | 否 | 相关实体列表 |
|
|
161
|
+
| outcome | string | 否 | 事件结果 |
|
|
162
|
+
| relations | array | 否 | 实体关系 |
|
|
163
|
+
|
|
164
|
+
### query_graph
|
|
165
|
+
|
|
166
|
+
查询归档事件中的实体共现关系。
|
|
167
|
+
|
|
168
|
+
**参数:**
|
|
169
|
+
| 参数 | 类型 | 必需 | 说明 |
|
|
170
|
+
|------|------|------|------|
|
|
171
|
+
| entity | string | 是 | 实体名称 |
|
|
172
|
+
|
|
173
|
+
### get_hot_context
|
|
174
|
+
|
|
175
|
+
获取当前热上下文(CORTEX_RULES.md + 近期会话)。
|
|
176
|
+
|
|
177
|
+
**参数:**
|
|
178
|
+
| 参数 | 类型 | 必需 | 说明 |
|
|
179
|
+
|------|------|------|------|
|
|
180
|
+
| limit | number | 否 | 最大条目数,默认 20 |
|
|
181
|
+
|
|
182
|
+
### get_auto_context
|
|
183
|
+
|
|
184
|
+
自动检索相关记忆(基于近期消息)。
|
|
185
|
+
|
|
186
|
+
**参数:**
|
|
187
|
+
| 参数 | 类型 | 必需 | 说明 |
|
|
188
|
+
|------|------|------|------|
|
|
189
|
+
| include_hot | boolean | 否 | 包含热上下文,默认 true |
|
|
190
|
+
|
|
191
|
+
### reflect_memory
|
|
192
|
+
|
|
193
|
+
将归档事件反思为规则并写入 `CORTEX_RULES.md`。
|
|
194
|
+
|
|
195
|
+
### sync_memory
|
|
196
|
+
|
|
197
|
+
增量同步会话记录到本地记忆(无参数)。
|
|
198
|
+
|
|
199
|
+
### delete_memory
|
|
200
|
+
|
|
201
|
+
删除指定记忆。
|
|
202
|
+
|
|
203
|
+
**参数:**
|
|
204
|
+
| 参数 | 类型 | 必需 | 说明 |
|
|
205
|
+
|------|------|------|------|
|
|
206
|
+
| memory_id | string | 是 | 记忆 ID |
|
|
207
|
+
|
|
208
|
+
### diagnostics
|
|
209
|
+
|
|
210
|
+
运行本地系统诊断,检查数据目录与基础状态。
|
|
211
|
+
|
|
212
|
+
## 配置选项
|
|
213
|
+
|
|
214
|
+
| 选项 | 必需 | 默认值 | 说明 |
|
|
215
|
+
|------|------|--------|------|
|
|
216
|
+
| embedding.provider | 是 | - | `api`(推荐) |
|
|
217
|
+
| embedding.model | 是 | - | Embedding 模型名称 |
|
|
218
|
+
| embedding.dimensions | 否 | 3072 | 向量维度 |
|
|
219
|
+
| embedding.apiKey | 是 | ${EMBEDDING_API_KEY} | Embedding API Key |
|
|
220
|
+
| embedding.baseURL | 是 | - | Embedding API 端点 |
|
|
221
|
+
| llm.provider | 是 | - | `api`(推荐) |
|
|
222
|
+
| llm.model | 是 | - | LLM 模型名称 |
|
|
223
|
+
| llm.apiKey | 是 | ${LLM_API_KEY} | LLM API Key |
|
|
224
|
+
| llm.baseURL | 是 | - | LLM API 端点 |
|
|
225
|
+
| reranker.provider | 否 | - | `api`(推荐) |
|
|
226
|
+
| reranker.model | 是 | - | Reranker 模型 |
|
|
227
|
+
| reranker.apiKey | 是 | ${RERANKER_API_KEY} | Reranker API Key |
|
|
228
|
+
| reranker.baseURL | 是 | - | Reranker API 端点 |
|
|
229
|
+
| dbPath | 否 | `<plugin-dir>/data/memory` | 记忆目录路径 |
|
|
230
|
+
| engineMode | 否 | `ts` | 固定为 TS 引擎 |
|
|
231
|
+
| autoSync | 否 | true | 会话结束自动同步 |
|
|
232
|
+
| autoReflect | 否 | false | 自动触发反思 |
|
|
233
|
+
|
|
234
|
+
## 数据文件
|
|
235
|
+
|
|
236
|
+
| 路径 | 说明 |
|
|
237
|
+
|------|------|
|
|
238
|
+
| `<dbPath>/MEMORY.md` | 记忆说明文件 |
|
|
239
|
+
| `<dbPath>/CORTEX_RULES.md` | 规则文件 |
|
|
240
|
+
| `<dbPath>/sessions/active/sessions.jsonl` | 活跃会话记忆 |
|
|
241
|
+
| `<dbPath>/sessions/archive/sessions.jsonl` | 归档事件 |
|
|
242
|
+
| `<dbPath>/.sync_state.json` | 同步增量状态 |
|
|
243
|
+
| `<dbPath>/.session_end_state.json` | session_end 幂等状态 |
|
|
244
|
+
| `<dbPath>/.rule_store_state.json` | 规则去重状态 |
|
|
245
|
+
|
|
246
|
+
## 错误处理
|
|
247
|
+
|
|
248
|
+
| 错误代码 | 说明 | 处理方式 |
|
|
249
|
+
|----------|------|----------|
|
|
250
|
+
| E203 | 重复记忆 | 相似度 > 0.95,已跳过 |
|
|
251
|
+
| E204 | 质量评分过低 | 信息密度不足,未存储 |
|
|
252
|
+
|
|
253
|
+
## 相关文件
|
|
254
|
+
|
|
255
|
+
- `index.ts` - 插件入口与工具注册
|
|
256
|
+
- `src/engine/ts_engine.ts` - TS 引擎实现
|
|
257
|
+
- `src/store/read_store.ts` - 读取能力
|
|
258
|
+
- `src/store/write_store.ts` - 写入能力
|
|
259
|
+
|
|
260
|
+
## 依赖
|
|
261
|
+
|
|
262
|
+
- Node.js >= 22
|
|
263
|
+
- OPENAI_API_KEY(或兼容 API 配置)
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import type { EngineMode } from "./src/engine/types";
|
|
2
|
+
interface EmbeddingConfig {
|
|
3
|
+
provider: string;
|
|
4
|
+
model: string;
|
|
5
|
+
apiKey?: string;
|
|
6
|
+
baseURL?: string;
|
|
7
|
+
baseUrl?: string;
|
|
8
|
+
dimensions?: number;
|
|
9
|
+
}
|
|
10
|
+
interface LLMConfig {
|
|
11
|
+
provider: string;
|
|
12
|
+
model: string;
|
|
13
|
+
apiKey?: string;
|
|
14
|
+
baseURL?: string;
|
|
15
|
+
baseUrl?: string;
|
|
16
|
+
}
|
|
17
|
+
interface RerankerConfig {
|
|
18
|
+
provider?: string;
|
|
19
|
+
model: string;
|
|
20
|
+
apiKey?: string;
|
|
21
|
+
baseURL?: string;
|
|
22
|
+
baseUrl?: string;
|
|
23
|
+
}
|
|
24
|
+
interface CortexMemoryConfig {
|
|
25
|
+
enabled?: boolean;
|
|
26
|
+
embedding: EmbeddingConfig;
|
|
27
|
+
llm: LLMConfig;
|
|
28
|
+
reranker: RerankerConfig;
|
|
29
|
+
dbPath?: string;
|
|
30
|
+
autoSync?: boolean;
|
|
31
|
+
autoReflect?: boolean;
|
|
32
|
+
fallbackToBuiltin?: boolean;
|
|
33
|
+
apiUrl?: string;
|
|
34
|
+
engineMode?: EngineMode;
|
|
35
|
+
}
|
|
36
|
+
interface ToolContext {
|
|
37
|
+
agentId: string;
|
|
38
|
+
sessionId?: string;
|
|
39
|
+
workspaceId: string;
|
|
40
|
+
}
|
|
41
|
+
interface ToolResult {
|
|
42
|
+
success: boolean;
|
|
43
|
+
data?: unknown;
|
|
44
|
+
error?: string;
|
|
45
|
+
errorCode?: string;
|
|
46
|
+
}
|
|
47
|
+
interface BuiltinMemory {
|
|
48
|
+
search: (query: string, limit?: number) => Promise<unknown[]>;
|
|
49
|
+
store: (content: string, metadata?: Record<string, unknown>) => Promise<string>;
|
|
50
|
+
delete: (id: string) => Promise<boolean>;
|
|
51
|
+
}
|
|
52
|
+
interface Logger {
|
|
53
|
+
debug: (message: string, ...args: unknown[]) => void;
|
|
54
|
+
info: (message: string, ...args: unknown[]) => void;
|
|
55
|
+
warn: (message: string, ...args: unknown[]) => void;
|
|
56
|
+
error: (message: string, ...args: unknown[]) => void;
|
|
57
|
+
}
|
|
58
|
+
interface OpenClawPluginApi {
|
|
59
|
+
registerTool(tool: {
|
|
60
|
+
name: string;
|
|
61
|
+
description: string;
|
|
62
|
+
parameters: Record<string, unknown>;
|
|
63
|
+
execute: (params: {
|
|
64
|
+
args: Record<string, unknown>;
|
|
65
|
+
context: ToolContext;
|
|
66
|
+
}) => Promise<ToolResult>;
|
|
67
|
+
}): void;
|
|
68
|
+
unregisterTool?(name: string): void;
|
|
69
|
+
registerHook(hook: {
|
|
70
|
+
event: string;
|
|
71
|
+
handler: (payload: unknown, context: ToolContext) => Promise<void>;
|
|
72
|
+
}): void;
|
|
73
|
+
on(event: string, handler: (payload: unknown, context: ToolContext) => Promise<void> | void, options?: {
|
|
74
|
+
priority?: number;
|
|
75
|
+
}): void;
|
|
76
|
+
off?(event: string, handler: (payload: unknown, context: ToolContext) => Promise<void> | void): void;
|
|
77
|
+
unregisterHook?(event: string): void;
|
|
78
|
+
getLogger?(): Logger;
|
|
79
|
+
getBuiltinMemory?(): BuiltinMemory;
|
|
80
|
+
}
|
|
81
|
+
export declare function enable(): Promise<void>;
|
|
82
|
+
export declare function disable(): Promise<void>;
|
|
83
|
+
export declare function getStatus(): {
|
|
84
|
+
enabled: boolean;
|
|
85
|
+
serviceRunning: boolean;
|
|
86
|
+
};
|
|
87
|
+
export declare function unregister(): Promise<void>;
|
|
88
|
+
export declare function register(pluginApi: OpenClawPluginApi, userConfig?: Partial<CortexMemoryConfig>): void;
|
|
89
|
+
export {};
|
|
90
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}
|