Mnemos

mnemos

为你的编码 Agent 打造的自动驾驶知识库。

只需安装一次。此后，你的 Agent 会在你编写代码时，为项目构建结构化知识库。无需记住提示词，无需调用 remember()，也无需学习 API。

单个 Go 二进制文件。内嵌 SQLite。完全不依赖云端。无需 Docker。无需 Python。无需 Node 运行时。

Agent (Claude Code / Cursor / Kiro / Gemini CLI / Codex / ...)
    ↓ MCP stdio
mnemos serve
    ↓
Auto-compiled knowledge base (~/.mnemos/mnemos.db)

---

mnemos 有何不同

每个记忆服务都存储文本。Mnemos 会编译知识库。

其他服务需要你（或经过精心调整的提示词）决定何时存储、何时检索，而 mnemos 会在后台运行完整的处理流水线：

Agent action → mnemos auto-pipeline:
                ├── Quality gate        (reject/rewrite low-value content)
                ├── 3-tier dedup        (hash → fuzzy → semantic)
                ├── Auto-summarize      (extractive, fast; LLM if available)
                ├── File linking        (extract identifiers, link to code)
                ├── Type classification (episodic / long_term / semantic / skill)
                ├── Quality scoring     (for retrieval ranking)
                └── Decay scheduling    (so knowledge base stays relevant)

Retrieval:
                ├── Hybrid search       (FTS5 + optional semantic + RRF)
                ├── File-overlap boost  (memories about active files rank higher)
                ├── MMR diversity       (kill redundant results)
                ├── Adaptive packing    (full content or summary based on budget)
                └── Token-budget cap    (always fits in context)

这条流水线通过 MCP 和钩子接口在后台运行。Agent 使用常规记忆 工具；无需自行编排去重、摘要、排序、打包或生命周期维护。

---

三层功能，现已全部推出

第 1 层 — MCP 传输。 标准 MCP 服务，使用 stdio，可与任何 MCP 客户端配合使用。

第 2 层 — 自动驾驶钩子。 一条命令（mnemos setup claude）即可配置钩子 + 引导说明 + MCP 配置。会话开始时自动注入相关上下文。提交提示词时，会在主题变化后自动搜索。会话结束时会验证覆盖情况。

第 3 层 — 自动编译的知识库。 质量门控、三级去重、自动摘要、文件关联、MMR 上下文组装——全部自动完成。你无需手动触发。还包括被动后台守护进程，可持续检测记忆库中的过时信息、矛盾和缺失关联。

---

坦诚比较

	Mem0	Zep/Graphiti	engram	OMEGA	mnemos
原生支持 MCP	✓	✓	✓	✓	✓
单个二进制文件，无运行时依赖	—	—	✓	—	✓
完全不依赖云端 / 本地优先	部分	—	✓	✓	✓
一条命令完成自动驾驶配置	—	—	—	—	✓
自动质量门控	—	—	—	—	✓
自动摘要	—	—	—	—	✓
自动关联文件（感知 git）	—	—	—	—	✓
MMR 上下文组装	—	—	—	—	✓
被动后台守护进程	—	—	—	—	✓
时序知识图谱	—	✓	—	—	部分（衰减 + 替代）
可自托管成本	$0-云端	~$50/月（Neo4j）	$0	$0	$0

Mnemos 并不打算成为 Zep——两者的选择不同。如果你需要对业务事实进行时序推理，并且拥有企业级基础设施，Zep 是最佳选择。如果你是编码 Agent 用户，希望拥有一个能在笔记本电脑上自行运行的自动驾驶知识库，那么 Mnemos 是最佳选择。

---

安装

# Homebrew (macOS / Linux)
brew install s60yucca/tap/mnemos && mnemos setup claude

# curl (verify mnemos.dev is live before using)
curl -fsSL https://mnemos.dev/install.sh | bash && mnemos setup claude

# npm wrapper
npx -y @s60yucca/mnemos setup claude

# Build from source (requires Go 1.23+)
git clone https://github.com/s60yucca/mnemos
cd mnemos && make build

