memem

为 Claude Code 提供持久、自我进化的记忆。 不必在每次会话时都重新解释您的项目。

有关 LLM/AI 工具发现，请参阅 llms.txt。

  ███╗   ███╗███████╗███╗   ███╗███████╗███╗   ███╗
  ████╗ ████║██╔════╝████╗ ████║██╔════╝████╗ ████║
  ██╔████╔██║█████╗  ██╔████╔██║█████╗  ██╔████╔██║
  ██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║
  ██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║
  ╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝
  persistent memory for Claude Code

什么是 memem？

memem 是一个 Claude Code 插件，为 Claude 提供跨会话的持久化记忆。后台挖掘程序会从您已完成的会话中提取持久的经验教训（决策、约定、错误修复、偏好），将它们以 Markdown 格式存储在 Obsidian 库中，并在每个新会话开始时通过查询定制的简报自动呈现相关内容。

它是本地优先的：无需云服务，无需 API 密钥，没有供应商锁定。所有内容都以人类可读的 Markdown 格式存储在 ~/obsidian-brain/memem/memories/ 中。

我什么时候应该使用 memem？

如果您符合以下情况，请使用 memem：

• 您每天使用 Claude Code，并且不断地向每个新会话重新解释您的项目

• 您想要可以浏览和编辑的持久化 Markdown 记忆

• 您喜欢零供应商锁定的本地优先工具

• 您已经在使用 Obsidian（memem 可以直接接入您的库）

如果您符合以下情况，请跳过 memem：

• CLAUDE.md 对您来说已经足够好，且您不想要后台守护进程

• 您需要在多台机器间进行云同步记忆（memem 仅限本地）

• 您使用的 Python 版本 < 3.11

memem 与 CLAUDE.md 有什么不同？

CLAUDE.md 是每个项目一个手动编辑的文件。memem 为您提供：

• 自动提取 — 无需手动记录，挖掘程序会从每个已完成的会话中捕获经验教训

• 查询感知上下文 — 只有与您当前问题相关的记忆才会被注入，而不是静态转储

• 自我进化 — 随着项目的演进，记忆会自动合并、更新和弃用

• 跨项目 — 适用于您使用的每个 Claude Code 项目，而不局限于单个仓库

• 安全扫描 — 每次写入都会扫描提示词注入和凭据泄露

• 可浏览 — 带有图谱视图和反向链接的 Obsidian 库，免费使用

如何安装 memem？

/plugin marketplace add TT-Wang/memem
/plugin install memem

就是这样。首次运行时，bootstrap.sh 会自动修复所有内容：

1. 验证 Python ≥ 3.11

2. 如果缺少 uv，则安装它（通过官方 Astral 安装程序）

3. 将依赖项同步到插件本地的 .venv 中（针对 uv.lock 进行哈希缓存）

4. 创建并进行金丝雀测试 ~/.memem/ 和 ~/obsidian-brain/

5. 写入 ~/.memem/.capabilities（用于降级模式决策）

6. 执行真正的 MCP 服务器

首次运行： 约 5 秒。后续每次运行： 约 100 毫秒。无需单独的 pip install 步骤。

我的第一次 Claude Code 会话会发生什么？

您输入第一条消息。UserPromptSubmit 钩子触发并发现没有记忆（因为您刚安装），因此它会在 Claude 的上下文中注入一个欢迎横幅。Claude 读取横幅，告诉您 memem 已激活，并且如果您有预先存在的 Claude Code 会话，它会提议通过 /memem-mine-history 进行挖掘。

您正常工作。挖掘程序守护进程在后台静默运行。当您的会话结束并稳定 5 分钟后，挖掘程序会使用 Claude Haiku 从记录中提取记忆并将其写入您的库。

从第二次会话开始： 钩子将您的第一条消息发送到 context_assemble，它会为 Haiku 提供相关的记忆，并要求它合成一份定制的简报。您会看到一个状态横幅，例如 [memem] 12 memories · miner OK · assembly OK，后面跟着简报。Claude 以完整的上下文开始工作 — 无需重新解释。

memem 保存什么？

它保存的是持久的知识，而不是会话日志：

• 架构决策及其理由（“我们使用 RS256 JWT，因为……”）

• 约定（“测试放在 tests/ 而不是 spec/ 中”）

• 您可能会忘记的错误修复（“bcrypt.compare 是异步的 — 必须 await”）

• 用户偏好（“偏好单次提交，而不是堆叠的 PR”）

• 已知问题（“如果未设置，JWT_SECRET 默认为 'secret' — 在 #123 中跟踪”）

它不会保存：

• 原始会话记录（这些可以通过 transcript_search 搜索，不会作为记忆存储）

• 平凡或显而易见的事实

• 会话结果（“今天我处理了 X”）

memem 将我的记忆存储在哪里？

您可以通过 MEMEM_DIR 和 MEMEM_OBSIDIAN_VAULT 环境变量将 memem 指向其他位置。

Claude 可以调用哪些 MCP 工具？

