imprint-mcp 2.0.0__tar.gz

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.
Files changed (54) hide show
  1. imprint_mcp-2.0.0/PKG-INFO +346 -0
  2. imprint_mcp-2.0.0/README.md +329 -0
  3. imprint_mcp-2.0.0/pyproject.toml +38 -0
  4. imprint_mcp-2.0.0/setup.cfg +4 -0
  5. imprint_mcp-2.0.0/src/imprint_mcp/__init__.py +6 -0
  6. imprint_mcp-2.0.0/src/imprint_mcp/__main__.py +8 -0
  7. imprint_mcp-2.0.0/src/imprint_mcp/cli.py +207 -0
  8. imprint_mcp-2.0.0/src/imprint_mcp/config.py +63 -0
  9. imprint_mcp-2.0.0/src/imprint_mcp/core/__init__.py +2 -0
  10. imprint_mcp-2.0.0/src/imprint_mcp/core/hint_extractor.py +41 -0
  11. imprint_mcp-2.0.0/src/imprint_mcp/core/recall_engine.py +253 -0
  12. imprint_mcp-2.0.0/src/imprint_mcp/core/scoring.py +56 -0
  13. imprint_mcp-2.0.0/src/imprint_mcp/core/token_budget.py +68 -0
  14. imprint_mcp-2.0.0/src/imprint_mcp/core/tokenizer.py +70 -0
  15. imprint_mcp-2.0.0/src/imprint_mcp/core/write_engine.py +46 -0
  16. imprint_mcp-2.0.0/src/imprint_mcp/errors.py +23 -0
  17. imprint_mcp-2.0.0/src/imprint_mcp/models.py +111 -0
  18. imprint_mcp-2.0.0/src/imprint_mcp/security/__init__.py +2 -0
  19. imprint_mcp-2.0.0/src/imprint_mcp/security/sandbox.py +43 -0
  20. imprint_mcp-2.0.0/src/imprint_mcp/security/validation.py +166 -0
  21. imprint_mcp-2.0.0/src/imprint_mcp/server.py +404 -0
  22. imprint_mcp-2.0.0/src/imprint_mcp/storage/__init__.py +2 -0
  23. imprint_mcp-2.0.0/src/imprint_mcp/storage/event_store.py +96 -0
  24. imprint_mcp-2.0.0/src/imprint_mcp/storage/index_store.py +626 -0
  25. imprint_mcp-2.0.0/src/imprint_mcp/storage/reindexer.py +38 -0
  26. imprint_mcp-2.0.0/src/imprint_mcp/storage/state_store.py +78 -0
  27. imprint_mcp-2.0.0/src/imprint_mcp/tools/__init__.py +2 -0
  28. imprint_mcp-2.0.0/src/imprint_mcp/tools/append.py +9 -0
  29. imprint_mcp-2.0.0/src/imprint_mcp/tools/query.py +31 -0
  30. imprint_mcp-2.0.0/src/imprint_mcp/tools/recall.py +29 -0
  31. imprint_mcp-2.0.0/src/imprint_mcp/tools/save.py +76 -0
  32. imprint_mcp-2.0.0/src/imprint_mcp/tools/stats.py +8 -0
  33. imprint_mcp-2.0.0/src/imprint_mcp/tools/upsert_state.py +13 -0
  34. imprint_mcp-2.0.0/src/imprint_mcp.egg-info/PKG-INFO +346 -0
  35. imprint_mcp-2.0.0/src/imprint_mcp.egg-info/SOURCES.txt +52 -0
  36. imprint_mcp-2.0.0/src/imprint_mcp.egg-info/dependency_links.txt +1 -0
  37. imprint_mcp-2.0.0/src/imprint_mcp.egg-info/entry_points.txt +2 -0
  38. imprint_mcp-2.0.0/src/imprint_mcp.egg-info/requires.txt +10 -0
  39. imprint_mcp-2.0.0/src/imprint_mcp.egg-info/top_level.txt +1 -0
  40. imprint_mcp-2.0.0/tests/test_cli.py +45 -0
  41. imprint_mcp-2.0.0/tests/test_event_store.py +17 -0
  42. imprint_mcp-2.0.0/tests/test_index_store.py +74 -0
  43. imprint_mcp-2.0.0/tests/test_models.py +9 -0
  44. imprint_mcp-2.0.0/tests/test_recall_engine.py +162 -0
  45. imprint_mcp-2.0.0/tests/test_reindexer.py +25 -0
  46. imprint_mcp-2.0.0/tests/test_resource.py +40 -0
  47. imprint_mcp-2.0.0/tests/test_sandbox.py +20 -0
  48. imprint_mcp-2.0.0/tests/test_save.py +75 -0
  49. imprint_mcp-2.0.0/tests/test_scoring.py +24 -0
  50. imprint_mcp-2.0.0/tests/test_state_store.py +15 -0
  51. imprint_mcp-2.0.0/tests/test_token_budget.py +20 -0
  52. imprint_mcp-2.0.0/tests/test_tokenizer.py +24 -0
  53. imprint_mcp-2.0.0/tests/test_validation.py +24 -0
  54. imprint_mcp-2.0.0/tests/test_write_engine.py +10 -0