将 claude 换成 cursor、kiro、gemini-cli、codex 或 trae。重启客户端。自动驾驶功能从此开始运行。

---

autopilot 实际会做什么

mnemos setup <client> 会写入：

• 引导文件（CLAUDE.md、.cursorrules、.kiro/steering/mnemos.md）——告诉 Agent 哪些内容值得存储
• 钩子配置（.claude/hooks.json 或同等配置）——接入生命周期事件
• MCP 配置（.mcp.json）——将 mnemos serve 注册为工具提供程序

三个钩子会自动运行：

会话开始 → mnemos hook session-start 在令牌预算内汇总相关记忆（采用 MMR 多样化处理，并对文件进行加权）。将其注入上下文。冷启动时间 < 200 ms。

提交提示词 → mnemos hook prompt-submit 检测主题和意图的变化。当变化有意义时，自动搜索知识库。遵循冷却时间，避免产生干扰。

会话结束 → mnemos hook session-end 确认是否已捕获持久记忆。可选择存储一条精简的线索。清理会话状态。

引导文件告诉 Agent 什么 值得记住。钩子负责检索、去重、摘要和关联——这样 Agent 就不用浪费令牌来考虑记忆管理。

升级 Mnemos 后，请验证 CLI 和正在运行的 MCP 服务：

mnemos version
mnemos doctor all

然后让 Agent 调用 mnemos_runtime。它会报告实际处理工具调用的 MCP 服务进程，包括 version、host、pid、started_at、executable、data_dir 和 project_id。如果显示的仍是旧版本，请关闭 MCP 客户端并重新打开。只有在关闭活动中的 MCP 客户端后，或你有意接受所有活动中的 Mnemos 传输重新连接时，才使用 pkill -f "mnemos serve"。

你可以使用以下命令验证返回的 JSON：

mnemos doctor runtime --from-json runtime.json
mnemos check --mcp-runtime runtime.json

每日运行 mnemos check 无需 MCP 运行时 JSON。发布或升级验证应传入 --mcp-runtime，以便在发布前发现过期的 MCP 服务。

---

被动 autopilot 守护进程

除了钩子之外，mnemos 还会运行一个后台守护进程，持续改进知识库：

• 过时检测——标记引用了已删除文件或过时模式的记忆
• 矛盾检测——查找相互冲突的记忆
• 关系推断——自动关联相关记忆
• 回填——为缺少摘要的记忆追溯生成摘要
• 自动编译——将符合条件的源记忆编译为可复用的项目知识

mnemos autopilot status          # check daemon state
mnemos autopilot run             # trigger immediate run
mnemos autopilot run --dry-run   # preview findings without writing
mnemos autopilot report          # view latest findings

---

验证自动化循环

Mnemos 为配置、原始活动、知识质量和端到端循环就绪状态提供了独立视图：

mnemos status                    # effective data path and automatic feature settings
mnemos health                    # raw feature firing rates and denominators
mnemos eval --project myapp      # memory quality, duplication, freshness, usefulness
mnemos check --project myapp     # consolidated read-only loop verification
mnemos check --launch            # stricter public-launch readiness gates

mnemos check 会以只读方式打开数据库。它不会运行迁移、启动工作进程或修改记忆。mnemos check --fix 的操作范围刻意保持有限：仅在生成经过验证的清理计划后，归档较早生成的 autopilot 报告。

---

性能基准（延迟）

操作	350 条记忆	1,500 条记忆
store（新内容，完整处理流程）	57 ms	24 ms
store（命中去重）	55 ms	22 ms
search 混合搜索（RRF + 文件加权）	42 ms	39 ms
maintain（衰减 + GC）	27 ms	108 ms
钩子 session-start（冷启动）	< 200 ms	—
二进制大小	~12 MB	—

硬件：M1 Pro，16GB RAM，SQLite 存储于 SSD。你的延迟可能有所不同。

无论数据集大小如何，大多数操作都能在 60 ms 内完成。钩子子命令使用 InitLight 模式——不启动后台工作进程，也不会中断会话。