memem 添加了哪些斜杠命令？

• /memem — 欢迎、状态、帮助

• /memem-status — 记忆计数、项目、搜索数据库大小、挖掘程序健康状况

• /memem-doctor — 带有任何阻塞项修复说明的飞行前健康检查

• /memem-mine — 手动启动挖掘程序守护进程（通常会自动启动）

• /memem-mine-history — 选择性加入：挖掘您安装前所有的 Claude Code 会话

如果 claude CLI 不在我的 PATH 中怎么办？

memem 进入降级模式 — 它仍然可以工作，只是没有 Haiku 驱动的上下文组装和智能召回。您将获得仅限 FTS 的关键字召回，而不是查询定制的简报。每个会话的顶部都会显示 [memem] N memories · miner OK · assembly degraded (claude CLI missing — FTS-only recall)，以便您知道原因。

这是有意设计的：缺少可选依赖项应该降级，而不是失败。

我该如何诊断问题？

运行 /memem-doctor。它会运行与引导程序 shim 相同的飞行前检查（Python 版本、mcp 可导入性、PATH 中的 claude CLI、目录可写性、uv 可用性），然后打印一份标记为 HEALTHY、DEGRADED 或 FAILING 的报告，并为每个阻塞项提供明确的修复说明。

进行更深入的调试：

tail -f ~/.memem/bootstrap.log   # first-run shim log
tail -f ~/.memem/miner.log       # miner daemon log
cat ~/.memem/events.jsonl        # memory operation audit trail
python3 -m memem.server --status   # detailed status dump

挖掘管道是如何工作的？

Session ends → miner daemon sees the JSONL file in ~/.claude/projects/
  → Waits 5 minutes for the file to "settle" (no more writes)
  → Filters to human messages + assistant prose (strips tool calls, system reminders)
  → One Haiku call with the full context: "extract durable lessons"
  → Haiku returns JSON array of memory candidates
  → Each candidate runs: security scan → dedup check → contradiction detection → save
  → Index rebuilt, per-project playbooks grown and refined
  → Session marked COMPLETE in ~/.memem/.mined_sessions

召回管道是如何工作的？

First message in a new session → auto-recall.sh hook fires
  → Reads ~/.memem/.capabilities for status banner
  → If claude CLI is available → sends (message, memories) to Haiku
      → Haiku synthesizes a focused briefing (300-800 tokens usually)
      → Brief injected into Claude's context as "memem context briefing"
  → If claude CLI is missing → falls back to FTS-only keyword recall
  → Either way, Claude starts its reply with relevant context already loaded

架构

memem 被拆分为小型、专注的模块：

• models.py — 数据类型、路径常量

• security.py — 提示词注入 + 凭据泄露扫描

• telemetry.py — 访问跟踪、事件日志（原子写入，fcntl 锁定）

• search_index.py — SQLite FTS5 索引

• obsidian_store.py — 记忆 I/O、去重评分、矛盾检测

• playbook.py — 每个项目的剧本增长 + 精炼

• assembly.py — 通过 Haiku 进行上下文组装

• capabilities.py — 降级模式的运行时功能检测

• storage.py — 服务器生命周期助手（PID 管理、挖掘程序自动启动）

• server.py — 轻量级 MCP 入口点（延迟导入 FastMCP）

• cli.py — 非 MCP 入口点的命令调度程序

• mining.py — 会话挖掘管道

多信号召回评分：

• 50% FTS 相关性

• 15% 近期性（0.995^小时衰减）

• 15% 访问历史（使用强化）

• 20% 重要性（Haiku 的 1-5 评分）

记忆模式（Markdown 前置元数据）：

---
id: uuid
schema_version: 1
title: "descriptive title"
project: project-name
tags: [mined, project-name]
related: [id1, id2, id3]
created: 2026-04-13
updated: 2026-04-13
source_type: mined | user | import
source_session: abc12345
importance: 1-5
status: active | deprecated
valid_to:                     # set when deprecated
contradicts: [id1]            # flagged conflicts
---

配置

设置 Obsidian（可选，推荐）

memem 无需 Obsidian 即可工作 — 它只是写入 Markdown。但 Obsidian 为您免费提供图谱视图和反向链接：

1. 下载：https://obsidian.md (免费)

2. 打开 ~/obsidian-brain 作为库

3. 记忆出现在 memem/memories/ 中，剧本出现在 memem/playbooks/ 中

4. 使用图谱视图查看记忆如何通过 related 字段链接

要求

• Claude Code

• Python ≥ 3.11

• uv（首次运行时由 bootstrap.sh 自动安装）

• PATH 中的 claude CLI（可选 — Haiku 驱动的组装需要；降级模式无需此项）

开发

git clone https://github.com/TT-Wang/memem.git
cd memem
pip install -e ".[dev]"
pytest             # 54 tests
ruff check .       # lint
mypy memem # type check (strict)

请参阅 CONTRIBUTING.md 了解 PR 流程，参阅 CHANGELOG.md 了解版本历史。

许可证

MIT