@@ -0,0 +1,346 @@
1
+ Metadata-Version: 2.4
2
+ Name: imprint-mcp
3
+ Version: 2.0.0
4
+ Summary: Local-first persistent long-term memory MCP server
5
+ License: MIT
6
+ Requires-Python: >=3.11
7
+ Description-Content-Type: text/markdown
8
+ Requires-Dist: mcp>=1.26.0
9
+ Requires-Dist: jsonschema>=4.20.0
10
+ Requires-Dist: jieba>=0.42
11
+ Provides-Extra: dev
12
+ Requires-Dist: pytest>=8.0; extra == "dev"
13
+ Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
14
+ Requires-Dist: pytest-cov>=5.0; extra == "dev"
15
+ Requires-Dist: ruff>=0.8; extra == "dev"
16
+ Requires-Dist: mypy>=1.13; extra == "dev"
17
+
18
+ # Imprint MCP
19
+
20
+ 本地优先的持久化长期记忆 MCP Server。让 AI Agent 跨会话、跨项目记住关键事实。
21
+
22
+ ## 特性
23
+
24
+ - **本地优先** — 数据存在本地,不依赖云服务
25
+ - **极轻量** — 仅 3 个运行时依赖(mcp, jsonschema, jieba)
26
+ - **MCP 原生** — 兼容所有 MCP Client(Claude Code、Cursor、Codex 等)
27
+ - **JSONL 真相源** — 人类可读、Git 友好、可迁移
28
+ - **中文原生支持** — jieba 预分词,中文召回准确率大幅提升
29
+ - **Content-hash 去重** — SHA-256 写入时自动去重
30
+ - **Token 预算控制** — 可配置输出上限,默认不限制
31
+ - **多项目隔离** — project_id 列级隔离,scope=user 跨项目共享
32
+
33
+ ## 记忆如何工作
34
+
35
+ ### 记忆提取 — 三层保障
36
+
37
+ | 层级 | 机制 | 可靠性 | 说明 |
38
+ |------|------|--------|------|
39
+ | **Layer 1** | MCP Resource 自动注入 | 最高 | Client 连接时自动拉取 `memory://project-context`,零依赖 Agent 行为 |
40
+ | **Layer 2** | Tool description 引导 | 高 | `memory_recall` 描述中标注 "IMPORTANT: Call at START of every task" |
41
+ | **Layer 3** | Agent 提示词规则 | 中 | CLAUDE.md / Rules 中的自动触发规则 |
42
+
43
+ 支持 MCP Resources 的 Client(Claude Code、Cursor 等)连接即加载最近高重要度记忆 + 任务状态,
44
+ 不需要 Agent 主动调用任何工具。
45
+
46
+ ### 记忆写入 — 用户感知
47
+
48
+ Agent 调用 `memory_save` 时用户可以看到工具调用(MCP 协议限制,无法静默)。
49
+ 控制策略:
50
+
51
+ - content-hash 去重避免重复写入
52
+ - Tool description 明确标注 "只保存有长期价值的信息"
53
+ - Agent 提示词限制写入频率(每会话 1-3 次为合理范围)
54
+
55
+ ### 记忆管理 — CLI 命令
56
+
57
+ ```bash
58
+ # 查看最近记忆
59
+ imprint-mcp list # 最近 20 条
60
+ imprint-mcp list --type gotcha # 按类型过滤
61
+ imprint-mcp list --tags nginx,sse # 按标签过滤
62
+ imprint-mcp list -v # 详细模式
63
+
64
+ # 全文搜索
65
+ imprint-mcp search "SSE 流延迟"
66
+
67
+ # 查看单条详情(完整 JSON)
68
+ imprint-mcp show mem_20260402_0001
69
+
70
+ # 归档记忆(软删除)
71
+ imprint-mcp delete mem_20260402_0001
72
+
73
+ # 统计信息
74
+ imprint-mcp stats
75
+
76
+ # 导出所有记忆(备份/迁移)
77
+ imprint-mcp export > backup.json
78
+
79
+ # 启动 MCP Server(默认行为)
80
+ imprint-mcp # 等价于 imprint-mcp serve
81
+ ```
82
+
83
+ ## 快速开始
84
+
85
+ ### 1. 安装
86
+
87
+ ```bash
88
+ # 方式 A: npm(推荐,自动解析 Python 环境)
89
+ npm install -g imprint-mcp
90
+
91
+ # 方式 B: pip
92
+ pip install imprint-mcp
93
+
94
+ # 方式 C: 源码开发
95
+ git clone <repo-url> && cd imprint_mcp
96
+ pip install -e .
97
+
98
+ # 验证
99
+ imprint-mcp --help
100
+ ```
101
+
102
+ ### 2. 配置 MCP Client
103
+
104
+ **Claude Code** — 在项目根目录创建 `.mcp.json`:
105
+
106
+ ```json
107
+ {
108
+ "mcpServers": {
109
+ "imprint-mcp": {
110
+ "command": "npx",
111
+ "args": ["imprint-mcp"]
112
+ }
113
+ }
114
+ }
115
+ ```
116
+
117
+ 或直接指向 Python 入口:
118
+
119
+ ```json
120
+ {
121
+ "mcpServers": {
122
+ "imprint-mcp": {
123
+ "command": "/path/to/imprint_mcp/.venv/bin/imprint-mcp"
124
+ }
125
+ }
126
+ }
127
+ ```
128
+
129
+ > `IMPRINT_MCP_PROJECT_ID` 可选 — 不设则自动从 git repo root 推导,与 Claude Code 行为一致。
130
+
131
+ **Codex** — 在 `~/.codex/config.toml` 中添加:
132
+
133
+ ```toml
134
+ [mcp_servers.imprint-mcp]
135
+ command = "npx"
136
+ args = ["imprint-mcp"]
137
+ ```
138
+
139
+ ### 3. 配置 Agent 提示词
140
+
141
+ 将以下规则添加到 Agent 的系统提示词(CLAUDE.md / `.claude/rules/` / System Prompt),
142
+ 让 Agent 知道何时自动调用记忆工具。
143
+
144
+ <details>
145
+ <summary>完整版(推荐嵌入 CLAUDE.md)— 点击展开</summary>
146
+
147
+ ```markdown
148
+ # Imprint MCP 自动记忆管理
149
+
150
+ ## 自动触发规则
151
+
152
+ ### 会话开始(必做)
153
+ 每次接收新任务时,第一步调用:
154
+ memory_recall(query=<任务描述>, max_tokens=2000)
155
+ 将返回的 memories 和 state_context 作为工作背景。
156
+
157
+ ### 及时写入
158
+ | 场景 | type | scope | importance |
159
+ |------|------|-------|------------|
160
+ | 确认技术事实 | fact | project | 0.5 |
161
+ | 踩坑/非直觉行为 | gotcha | project | 0.9 |
162
+ | 技术决策 | decision | project | 0.8 |
163
+ | 用户偏好 | preference | user | 0.7 |
164
+ | 硬约束条件 | constraint | project | 0.8 |
165
+ | API 行为/限制 | api_note | project | 0.6 |
166
+
167
+ 写入格式:
168
+ memory_save(text: "<完整描述>", type: "<类型>", tags: ["<关键词>"], importance: N)
169
+
170
+ memory_save 内置 content-hash 去重,无需写入前手动检查。
171
+
172
+ ### 状态同步
173
+ 任务目标或进展变化时:
174
+ memory_upsert_state(namespace: "current_task", value: {
175
+ goal: "<当前目标>", status: "in_progress", next_steps: ["<下一步>"]
176
+ })
177
+
178
+ ### 场景化召回
179
+ - 调试排错:memory_recall(query=<错误信息>) — 系统自动提升 gotcha 权重
180
+ - 架构讨论:memory_recall(query=<设计主题>) — 系统自动提升 decision 权重
181
+ - 精确过滤:memory_recall(type="gotcha", tags=["nginx"]) — 无需 query,纯结构化过滤
182
+
183
+ ### 不做
184
+ - 不要每句话都写记忆,只记有长期价值的信息
185
+ - 不要写模糊内容,要写具体、可操作的事实
186
+ - 不要忽略 tags,它们是检索的关键
187
+ - 不要把临时信息存为 project scope,用 session scope
188
+ ```
189
+
190
+ </details>
191
+
192
+ <details>
193
+ <summary>精简版(适合嵌入 Rules 文件)— 点击展开</summary>
194
+
195
+ ```markdown
196
+ # Imprint MCP 自动记忆管理
197
+
198
+ ## 会话开始(必做)
199
+ memory_recall(query=<任务描述>, max_tokens=2000)
200
+
201
+ ## 及时写入
202
+ | 场景 | type | importance |
203
+ |------|------|------------|
204
+ | 确认技术事实 | fact | 0.5 |
205
+ | 踩坑 | gotcha | 0.9 |
206
+ | 技术决策 | decision | 0.8 |
207
+ | 用户偏好 | preference (scope=user) | 0.7 |
208
+
209
+ 写入:memory_save(text: "...", type: "...", tags: [...])
210
+ 内置去重,无需手动检查。
211
+
212
+ ## 状态同步
213
+ memory_upsert_state(namespace: "current_task", value: { goal, status, next_steps })
214
+
215
+ ## 场景化召回
216
+ - 调试:memory_recall(query=<错误信息>) — gotcha 权重自动提升
217
+ - 精确:memory_recall(type="gotcha", tags=["nginx"]) — 纯过滤
218
+ ```
219
+
220
+ </details>
221
+
222
+ ### 4. 验证
223
+
224
+ 配置完成后,在 Agent 对话中测试:
225
+
226
+ ```
227
+ 你: 记住一下,这个项目用的是 FastAPI + SQLite 技术栈
228
+ Agent 应调用: memory_save(text="这个项目用的是 FastAPI + SQLite 技术栈", type="fact", ...)
229
+
230
+ 你: 回忆一下这个项目的技术栈
231
+ Agent 应调用: memory_recall(query="项目技术栈")
232
+ ```
233
+
234
+ 检查数据是否写入成功:
235
+
236
+ ```bash
237
+ # 用 CLI 查看
238
+ imprint-mcp list
239
+ imprint-mcp stats
240
+
241
+ # 或直接看原始文件
242
+ cat ~/.memory/events/*.jsonl | python -m json.tool
243
+ ```
244
+
245
+ ## MCP 工具参考
246
+
247
+ ### memory_save(推荐写入方式)
248
+
249
+ 只需传入文本,服务端自动提取 tags、生成结构化字段,内置 content-hash 去重。
250
+
251
+ ```
252
+ memory_save(
253
+ text: "Nginx 默认缓冲 SSE 流,需要关闭 proxy_buffering",
254
+ type: "gotcha", # 可选 hint
255
+ tags: ["nginx", "sse"], # 可选 hint,不传则自动提取
256
+ importance: 0.9 # 可选,默认 0.5
257
+ )
258
+ ```
259
+
260
+ ### memory_recall(语义召回 + 结构化过滤)
261
+
262
+ 召回与当前问题最相关的记忆。支持纯文本搜索、纯过滤、或两者组合。
263
+
264
+ ```
265
+ # 语义搜索
266
+ memory_recall(query: "SSE 流为什么有延迟", max_tokens: 2000)
267
+
268
+ # 纯结构化过滤(query 可省略)
269
+ memory_recall(type: "gotcha", tags: ["nginx"], status: "active")
270
+
271
+ # 组合:搜索 + 过滤
272
+ memory_recall(query: "缓冲问题", type: "gotcha", tags: ["nginx"])
273
+ ```
274
+
275
+ 全部参数:`query`, `type`, `tags`, `entity_refs`, `status`, `scope`, `project_id`, `max_tokens`, `limit`
276
+
277
+ ### memory_upsert_state
278
+
279
+ 更新状态快照(当前任务、项目摘要等)。
280
+
281
+ ```
282
+ memory_upsert_state(
283
+ namespace: "current_task",
284
+ value: { goal: "实现 memory MCP v2", status: "in_progress" }
285
+ )
286
+ ```
287
+
288
+ ### memory_stats
289
+
290
+ 返回记忆库统计信息。
291
+
292
+ ```
293
+ memory_stats()
294
+ memory_stats(project_id: "my-project")
295
+ ```
296
+
297
+ ### memory_append(批量结构化写入)
298
+
299
+ 批量写入多条完整结构化记忆事件。每条需提供完整 schema 字段。
300
+
301
+ ```
302
+ memory_append(entries=[{
303
+ type: "gotcha", scope: "project",
304
+ title: "Nginx 缓冲 SSE", content: "Nginx 默认缓冲 SSE 流...",
305
+ source: { kind: "agent" }, tags: ["nginx", "sse"]
306
+ }])
307
+ ```
308
+
309
+ ## 环境变量
310
+
311
+ | 变量 | 默认值 | 说明 |
312
+ |------|--------|------|
313
+ | `IMPRINT_MCP_DATA_DIR` | `~/.memory` | 数据存储目录 |
314
+ | `IMPRINT_MCP_PROJECT_ID` | 自动从 CWD 推导 | 当前项目标识(可选,不设则自动推导) |
315
+ | `IMPRINT_MCP_MAX_TOKENS` | `0` | recall 输出 Token 上限,0 = 不限制 |
316
+ | `IMPRINT_MCP_STATE_BUDGET` | `500` | state_context Token 预算 |
317
+ | `IMPRINT_MCP_FTS_LIMIT` | `50` | FTS5 检索返回上限 |
318
+ | `IMPRINT_MCP_STRUCTURED_LIMIT` | `50` | 结构化过滤返回上限 |
319
+ | `IMPRINT_MCP_RRF_K` | `60` | RRF 融合常量 |
320
+
321
+ ## 数据存储
322
+
323
+ ```
324
+ ~/.memory/
325
+ ├── events/
326
+ │ └── 2026-04.jsonl # 按月分文件,append-only(唯一事实源)
327
+ ├── state/
328
+ │ ├── current_task.json # 状态快照
329
+ │ └── project_summary.json
330
+ └── index/
331
+ └── memory_fts.db # SQLite FTS5 索引(可从 events 重建)
332
+ ```
333
+
334
+ - `events/` — JSONL 格式,永不原地修改,`cat` 即可查看
335
+ - `index/` — 读模型,删除后重启服务会自动从 events 重建
336
+ - `state/` — 命名空间隔离的 JSON 快照
337
+ - 多项目通过 `project_id` 列隔离,`scope=user` 的记忆 `project_id` 为 `__global__`(跨项目可见)
338
+
339
+ ## 版本
340
+
341
+ - **v1.0** — 写入/索引/召回闭环
342
+ - **v2.0**(当前)— 轻量写入 + 中文分词 + 多项目隔离 + content-hash 去重 + MCP Resource 自动注入 + CLI 管理工具
343
+
344
+ ## License
345
+
346
+ MIT
@@ -0,0 +1,329 @@
1
+ # Imprint MCP
2
+
3
+ 本地优先的持久化长期记忆 MCP Server。让 AI Agent 跨会话、跨项目记住关键事实。
4
+
5
+ ## 特性
6
+
7
+ - **本地优先** — 数据存在本地,不依赖云服务
8
+ - **极轻量** — 仅 3 个运行时依赖(mcp, jsonschema, jieba)
9
+ - **MCP 原生** — 兼容所有 MCP Client(Claude Code、Cursor、Codex 等)
10
+ - **JSONL 真相源** — 人类可读、Git 友好、可迁移
11
+ - **中文原生支持** — jieba 预分词,中文召回准确率大幅提升
12
+ - **Content-hash 去重** — SHA-256 写入时自动去重
13
+ - **Token 预算控制** — 可配置输出上限,默认不限制
14
+ - **多项目隔离** — project_id 列级隔离,scope=user 跨项目共享
15
+
16
+ ## 记忆如何工作
17
+
18
+ ### 记忆提取 — 三层保障
19
+
20
+ | 层级 | 机制 | 可靠性 | 说明 |
21
+ |------|------|--------|------|
22
+ | **Layer 1** | MCP Resource 自动注入 | 最高 | Client 连接时自动拉取 `memory://project-context`,零依赖 Agent 行为 |
23
+ | **Layer 2** | Tool description 引导 | 高 | `memory_recall` 描述中标注 "IMPORTANT: Call at START of every task" |
24
+ | **Layer 3** | Agent 提示词规则 | 中 | CLAUDE.md / Rules 中的自动触发规则 |
25
+
26
+ 支持 MCP Resources 的 Client(Claude Code、Cursor 等)连接即加载最近高重要度记忆 + 任务状态,
27
+ 不需要 Agent 主动调用任何工具。
28
+
29
+ ### 记忆写入 — 用户感知
30
+
31
+ Agent 调用 `memory_save` 时用户可以看到工具调用(MCP 协议限制,无法静默)。
32
+ 控制策略:
33
+
34
+ - content-hash 去重避免重复写入
35
+ - Tool description 明确标注 "只保存有长期价值的信息"
36
+ - Agent 提示词限制写入频率(每会话 1-3 次为合理范围)
37
+
38
+ ### 记忆管理 — CLI 命令
39
+
40
+ ```bash
41
+ # 查看最近记忆
42
+ imprint-mcp list # 最近 20 条
43
+ imprint-mcp list --type gotcha # 按类型过滤
44
+ imprint-mcp list --tags nginx,sse # 按标签过滤
45
+ imprint-mcp list -v # 详细模式
46
+
47
+ # 全文搜索
48
+ imprint-mcp search "SSE 流延迟"
49
+
50
+ # 查看单条详情(完整 JSON)
51
+ imprint-mcp show mem_20260402_0001
52
+
53
+ # 归档记忆(软删除)
54
+ imprint-mcp delete mem_20260402_0001
55
+
56
+ # 统计信息
57
+ imprint-mcp stats
58
+
59
+ # 导出所有记忆(备份/迁移)
60
+ imprint-mcp export > backup.json
61
+
62
+ # 启动 MCP Server(默认行为)
63
+ imprint-mcp # 等价于 imprint-mcp serve
64
+ ```
65
+
66
+ ## 快速开始
67
+
68
+ ### 1. 安装
69
+
70
+ ```bash
71
+ # 方式 A: npm(推荐,自动解析 Python 环境)
72
+ npm install -g imprint-mcp
73
+
74
+ # 方式 B: pip
75
+ pip install imprint-mcp
76
+
77
+ # 方式 C: 源码开发
78
+ git clone <repo-url> && cd imprint_mcp
79
+ pip install -e .
80
+
81
+ # 验证
82
+ imprint-mcp --help
83
+ ```
84
+
85
+ ### 2. 配置 MCP Client
86
+
87
+ **Claude Code** — 在项目根目录创建 `.mcp.json`:
88
+
89
+ ```json
90
+ {
91
+ "mcpServers": {
92
+ "imprint-mcp": {
93
+ "command": "npx",
94
+ "args": ["imprint-mcp"]
95
+ }
96
+ }
97
+ }
98
+ ```
99
+
100
+ 或直接指向 Python 入口:
101
+
102
+ ```json
103
+ {
104
+ "mcpServers": {
105
+ "imprint-mcp": {
106
+ "command": "/path/to/imprint_mcp/.venv/bin/imprint-mcp"
107
+ }
108
+ }
109
+ }
110
+ ```
111
+
112
+ > `IMPRINT_MCP_PROJECT_ID` 可选 — 不设则自动从 git repo root 推导,与 Claude Code 行为一致。
113
+
114
+ **Codex** — 在 `~/.codex/config.toml` 中添加:
115
+
116
+ ```toml
117
+ [mcp_servers.imprint-mcp]
118
+ command = "npx"
119
+ args = ["imprint-mcp"]
120
+ ```
121
+
122
+ ### 3. 配置 Agent 提示词
123
+
124
+ 将以下规则添加到 Agent 的系统提示词(CLAUDE.md / `.claude/rules/` / System Prompt),
125
+ 让 Agent 知道何时自动调用记忆工具。
126
+
127
+ <details>
128
+ <summary>完整版(推荐嵌入 CLAUDE.md)— 点击展开</summary>
129
+
130
+ ```markdown
131
+ # Imprint MCP 自动记忆管理
132
+
133
+ ## 自动触发规则
134
+
135
+ ### 会话开始(必做)
136
+ 每次接收新任务时,第一步调用:
137
+ memory_recall(query=<任务描述>, max_tokens=2000)
138
+ 将返回的 memories 和 state_context 作为工作背景。
139
+
140
+ ### 及时写入
141
+ | 场景 | type | scope | importance |
142
+ |------|------|-------|------------|
143
+ | 确认技术事实 | fact | project | 0.5 |
144
+ | 踩坑/非直觉行为 | gotcha | project | 0.9 |
145
+ | 技术决策 | decision | project | 0.8 |
146
+ | 用户偏好 | preference | user | 0.7 |
147
+ | 硬约束条件 | constraint | project | 0.8 |
148
+ | API 行为/限制 | api_note | project | 0.6 |
149
+
150
+ 写入格式:
151
+ memory_save(text: "<完整描述>", type: "<类型>", tags: ["<关键词>"], importance: N)
152
+
153
+ memory_save 内置 content-hash 去重,无需写入前手动检查。
154
+
155
+ ### 状态同步
156
+ 任务目标或进展变化时:
157
+ memory_upsert_state(namespace: "current_task", value: {
158
+ goal: "<当前目标>", status: "in_progress", next_steps: ["<下一步>"]
159
+ })
160
+
161
+ ### 场景化召回
162
+ - 调试排错:memory_recall(query=<错误信息>) — 系统自动提升 gotcha 权重
163
+ - 架构讨论:memory_recall(query=<设计主题>) — 系统自动提升 decision 权重
164
+ - 精确过滤:memory_recall(type="gotcha", tags=["nginx"]) — 无需 query,纯结构化过滤
165
+
166
+ ### 不做
167
+ - 不要每句话都写记忆,只记有长期价值的信息
168
+ - 不要写模糊内容,要写具体、可操作的事实
169
+ - 不要忽略 tags,它们是检索的关键
170
+ - 不要把临时信息存为 project scope,用 session scope
171
+ ```
172
+
173
+ </details>
174
+
175
+ <details>
176
+ <summary>精简版(适合嵌入 Rules 文件)— 点击展开</summary>
177
+
178
+ ```markdown
179
+ # Imprint MCP 自动记忆管理
180
+
181
+ ## 会话开始(必做)
182
+ memory_recall(query=<任务描述>, max_tokens=2000)
183
+
184
+ ## 及时写入
185
+ | 场景 | type | importance |
186
+ |------|------|------------|
187
+ | 确认技术事实 | fact | 0.5 |
188
+ | 踩坑 | gotcha | 0.9 |
189
+ | 技术决策 | decision | 0.8 |
190
+ | 用户偏好 | preference (scope=user) | 0.7 |
191
+
192
+ 写入:memory_save(text: "...", type: "...", tags: [...])
193
+ 内置去重,无需手动检查。
194
+
195
+ ## 状态同步
196
+ memory_upsert_state(namespace: "current_task", value: { goal, status, next_steps })
197
+
198
+ ## 场景化召回
199
+ - 调试:memory_recall(query=<错误信息>) — gotcha 权重自动提升
200
+ - 精确:memory_recall(type="gotcha", tags=["nginx"]) — 纯过滤
201
+ ```
202
+
203
+ </details>
204
+
205
+ ### 4. 验证
206
+
207
+ 配置完成后,在 Agent 对话中测试:
208
+
209
+ ```
210
+ 你: 记住一下,这个项目用的是 FastAPI + SQLite 技术栈
211
+ Agent 应调用: memory_save(text="这个项目用的是 FastAPI + SQLite 技术栈", type="fact", ...)
212
+
213
+ 你: 回忆一下这个项目的技术栈
214
+ Agent 应调用: memory_recall(query="项目技术栈")
215
+ ```
216
+
217
+ 检查数据是否写入成功:
218
+
219
+ ```bash
220
+ # 用 CLI 查看
221
+ imprint-mcp list
222
+ imprint-mcp stats
223
+
224
+ # 或直接看原始文件
225
+ cat ~/.memory/events/*.jsonl | python -m json.tool
226
+ ```
227
+
228
+ ## MCP 工具参考
229
+
230
+ ### memory_save(推荐写入方式)
231
+
232
+ 只需传入文本,服务端自动提取 tags、生成结构化字段,内置 content-hash 去重。
233
+
234
+ ```
235
+ memory_save(
236
+ text: "Nginx 默认缓冲 SSE 流,需要关闭 proxy_buffering",
237
+ type: "gotcha", # 可选 hint
238
+ tags: ["nginx", "sse"], # 可选 hint,不传则自动提取
239
+ importance: 0.9 # 可选,默认 0.5
240
+ )
241
+ ```
242
+
243
+ ### memory_recall(语义召回 + 结构化过滤)
244
+
245
+ 召回与当前问题最相关的记忆。支持纯文本搜索、纯过滤、或两者组合。
246
+
247
+ ```
248
+ # 语义搜索
249
+ memory_recall(query: "SSE 流为什么有延迟", max_tokens: 2000)
250
+
251
+ # 纯结构化过滤(query 可省略)
252
+ memory_recall(type: "gotcha", tags: ["nginx"], status: "active")
253
+
254
+ # 组合:搜索 + 过滤
255
+ memory_recall(query: "缓冲问题", type: "gotcha", tags: ["nginx"])
256
+ ```
257
+
258
+ 全部参数:`query`, `type`, `tags`, `entity_refs`, `status`, `scope`, `project_id`, `max_tokens`, `limit`
259
+
260
+ ### memory_upsert_state
261
+
262
+ 更新状态快照(当前任务、项目摘要等)。
263
+
264
+ ```
265
+ memory_upsert_state(
266
+ namespace: "current_task",
267
+ value: { goal: "实现 memory MCP v2", status: "in_progress" }
268
+ )
269
+ ```
270
+
271
+ ### memory_stats
272
+
273
+ 返回记忆库统计信息。
274
+
275
+ ```
276
+ memory_stats()
277
+ memory_stats(project_id: "my-project")
278
+ ```
279
+
280
+ ### memory_append(批量结构化写入)
281
+
282
+ 批量写入多条完整结构化记忆事件。每条需提供完整 schema 字段。
283
+
284
+ ```
285
+ memory_append(entries=[{
286
+ type: "gotcha", scope: "project",
287
+ title: "Nginx 缓冲 SSE", content: "Nginx 默认缓冲 SSE 流...",
288
+ source: { kind: "agent" }, tags: ["nginx", "sse"]
289
+ }])
290
+ ```
291
+
292
+ ## 环境变量
293
+
294
+ | 变量 | 默认值 | 说明 |
295
+ |------|--------|------|
296
+ | `IMPRINT_MCP_DATA_DIR` | `~/.memory` | 数据存储目录 |
297
+ | `IMPRINT_MCP_PROJECT_ID` | 自动从 CWD 推导 | 当前项目标识(可选,不设则自动推导) |
298
+ | `IMPRINT_MCP_MAX_TOKENS` | `0` | recall 输出 Token 上限,0 = 不限制 |
299
+ | `IMPRINT_MCP_STATE_BUDGET` | `500` | state_context Token 预算 |
300
+ | `IMPRINT_MCP_FTS_LIMIT` | `50` | FTS5 检索返回上限 |
301
+ | `IMPRINT_MCP_STRUCTURED_LIMIT` | `50` | 结构化过滤返回上限 |
302
+ | `IMPRINT_MCP_RRF_K` | `60` | RRF 融合常量 |
303
+
304
+ ## 数据存储
305
+
306
+ ```
307
+ ~/.memory/
308
+ ├── events/
309
+ │ └── 2026-04.jsonl # 按月分文件,append-only(唯一事实源)
310
+ ├── state/
311
+ │ ├── current_task.json # 状态快照
312
+ │ └── project_summary.json
313
+ └── index/
314
+ └── memory_fts.db # SQLite FTS5 索引(可从 events 重建)
315
+ ```
316
+
317
+ - `events/` — JSONL 格式,永不原地修改,`cat` 即可查看
318
+ - `index/` — 读模型,删除后重启服务会自动从 events 重建
319
+ - `state/` — 命名空间隔离的 JSON 快照
320
+ - 多项目通过 `project_id` 列隔离,`scope=user` 的记忆 `project_id` 为 `__global__`(跨项目可见)
321
+
322
+ ## 版本
323
+
324
+ - **v1.0** — 写入/索引/召回闭环
325
+ - **v2.0**(当前)— 轻量写入 + 中文分词 + 多项目隔离 + content-hash 去重 + MCP Resource 自动注入 + CLI 管理工具
326
+
327
+ ## License
328
+
329
+ MIT
@@ -0,0 +1,38 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "imprint-mcp"
7
+ version = "2.0.0"
8
+ description = "Local-first persistent long-term memory MCP server"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = {text = "MIT"}
12
+ dependencies = [
13
+ "mcp>=1.26.0",
14
+ "jsonschema>=4.20.0",
15
+ "jieba>=0.42",
16
+ ]
17
+
18
+ [project.scripts]
19
+ imprint-mcp = "imprint_mcp.cli:cli_main"
20
+
21
+ [project.optional-dependencies]
22
+ dev = [
23
+ "pytest>=8.0",
24
+ "pytest-asyncio>=0.24",
25
+ "pytest-cov>=5.0",
26
+ "ruff>=0.8",
27
+ "mypy>=1.13",
28
+ ]
29
+
30
+ [tool.setuptools]
31
+ package-dir = {"" = "src"}
32
+
33
+ [tool.setuptools.packages.find]
34
+ where = ["src"]
35
+
36
+ [tool.pytest.ini_options]
37
+ asyncio_mode = "auto"
38
+ testpaths = ["tests"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+