ultra-memory 3.0.2 → 3.0.4

package/SKILL.md

@@ -1,229 +1,268 @@
 ---
 name: ultra-memory
 description: >
-  ultra-memory 是 AI Agent 的超长会话记忆系统。
-  【必须触发-中文】用户说：记住、别忘了、记录一下、上次我们做了什么、帮我回忆、继续上次、从上次继续、不要忘记、上次、跨会话、继续昨天、还有印象吗、我们上次讨论过、之前那个是怎么写的、还记得吗、这次不要忘、帮我追踪、帮我记着
-  【必须触发-英文】用户说：remember this、don't forget、recall、what did we do、pick up where we left off、continue from last time、memory、keep track、log this、what was that、remind me、context lost、continue from yesterday、from last session
-  【隐式触发】用户描述了一个持续性任务（开发某项目、处理某数据集、持续性工作），即使未说"记住"也必须初始化记忆；对话操作数超过30条；用户说"继续昨天的任务"/"接着上次做"
-  【不触发】单次问答（"帮我写个正则"、"查一下天气"）；纯代码补全、文件格式转换等无状态操作；用户已在 context 中能找到所需信息；用户明确说"不用记录"/"just this once"
+  ultra-memory 是多模型 AI 的超长会话记忆系统。
+  【必须触发-中文】用户说以下任意词或短语：记住、别忘了、记录一下、不要忘记、上次我们做了什么、帮我回忆、继续上次的、从上次继续、记忆、帮我记、追踪进度
+  【必须触发-英文】用户说以下任意词或短语：remember、don't forget、recall、what did we do、pick up where we left off、continue from last time、memory、keep track、track progress、log this
+  【隐式触发】用户消息描述了一个持续性任务且消息中包含项目名词（"开发X"、"处理Y数据集"、"完成Z功能"），即使没有明确说"记住"，也必须初始化记忆
+  【不触发】用户只问了一个问题且无后续任务；对话是单次咨询性质；用户说"随便聊聊"或类似表达；用户明确说"不用记录"
 ---
 
-# Ultra Memory — 超长会话记忆
+# Ultra Memory — 多模型记忆操作手册
 
 AI Agent 的操作记忆系统，每次操作后记录，跨会话持久化，可检索可进化。
 
 ## 前置说明
 
-所有脚本已存在于 `~/.ultra-memory/scripts/` 或技能目录下：
-- `init.py` — 初始化会话
-- `log_op.py` — 记录操作
-- `recall.py` — 检索记忆
-- `summarize.py` — 压缩摘要
-- `restore.py` — 恢复会话
-- `extract_entities.py` — 提取实体
+脚本已存在于 `$SKILL_DIR/scripts/` 目录，直接调用，不需要理解内部架构。
 
-存储根目录：`~/.ultra-memory/`（可配置环境变量 `ULTRA_MEMORY_HOME`）
-不需要理解内部架构，只需按步骤调用脚本。
+存储根目录：`$ULTRA_MEMORY_HOME`（默认 `~/.ultra-memory/`）
+会话 ID 由 init.py 自动生成，模型不需要自己生成。
 
 ---
 
 ## 步骤一：会话初始化
 
-### 触发时机
+### 触发条件
 
-首次与用户对话时，或用户提到记忆相关触发词时，立即执行。
+以下任意情况出现时，立即执行初始化命令：
+1. 首次与用户对话
+2. 用户说了记忆触发词（见 description）
+3. 用户描述持续性任务且包含项目名词（隐式触发）
 
 ### 执行命令
 
 ```bash
-python3 <skill_dir>/scripts/init.py --project <项目名>
+python3 $SKILL_DIR/scripts/init.py --project <项目名>
 ```
 
 **参数说明：**
-- `--project`：项目名称，用于跨会话分组。不填默认为 `default`。
+- `--project`：项目名称（用于跨会话分组）。从用户消息中提取项目名词作为值；无法提取则用 `default`。
 
-### 期望输出
+### 成功标志
+
+输出中必须同时包含以下两个信号：
 
-输出包含 `MEMORY_READY` 字样，表示会话初始化成功。同时输出 `session_id:`，记录该会话 ID。
+| 输出中的字符串 | 模型必须执行的动作 |
+|-------------|----------------|
+| `MEMORY_READY` | 确认初始化成功 |
+| `session_id: sess_xxxxx` | 从该行提取等号后面的值，保存为当前 `SESSION_ID` 变量 |
 
 ### 告知用户
 
