让Agent自己整理笔记：memsearch后台记忆维护机制（PROJECT.md与USER.md）完整解析

【免费下载链接】memsearchA persistent, unified memory layer for all your AI agents (e.g. Claude Code, Codex, DSH), backed by Markdown and Milvus.项目地址: https://gitcode.com/gh_mirrors/mem/memsearch

memsearch 是一个为 AI Agent（Claude Code、Codex、DSH 等）提供持久统一记忆层的开源工具，而它的后台记忆维护机制正是亮点之一：在会话结束后，memsearch 会在后台自动唤醒一个 LLM，把散落在日常记忆日志里的关键信息，提炼进两份高价值笔记——PROJECT.md（项目状态）和USER.md（用户偏好）。你不需要手动整理任何笔记，Agent 自己就能把笔记整理好。

📌 为什么需要"后台记忆维护"？

日常使用中，memsearch 会把每次会话的关键信息写入.memsearch/memory/目录下的记忆日志（journal）。但日志是碎片化的、按时间堆积的，存在两个天然问题：

• 噪声多：大量临时性讨论、一次性问答，不值得长期保留；
• 缺少提炼：真正有长期价值的"项目决策、活跃线索、用户偏好"淹没在日志里，Agent 下次回忆时很难直接命中。

后台维护机制的思路很像人类的"定期复盘"：定期把日志里的长期价值信息，蒸馏成两份精炼、可审阅的 Markdown 文件，而不是让笔记越攒越乱。

📝 两大维护任务：PROJECT.md 与 USER.md 各管什么

memsearch 内置两个后台维护任务（见 src/memsearch/maintenance.py 中的TASKS = ("project_review", "user_profile")）：

两者的边界在提示词里被严格约束，避免"串台"：

• PROJECT.md 保持"只谈项目"：稳定的用户偏好（语言偏好、沟通风格等）不放这里，应写入USER.md（见 plugins/_shared/prompts/project_review.txt）；
• USER.md 保持"只谈人与习惯"：项目技术决策、文件路径、Bug 修复不写入用户画像，且严禁把项目决策改写成"用户偏好……"的句式（见 plugins/_shared/prompts/user_profile.txt）。

⏱️ 什么时候才会触发？三个条件缺一不可

维护任务不是"每次会话都跑"，而是由 run_due_tasks() 按以下三个条件判断是否"到期"：

1. 任务已启用（enabled = true，默认关闭，避免意外的后台模型调用）；
2. 输入发生变化：对.memsearch/memory/下所有.md文件计算 SHA256 摘要（_input_digest()），摘要没变就直接跳过，不做无谓的模型调用；
3. 距上次成功运行已超过min_interval_hours（默认 24 小时）。

运行状态记录在.memsearch/.maintenance-state.json中。一个贴心的设计是：失败的运行不会被标记为"成功摘要"，所以下次到期时会自动重试，不会因为一次 API 失败就永远"沉默"（详见 docs/home/configuration.md）。

🤖 维护任务如何"动笔"：提示词、JSON 与全量替换

触发后，memsearch 会组装一个结构化提示词（_build_prompt()），包含四部分：

1. 任务模板（项目目录、输入目录、输出文件路径）；
2. 现有的输出文件内容；
3. 最近 12 个记忆日志条目（带字符预算控制）；
4. 输入摘要变化值。

LLM 被要求只返回一个 JSON 对象，且只有两种动作（_parse_task_response()）：

• {"action":"none","reason":"..."}—— 日志没有新的长期价值信息，不动文件；
• {"action":"replace","reason":"...","content":"完整 Markdown 内容"}—— 用全文替换输出文件。

这种"none / replace"的二元设计非常保守：默认不改，只有确有新价值才改写，而且提示词明确要求"保留有用的现有内容、做小步精准增补，而不是为文风重写"。

此外，memsearch 还支持让 LLM 在整理时"下钻"查看记忆：它内置了一个受限只读工具（run_memory_command()），只允许执行memsearch expand、memsearch transcript、find、grep等只读命令，路径被限制在记忆目录内，并禁止一切 shell 元字符，防止提示词注入带来的越权操作。

🛠️ 如何开启：一句话让 Agent 配置

这两个任务默认关闭。最简单的开启方式是直接对 Agent 说：

"enable MemSearch's PROJECT.md and USER.md maintenance"

Agent 会通过memory-config技能帮你完成配置，并可以顺带选择模型、间隔和自定义提示词。偏好手动配置的话，设置位于 MemSearch 配置的[plugins.<agent>.project_review]与[plugins.<agent>.user_profile]下（完整示例见 docs/home/configuration.md）：

[plugins.codex.project_review] enabled = true provider = "native" # 复用 Agent 自身的模型通道 min_interval_hours = 24 input_dir = ".memsearch/memory" output_file = ".memsearch/PROJECT.md"

• provider = "native"表示复用宿主 Agent 的模型；也可以配置 memsearch 管理的 API 提供商（OpenAI / Anthropic / Gemini 等）来独立跑后台任务；
• 提示词支持全局自定义：memsearch config set prompts.project_review /path/to/project-review.txt。

平台侧的唤醒入口在插件层的 maintenance-runner.py，负责处理各 Agent 宿主的原生模型调用；Python 核心包则提供共享的配置、到期判断、提示词与 API 提供商逻辑，分工清晰。

🔍 维护任务"沉默"了怎么办？排查指南

如果后台维护迟迟没有产出，按顺序检查：

1. 查看.memsearch/.maintenance-state.json：对应<平台>.<任务>条目里，last_action是error？还是skip（输入未变化 / 未到间隔）？
2. last_error字段记录了失败原因，这是第一排查点；
3. 确认任务enabled = true，且记忆日志目录确实有更新；
4. 也可以直接问memory-config技能，它能检查当前配置、记忆文件与健康状态。

📂 相关文件速查

小结：memsearch 的后台记忆维护用"日志蒸馏"的方式，把 Agent 的日常记忆自动沉淀为两份可持续维护的笔记——PROJECT.md记录项目状态，USER.md记录用户习惯。三个触发条件保证不浪费模型调用，保守的"none/replace"协议保证不破坏已有内容，失败自动重试保证长期可靠。开启它之后，你的 Agent 就像一位会定期复盘的助理：你只管干活，笔记它来整理。

【免费下载链接】memsearchA persistent, unified memory layer for all your AI agents (e.g. Claude Code, Codex, DSH), backed by Markdown and Milvus.项目地址: https://gitcode.com/gh_mirrors/mem/memsearch