价值基准（令牌节省、精准度、避免陷阱）仍在进行中。 方法见 DOGFOODING_RUNBOOK.md。正式发布前，我们会用实际数据替换此占位内容。

---

MCP 工具

工具	功能
mnemos_store	存储一条记忆（完整的自动化流水线会透明运行）
mnemos_search	混合式 FTS + 语义 + 文件重叠搜索
mnemos_context	汇总符合预算且经 MMR 多样化处理的上下文
mnemos_get	按 ID 获取
mnemos_update	更新内容、摘要或标签
mnemos_delete	软删除（可通过 maintain 恢复）
mnemos_relate	关联两条记忆（supersedes、caused_by、depends_on）
mnemos_maintain	运行衰减、归档、GC 和过时检测
mnemos_runtime	报告 MCP 服务的实时版本、主机、pid、可执行文件、运行时间、数据目录和项目范围

---

安装后的快速开始

# Agents call these automatically via MCP. You can also use directly:
mnemos store "JWT uses RS256, 1h expiry, config in auth/config.go"
mnemos search "token expiry"
mnemos stats
mnemos maintain

---

配置

大多数用户无需修改配置。不过，如果你想修改：

# .mnemos/config.yaml (project-local) or ~/.mnemos/config.yaml (global)
embeddings:
  provider: noop              # noop (default) | ollama | openai
  # Pure FTS works fine. Enable semantic for meaning-based search.

quality_gate:
  min_words: 5
  max_words: 200
  min_density: 0.3
  require_specific: true      # long_term memories need project identifiers
  duplicate_threshold: 0.8

summarization:
  extractive: true             # always on, fast, offline

file_linking:
  enabled: true                # auto-disables outside git

hook:
  enabled: true
  search_cooldown: 5m
  session_start_max_tokens: 2000
  mmr_lambda: 0.7              # 0=max diversity, 1=max relevance
  file_boost: 0.3

autopilot:
  enabled: true
  interval: 15m
  contradiction_enabled: false
  auto_compile_enabled: true
  min_auto_compile_sources: 5

配置解析顺序为：显式指定的 --config、项目本地的 .mnemos/config.yaml，然后是 ~/.mnemos/config.yaml。环境变量使用 MNEMOS_ 前缀。

---

记忆类型

Mnemos 会自动分类。可通过 --type 标志手动覆盖。

类型	衰减速率	用途
short_term	快（约 1 天）	待办事项、临时笔记、进行中的工作
episodic	中（约 1 个月）	会话事件、错误修复
long_term	慢（约 6 个月）	架构决策
semantic	非常慢	事实、定义、知识
skill	慢	可重复的流程和操作工作流
compiled	受管理	自动编译的项目知识

---

我为什么构建它

我厌倦了每天早上都要向 Claude Code 重新解释自己的项目。

我试用了现有的记忆服务。它们大多能很好地存储文本。但每个服务都要求我（或经过精心调校的提示词）决定何时存储、何时检索。这不是知识库，只是套了 MCP 包装器的数据库。

我构建 Mnemos，就是为了让这一切真正自动化。运行 mnemos setup claude，重启编辑器，知识库就会自行编译。

---

自动驾驶设置——每个客户端只需一条命令

mnemos setup claude       # writes CLAUDE.md, .claude/hooks.json, .mcp.json
mnemos setup cursor       # writes .cursorrules, .mcp.json
mnemos setup kiro         # writes .kiro/steering/mnemos.md, .kiro/mcp.json
mnemos setup gemini-cli   # writes GEMINI.md, .gemini/settings.json, .mcp.json
mnemos setup codex        # writes ~/.codex/config.toml (global, CLI + VSCode)

标志：--global（为所有项目安装）、--force（覆盖现有内容）、--project <id>（覆盖项目 ID）。

对于 Claude Code，--project <id> 会将 MNEMOS_PROJECT_ID 写入 MCP 条目和钩子命令。这是钩子和 mnemos serve 使用的规范项目范围；mnemos --project <id> ... 会桥接到相同的运行时环境，供手动命令使用。