-初始化成功后，立即告知用户：
-> "记忆系统已就绪（session_id: xxx），开始记录本次操作。"
+> "记忆系统已就绪（session_id: sess_xxxxx），开始记录本次操作。"
 
 ---
 
 ## 步骤二：操作记录
 
-**每次**以下任意事件发生时，立即调用 `log_op.py` 追加写入 ops.jsonl。
+### 触发条件
 
-### 操作类型与命令对照表
+**每次**用户与 AI 之间发生以下任意事件时，立即执行记录命令：
 
-| 事件 | op_type | 命令示例 |
-|------|---------|---------|
-| 执行了 shell 命令 | `bash_exec` | `python3 log_op.py --session <id> --type bash_exec --summary "执行了..." --detail '{"cmd":"...","exit_code":0}'` |
-| 创建或修改了文件 | `file_write` | `python3 log_op.py --session <id> --type file_write --summary "创建了..." --detail '{"path":"..."}'` |
-| 读取了文件 | `file_read` | `python3 log_op.py --session <id> --type file_read --summary "读取了..." --detail '{"path":"..."}'` |
-| 进行了重要推理 | `reasoning` | `python3 log_op.py --session <id> --type reasoning --summary "决定用..." --detail '{"confidence":0.9}'` |
-| 做出了关键决策 | `decision` | `python3 log_op.py --session <id> --type decision --summary "选用X方案" --detail '{"rationale":"..."}'` |
-| 发生了错误或回退 | `error` | `python3 log_op.py --session <id> --type error --summary "报错..." --detail '{"traceback":"..."}'` |
-| 用户给了新指令 | `user_instruction` | `python3 log_op.py --session <id> --type user_instruction --summary "用户要求..."` |
-| 某个目标已完成 | `milestone` | `python3 log_op.py --session <id> --type milestone --summary "数据清洗模块完成"` |
+| 事件 | op_type | 命令 |
+|------|---------|------|
+| 执行了 shell 命令 | `bash_exec` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type bash_exec --summary "<一句话描述>" --detail '{"cmd":"<命令>","exit_code":<数字>}'` |
+| 创建或修改了文件 | `file_write` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type file_write --summary "<一句话描述>" --detail '{"path":"<文件路径>"}'` |
+| 读取了文件 | `file_read` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type file_read --summary "<一句话描述>" --detail '{"path":"<文件路径>"}'` |
+| 进行了重要推理 | `reasoning` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type reasoning --summary "<推理结论>" --detail '{"confidence":<0-1>}'` |
+| 做出了关键决策 | `decision` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type decision --summary "<决策内容>" --detail '{"rationale":"<决策依据>"}'` |
+| 发生了错误或回退 | `error` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type error --summary "<错误描述>" --detail '{"traceback":"<错误信息>"}'` |
+| 用户给了新指令 | `user_instruction` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type user_instruction --summary "<用户说的话>"` |
+| 某个目标已完成 | `milestone` | `python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type milestone --summary "<完成的内容>"` |
 
 ### 成功标志
 
-命令返回 exit code 0 即为成功，输出形如：
-> `[ultra-memory] [1] bash_exec: 执行了 pip install pandas，安装成功`
+命令返回 exit code 0 即为成功。
 
 ### 自动标签
 
-`log_op.py` 会根据操作类型和内容自动追加标签（如 `setup`、`dependency`、`code`、`test` 等），无需手动指定 `--tags`。
+`log_op.py` 会根据操作类型和内容自动追加标签（`setup`、`dependency`、`code`、`test` 等），无需手动指定 `--tags`。
 
 ---
 
 ## 步骤三：记忆检索
 
-### 触发时机
+### 触发条件
 
-用户问及"之前做了什么"、"上次那个函数在哪里"、"之前遇到过这个问题吗"等记忆相关问题时执行。
+用户问及以下任意问题时执行：
+- "之前做了什么"
+- "上次那个函数在哪里"
+- "之前遇到过这个问题吗"
+- "我们用过哪些文件"
+- "上次选了什么方案"
+- 其他需要查找历史记忆的问题
 
 ### 执行命令
 
 ```bash