Claude 子 Agent 可能无法接收会话开始钩子的上下文。主 Agent 应在委派任务前调用 mnemos_context，并在子 Agent 的任务提示词中包含相关记忆或记忆 ID。

Codex 说明： Codex 使用 CLI 和 VSCode 扩展共用的单一全局配置。--global 和 --local 会被忽略。设置命令会写入 MNEMOS_PROJECT_ID，并接受 --project <id> 作为显式 覆盖项。设置完成后，重启 Codex CLI 和 VSCode 扩展。

---

🤖 与 Trae、OpenClaw、Paperclip 或任何 MCP 客户端配合使用

如果你正在使用 Trae（Solo Agent）、OpenClaw（Claw bot）、Paperclip 或 Claude Desktop 等新兴 AI 框架，可以轻松手动连接 Mnemos。Mnemos 通过 stdio 使用标准 MCP。

只需将以下 JSON 片段添加到客户端的 MCP 配置文件中（例如 trae.json、openclaw.json、paperclip.config.json 或 claude_desktop_config.json）：

{
  "mcpServers": {
    "mnemos": {
      "command": "mnemos",
      "args": ["serve"]
    }
  }
}

---

CLI 参考

mnemos init                                           # first-time setup
mnemos store "..."                                    # store (auto-pipeline)
mnemos search "auth"                                  # hybrid search
mnemos list --project myapp                           # list memories
mnemos get <id>                                       # fetch by id
mnemos update <id> --content "..."                    # update
mnemos delete <id>                                    # soft delete
mnemos relate <src> <tgt> --type supersedes           # typed relation
mnemos stats                                          # storage + quality stats
mnemos maintain                                       # decay + stale + GC
mnemos status                                         # automatic feature configuration
mnemos eval [--project myapp]                         # knowledge quality metrics
mnemos health [--project myapp]                       # raw feature activity
mnemos check [--project myapp] [--mcp-runtime runtime.json]  # verify the automatic knowledge loop
mnemos doctor runtime --from-json runtime.json        # validate live MCP server identity
mnemos check --launch                                 # apply public-launch readiness gates
mnemos check --fix                                    # archive older generated reports safely
mnemos serve                                          # MCP server (stdio)
mnemos version

# Autopilot setup
mnemos setup claude | cursor | kiro | gemini-cli | codex | trae [--global] [--force] [--project <id>]

# Passive autopilot daemon
mnemos autopilot status
mnemos autopilot run [--dry-run] [--project <id>]
mnemos autopilot report [--project <id>]

# Backfill
mnemos backfill summaries --project <id> [--dry-run] [--limit N]

# Benchmark readiness
mnemos bench status
mnemos bench mode on | off
mnemos bench export [--project <id>] [--include-mixed] [--output sessions.csv]

# Hook subcommands (called by clients, not manually)
mnemos hook session-start
mnemos hook prompt-submit
mnemos hook session-end

---

mnemos 不是什么

• 不是聊天机器人记忆 SaaS。 如需在客户支持机器人中回忆用户偏好，请使用 Mem0。
• 不是时态知识图谱数据库。 如需对业务事实进行有效时间/无效时间推理，请使用 Zep。
• 不是云产品。 Mnemos 没有云服务，也永远不会推出。
• 不依赖特定框架。 原生支持 MCP，可与任何支持 MCP 的产品配合使用。

Mnemos 只做一件事：为 Agent 提供能自行编译的知识库。

---

路线图

参见 ROADMAP.md。简要版：

• v1.1.14（当前）： 完整自动化流水线、自动编译、被动自动注入、循环验证、基于来源证明的基准测试、支持 Codex
• v1.2（下一版本）： 分发、公开的基准测试证据、MCP Registry、在 HN 上发布
• v1.3（计划中）： 通过 git 实现团队记忆——共享的 .mnemos/shared/，用于存放团队成员的知识
• v2.0+（待定）： 跨项目记忆范围、记忆压缩，根据用户反馈制定

---

社区

• GitHub 讨论区
• GitHub 问题

---

许可证

MIT