-python3 <skill_dir>/scripts/recall.py --session <session_id> --query "<用户问题的关键词>" --top-k 5
+python3 $SKILL_DIR/scripts/recall.py --session $SESSION_ID --query "<用户问题的关键词>" --top-k 5
 ```
 
-### 检索范围
-
-按以下优先级检索：
-1. 当前会话 `ops.jsonl`（精确匹配）
-2. 当前会话 `summary.md`（摘要快速定位）
-3. 跨会话 `knowledge_base.jsonl`（语义相似）
-4. 跨会话 `user_profile.json`（偏好匹配）
-
 ### 结果展示
 
-将检索结果直接展示给用户，格式如下：
+将脚本输出直接展示给用户。输出格式如下：
+
 ```
 [RECALL] 找到 N 条相关记录：
-
-[ops #23 · 14:18] <操作摘要>
-[summary · 里程碑] <里程碑内容>
-[跨会话 · 日期 · 项目] <历史记录摘要>
+1. [ops #23 · 14:18] <操作摘要>
+2. [summary · 里程碑] <里程碑内容>
+3. [知识库 · 标题] <内容摘要>
+4. [跨会话 · 日期 · 项目] <历史摘要>
 ```
 
 ---
 
 ## 步骤四：摘要压缩
 
-### 触发时机
+### 触发条件
 
-满足以下**任一条件**时，立即执行压缩：
+满足以下**任意条件**时，立即执行压缩命令：
 
 1. 操作日志达到 **50 条**
 2. 距上次压缩超过 **30 分钟**
-3. 用户明确说"总结一下"
-4. 当前 context 占用超过 **60%**
+3. 用户明确说"总结一下"或"做个总结"
+4. 脚本输出中包含 `COMPRESS_SUGGESTED` 信号
 
 ### 执行命令
 
 ```bash
-python3 <skill_dir>/scripts/summarize.py --session <session_id> --force
+python3 $SKILL_DIR/scripts/summarize.py --session $SESSION_ID --force
 ```
 
-### 期望输出
+### 成功标志
 
-生成/更新 `~/.ultra-memory/sessions/<session_id>/summary.md`，输出包含：
-- 已完成里程碑（[✅] 标记）
-- 当前进行中（[ ] 标记）
-- 下一步建议（[💡] 标记）
-- 操作统计（[📊] 标记）
+命令返回 exit code 0，输出包含 `摘要压缩完成`。
 
 ---
 
 ## 步骤五：跨会话恢复
 
-### 触发时机
+### 触发条件
 
-用户说"继续上次"、"从上次继续"、"记得昨天那个项目吗"等时执行。也在新会话开始时（检测到 session_id 变化）自动执行。
+用户说以下任意表达时执行：
+- "继续上次"
+- "从上次继续"
+- "记得昨天那个项目吗"
+- "还记得吗"
+- "继续上次的工作"
 
 ### 执行命令
 
 ```bash
-python3 <skill_dir>/scripts/restore.py --project <项目名>
+python3 $SKILL_DIR/scripts/restore.py --project <项目名>
 ```
 
-### 告知用户
+### 成功标志
 
-恢复成功后，立即告知用户：
-> "我找到了上次会话的记录。上次我们做到了：[里程碑摘要]。当前状态：[进行中任务]。下一步建议：[具体建议]。"
+输出中包含 `SESSION_ID=sess_xxxxx` 信号。
 
-如果找到了用户画像，也在回复中体现用户偏好。
+### 从输出提取信息
+
+| 输出中的字符串 | 模型必须执行的动作 |
+|-------------|----------------|
+| `SESSION_ID=sess_xxxxx` | 从等号后面提取值，保存为新的 `SESSION_ID` |
+| `TASK_STATUS=complete` | 告知用户"上次任务已完成" |
+| `TASK_STATUS=in_progress` | 告知用户"上次任务进行中" |
+| `💬 <自然语言总结>` | 直接将总结说给用户 |
+| `📌 <继续建议>` | 直接将建议说给用户 |
+
+### 告知用户
+
+> "我找到了上次会话的记录。{自然语言总结}。{继续建议}。"
 
 ---
 
 ## 步骤六：记忆进化
 
-记忆进化在每次操作中持续进行，不打断主任务。
+记忆进化在操作间隙进行，不打断主任务。
 
-### 6.1 用户画像更新
+### 6.1 用户画像积累
 
-**触发时机：**
-- 用户纠正了 AI 的代码风格或实现方式
-- 用户选择/拒绝了某个技术方案
-- 用户明确说出自己的技术栈或偏好
-- 用户表示某种工作流程更顺手
+**触发条件（满足任意一条，立即更新画像）：**
 
-**执行方式（二选一）：**
+1. 用户纠正了 AI 生成的代码风格
+2. 用户在两个技术方案中选择了其中一个
+3. 用户说出自己的技术栈（如"我用 Vue"、"我们用 Python"）
+4. 用户表示某种工作流程更顺手
+5. 用户明确描述了自己的偏好
+
+**执行命令 — 方式 A（MCP 工具，推荐）：**
+
+调用 `memory_profile` 工具，`action=update`，`updates` 中填写观察到的偏好字段。
+
+**执行命令 — 方式 B（直接修改文件）：**
 
-方式 A — 使用 MCP 工具：
 ```bash
-python3 <skill_dir>/scripts/mcp-server.js  # 通过 MCP 调用 memory_profile
+# 文件路径：$ULTRA_MEMORY_HOME/semantic/user_profile.json
+# 只更新观察到的字段，不覆盖已有字段
 ```
 
-方式 B — 直接读写 JSON：
-```
-文件路径：~/.ultra-memory/semantic/user_profile.json
-```
+**user_profile.json 可更新字段：**
 
-**user_profile.json 格式：**
 ```json
 {
-  "tech_stack": ["Python", "Vue3"],
-  "work_style": {"prefers_concise_code": true},
-  "projects": ["ai-data-qa"],
-  "language": "zh-CN",
-  "observed_patterns": ["倾向在实现前讨论方案"]
+  "tech_stack": ["观察到的技术栈"],
+  "work_style": {
+    "confirm_before_implement": true,
+    "prefers_concise_code": true
+  },
+  "language": "zh-CN 或 en",
+  "observed_patterns": ["观察到的工作习惯描述"]
 }
 ```
 
-### 6.2 知识库写入
+### 6.2 知识沉淀
+
+**触发条件（满足任意一条，立即写入知识库）：**
+
+1. 解决了一个报错或 bug（记录问题现象 + 解决方案）
+2. 做出了技术选型决策（记录选了什么 + 为什么）
+3. 发现了某个工具或库的使用技巧
+4. 完成了一个可复用的代码模式或函数
+
+**执行命令 — 方式 A（MCP 工具，推荐）：**
+
+调用 `memory_knowledge_add` 工具，`title` 必填（20字内），`content` 必填（200字内），`project` 和 `tags` 可选。
 
-**触发时机：**
-- 解决了一个棘手的 bug（记录问题现象 + 解决方案）
-- 做出了重要的技术选型决策（记录选了什么、为什么、放弃了什么）
-- 发现了某个工具/库的使用技巧
-- 完成了一个可复用的代码模式
+**执行命令 — 方式 B（直接追加）：**
 
-**执行方式：**
-追加写入 `~/.ultra-memory/semantic/knowledge_base.jsonl`，每行一条 JSON。
+追加写入 `$ULTRA_MEMORY_HOME/semantic/knowledge_base.jsonl`，每行一条 JSON。
 
 **knowledge_base.jsonl 格式：**
+
 ```json
-{"ts": "2026-04-07T10:00:00Z", "project": "项目名", "title": "简短标题", "content": "内容（200字内）", "tags": ["bug-fix", "python"]}
+{"ts": "2026-04-07T10:00:00Z", "project": "项目名", "title": "简短标题（20字内）", "content": "内容描述（200字内）", "tags": ["tag1", "tag2"]}
 ```
 
-### 6.3 里程碑追踪
+### 6.3 里程碑记录
+
+**触发条件 — 用户说出以下任意表达，立即记录 milestone：**
 
-**触发时机：**
-- 用户说"好了"、"完成了"、"搞定了"、"done"、"finished"
-- 某个功能/模块通过了测试
-- 阶段任务全部完成，用户准备切换下一个子任务
+中文：好了、完成了、搞定了、做完了、弄好了、可以了、没问题了、测试通过、上线了
 
-**执行方式：**
-使用 `op_type=milestone` 调用 `log_op.py`（见步骤二表格）。
+英文：done、finished、completed、it works、all good、passed、deployed、ready
 
-**作用：** 里程碑记录在 `summary.md` 中，恢复会话时优先展示，让用户快速找回状态。
+**执行命令：**
+
+```bash
+python3 $SKILL_DIR/scripts/log_op.py --session $SESSION_ID --type milestone --summary "<用户刚完成的事情的一句话描述>"
+```
+
+---
+
+## 信号对照表
+
+| 脚本输出信号 | 模型必须执行的动作 |
+|------------|----------------|
+| `MEMORY_READY` | 初始化成功；从同行使提取 session_id |
+| `session_id: sess_xxxxx` | 提取等号后值，保存为 SESSION_ID |
+| `COMPRESS_SUGGESTED` | 立即执行 summarize.py |
+| `SESSION_ID=sess_xxxxx` | restore 成功；提取等号后值，保存为新的 SESSION_ID |
+| `TASK_STATUS=complete` | 告知用户"上次任务已完成" |
+| `TASK_STATUS=in_progress` | 告知用户"上次任务进行中" |
+| `⚡ 建议运行: python3 scripts/summarize.py` | 执行该命令 |
+| 脚本返回 exit code != 0 | 静默跳过，继续主任务 |
 
 ---
 
@@ -232,7 +271,7 @@ python3 <skill_dir>/scripts/mcp-server.js  # 通过 MCP 调用 memory_profile
 | 变量 | 默认值 | 说明 |
 |------|--------|------|
 | `ULTRA_MEMORY_HOME` | `~/.ultra-memory/` | 存储根目录 |
-| `ULTRA_MEMORY_SESSION` | 自动生成 | 当前会话 session_id |
+| `SESSION_ID` | init.py 执行后自动生成 | 当前会话 ID，保存后供后续命令使用 |
 
 ---
 
@@ -240,12 +279,13 @@ python3 <skill_dir>/scripts/mcp-server.js  # 通过 MCP 调用 memory_profile
 
 | 异常情况 | 处理方式 |
 |---------|---------|
-| 脚本执行失败（exit code != 0） | 静默跳过，继续主任务。记忆功能失败**不阻塞**用户实际需求 |
-| 脚本超时（>15s） | 静默跳过，不重试 |
-| 存储目录无写入权限 | 静默跳过，尝试写入内存缓冲区，下次重试 |
-| 脚本文件不存在 | 静默跳过，退化为在当前 context 中手动维护摘要 |
+| 脚本执行失败（exit code != 0） | **静默跳过**，继续主任务。记忆功能失败**不阻塞**用户实际需求 |
+| 脚本超时（>15s） | **静默跳过**，不重试 |
+| 存储目录无写入权限 | **静默跳过**，尝试写入内存缓冲区，下次重试 |
+| 脚本文件不存在 | **静默跳过**，在当前 context 中手动维护摘要 |
 | 用户明确说"不用记录" | 立即停止记录，后续操作不再调用 log_op.py |
 | 文件被占用无法追加 | 自动重试 1 次，仍失败则静默跳过 |
+| SESSION_ID 未设置 | 先执行 init.py 初始化会话，再继续 |
 
 ---
 
@@ -254,25 +294,28 @@ python3 <skill_dir>/scripts/mcp-server.js  # 通过 MCP 调用 memory_profile
 ```
 用户发起对话
     │
-    ├─ 首次对话或听到记忆触发词？
-    │   └─ 是 → 步骤一：init.py → 告知用户"记忆就绪"
+    ├─ 首次对话或听到记忆触发词或描述持续性任务含项目名词？
+    │   └─ 是 → 执行 init.py
+    │       ├─ 输出含 MEMORY_READY？→ 提取 session_id，告知用户
+    │       └─ 输出含 COMPRESS_SUGGESTED？→ 执行 summarize.py
     │
     ├─ 用户说记忆相关问题？
-    │   └─ 是 → 步骤三：recall.py → 展示检索结果
+    │   └─ 是 → 执行 recall.py → 将结果展示给用户
+    │
+    ├─ 用户说恢复相关表达？
+    │   └─ 是 → 执行 restore.py → 提取 session_id + 总结 + 建议，告知用户
     │
     └─ 每次用户与 AI 交互后：
         │
-        ├─ 操作数 % 10 == 0 且 context > 60%？
-        │   └─ 是 → 步骤四：summarize.py
+        ├─ 操作数达到 50 条？→ 执行 summarize.py
+        ├─ 脚本输出含 COMPRESS_SUGGESTED？→ 执行 summarize.py
+        ├─ 满足画像积累条件？→ 更新 user_profile.json
+        ├─ 满足知识沉淀条件？→ 写入 knowledge_base.jsonl
+        ├─ 用户说完成相关表达？→ 记录 milestone
         │
-        ├─ 发现用户偏好 / 解决重要问题 / 完成里程碑？
-        │   └─ 是 → 步骤六：进化（画像/知识库/里程碑）
-        │
-        └─ 步骤二：log_op.py（记录本次操作）
+        └─ 执行 log_op.py（记录本次操作）
 ```
 
 ---
 
-## 进阶配置
-
-详细配置项（过滤规则、LanceDB 向量检索升级、团队共享、安全注意事项等）见 `references/advanced-config.md`。
+进阶配置（过滤规则、LanceDB 向量检索升级、安全注意事项等）见 `references/advanced-config.md`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra-memory",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "超长会话记忆系统 — 5层记忆架构，零外部依赖，支持所有LLM平台（Claude/GPT/Gemini/Qwen等）",
   "keywords": [
     "ai",
@@ -45,7 +45,8 @@
     "ultra-memory-log": "scripts/log_op.py",
     "ultra-memory-recall": "scripts/recall.py",
     "ultra-memory-summarize": "scripts/summarize.py",
-    "ultra-memory-restore": "scripts/restore.py"
+    "ultra-memory-restore": "scripts/restore.py",
+    "ultra-memory-knowledge": "scripts/log_knowledge.py"
   },
   "scripts": {
     "test": "python3 test_e2e.py",

package/platform/server.py

@@ -263,6 +263,19 @@ def tool_memory_extract_entities(body: dict) -> tuple[bool, str]:
     return _run_script("extract_entities.py", ["--session", session_id, "--all"])
 
 
+def tool_memory_knowledge_add(body: dict) -> tuple[bool, str]:
+    title = body.get("title", "")
+    content = body.get("content", "")
+    if not title or not content:
+        return False, "缺少 title 或 content 参数"
+    project = body.get("project", "default")
+    tags = body.get("tags", [])
+    args = ["--title", title, "--content", content, "--project", project]
+    if tags:
+        args.extend(["--tags", ",".join(tags)])
+    return _run_script("log_knowledge.py", args)
+
+
 # ── 工具注册表 ────────────────────────────────────────────────────────────
 
 TOOL_HANDLERS = {
@@ -275,6 +288,7 @@ TOOL_HANDLERS = {
     "memory_profile":          tool_memory_profile,
     "memory_entities":         tool_memory_entities,
     "memory_extract_entities": tool_memory_extract_entities,
+    "memory_knowledge_add":    tool_memory_knowledge_add,
 }
 
 TOOL_DESCRIPTIONS = {
@@ -287,6 +301,7 @@ TOOL_DESCRIPTIONS = {
     "memory_profile":          "读写用户画像（技术栈、偏好）",
     "memory_entities":         "查询结构化实体索引（函数/文件/依赖/决策/错误）",
     "memory_extract_entities": "对整个 ops.jsonl 全量重提取实体",
+    "memory_knowledge_add":    "追加知识库条目（bug解决方案、技术选型、工具技巧、可复用代码模式）",
 }
 
 

package/platform/tools_gemini.json

@@ -171,6 +171,33 @@
         },
         "required": ["session_id"]
       }
+    },
+    {
+      "name": "memory_knowledge_add",
+      "description": "Append important information to the knowledge base for future retrieval. Use when: solving a tricky bug, making a key tech decision, discovering a tool usage tip, or completing a reusable code pattern.",
+      "parameters": {
+        "type": "OBJECT",
+        "properties": {
+          "title": {
+            "type": "STRING",
+            "description": "Knowledge title (max 100 chars)"
+          },
+          "content": {
+            "type": "STRING",
+            "description": "Knowledge content (max 200 chars)"
+          },
+          "project": {
+            "type": "STRING",
+            "description": "Associated project name (default: 'default')"
+          },
+          "tags": {
+            "type": "ARRAY",
+            "items": { "type": "STRING" },
+            "description": "Tag list (optional)"
+          }
+        },
+        "required": ["title", "content"]
+      }
     }
   ]
 }

package/platform/tools_openai.json

@@ -203,5 +203,35 @@
         "required": ["session_id"]
       }
     }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "memory_knowledge_add",
+      "description": "Append important information to the knowledge base (knowledge_base.jsonl) for future retrieval. Use when: solving a tricky bug (record problem + solution), making a key tech decision (record what was chosen and why), discovering a tool usage tip, or completing a reusable code pattern.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "Knowledge title (max 100 chars)"
+          },
+          "content": {
+            "type": "string",
+            "description": "Knowledge content (max 200 chars)"
+          },
+          "project": {
+            "type": "string",
+            "description": "Associated project name (default: 'default')"
+          },
+          "tags": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Tag list (optional)"
+          }
+        },
+        "required": ["title", "content"]
+      }
+    }
   }
 ]

package/scripts/log_knowledge.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""
+ultra-memory: 知识库写入脚本
+将重要信息追加写入 semantic/knowledge_base.jsonl，供未来相似任务检索。
+"""
+
+import os
+import sys
+import json
+import argparse
+from datetime import datetime, timezone
+from pathlib import Path
+
+if sys.stdout.encoding != "utf-8":
+    sys.stdout.reconfigure(encoding="utf-8")
+
+ULTRA_MEMORY_HOME = Path(os.environ.get("ULTRA_MEMORY_HOME", Path.home() / ".ultra-memory"))
+
+
+def log_knowledge(
+    title: str,
+    content: str,
+    project: str = "default",
+    tags: list = None,
+):
+    """追加一条知识库条目"""
+    semantic_dir = ULTRA_MEMORY_HOME / "semantic"
+    semantic_dir.mkdir(parents=True, exist_ok=True)
+    kb_file = semantic_dir / "knowledge_base.jsonl"
+
+    entry = {
+        "ts": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "project": project,
+        "title": title[:100],
+        "content": content[:200],
+        "tags": tags or [],
+    }
+
+    with open(kb_file, "a", encoding="utf-8") as f:
+        f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+    print(f"[ultra-memory] 知识库已写入: {title}")
+    return entry
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="追加知识库条目")
+    parser.add_argument("--title", required=True, help="知识标题（100字内）")
+    parser.add_argument("--content", required=True, help="知识内容（200字内）")
+    parser.add_argument("--project", default="default", help="关联项目名")
+    parser.add_argument("--tags", default="", help="逗号分隔的标签")
+    args = parser.parse_args()
+
+    tags = [t.strip() for t in args.tags.split(",") if t.strip()]
+    log_knowledge(args.title, args.content, args.project, tags)

package/scripts/mcp-server.js

@@ -164,6 +164,20 @@ const TOOLS = [
       },
       required: ["session_id"]
     }
+  },
+  {
+    name: "memory_knowledge_add",
+    description: "将重要信息追加到知识库（knowledge_base.jsonl），供未来相似任务检索。适用场景：解决了一个棘手的 bug、做出了重要技术选型决策、发现了工具使用技巧、完成了一个可复用的代码模式",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "知识标题（100字内）", maxLength: 100 },
+        content: { type: "string", description: "知识内容（200字内）", maxLength: 200 },
+        project: { type: "string", description: "关联项目名", default: "default" },
+        tags: { type: "array", items: { type: "string" }, description: "标签列表", default: [] }
+      },
+      required: ["title", "content"]
+    }
   }
 ];
 
@@ -291,6 +305,15 @@ function executeTool(name, input) {
     case "memory_extract_entities": {
       return runScript("extract_entities.py", ["--session", input.session_id, "--all"]);
     }
+    case "memory_knowledge_add": {
+      const args = [
+        "--title", input.title,
+        "--content", input.content,
+        "--project", input.project || "default",
+        "--tags", (input.tags || []).join(",")
+      ];
+      return runScript("log_knowledge.py", args);
+    }
     default:
       return { success: false, output: `未知工具: ${name}` };
   }