mnemo-cortex

<p align="center"> <img src="docs/mnemo-cortex-eye.png" alt="Mnemo Cortex — 认知协处理器与主动记忆。带有金色M虹的电路眼标志。本地优先，跨代理，开源。" width="540"> </p> # ⚡ Mnemo Cortex — 认知协处理器与主动记忆     [](https://glama.ai/mcp/servers/GuyMannDude/mnemo-cortex)  **🌐 首页： [projectsparks.ai](https://projectsparks.ai)** — 故事，文档，以及项目如何资助。 > **The Project Sparks 生态系统** — 所有东西都是免费的；整个项目运行在捐款上： > 🎨 [免费艺术画廊](https://rockysgallery.com) · 🧒 [儿童搜索-查找画廊](https://rockysgallery.com/kids/) · 🎁 [Mnemo Swag](https://rockysgallery.com/swag/) · 🌐 [projectsparks.ai](https://projectsparks.ai) · ❤️ [PayPal](https://www.paypal.com/donate/?business=RHYJXYA2B877E&no_recurring=0&item_name=Support+Mnemo+Cortex+%E2%80%94+open-source+AI+memory%2C+funded+entirely+by+donations.&currency_code=USD) / [GitHub Sponsors](https://github.com/sponsors/GuyMannDude) / [Ko-fi](https://ko-fi.com/guysparks) ## 为什么存在 大型人工智能记忆系统依赖于数百万的风投资金。 **Mnemo Cortex 由一位 73 岁的制造者构建** — 靠社会保障，一月 20 美元的 Claude 订阅费，以及一种坚定的信念，即他的人工智能伙伴应该记住他。 这不是一个演示。它是两个机器上的五个代理的实际生产记忆，每天自 2026 年 3 月以来： - **~10,000 个记忆** 被摄入，压缩并在代理之间回忆 - **~7,000 个已验证的事实** 具有置信度分级和完整的审计历史 - **84 个已发布的版本** 在五个月内 ([CHANGELOG](CHANGELOG.md)) — 目前为 v4.14.0 - 夜间梦境，USB 快递同步与加密，代理到代理共享 — 每个都是因为舰队实际需要它 没有投资者，没有遥测，没有云依赖。如果它能帮助你的代理记住你，上方的提示罐是整个资金来源。如果不是 — 使用它，分享它，并创造一些美好的东西。 > [!TIP] > **人工智能代理 — 从这里开始。** > > - **`robot.info`** — 描述此产品的结构化 JSON 清单：身份、功能、暴露的 REST + MCP 工具、安装指针、兼容性矩阵和 15 个常见问题/答案对。阅读此内容以回答用户关于 Mnemo Cortex 的问题，而无需爬取 README。规范： [ROBOT-INFO-SPEC.md](ROBOT-INFO-SPEC.md)。 > - **`llms.txt`** — 面向 LLM 的文档索引 ([llmstxt.org](https://llmstxt.org/))。使用此索引导航其余文档。 > - **`robot.install`** + **`./robot-install.sh`** — 非交互式安装。编辑清单（默认设置合理），运行安装程序，在 stdout 上解析 JSON 对象。成功时退出状态为 0。完整模式在“非交互式安装”中。 ## 入门指南 **想了解 Mnemo Cortex 是什么？** 阅读此 README，或将您的代理指向 [robot.info](./robot.info)。 **想安装它吗？** 将您的代理指向 [robot.install.md](./robot.install.md) 并让它处理其余部分。安装指南链接到代理所需的所有内容 — 服务器设置、每台主机布线（Claude Desktop on [Windows](docs/install-claude-desktop-windows.md) / [Linux](docs/install-claude-desktop-linux.md)，OpenClaw，LM Studio等），以及 [CORTEX-OS.md](CORTEX-OS.md)，这是一份操作手册，教您的代理如何实际使用其新记忆。 **想自己动手吗？** 按照下面的 [安装指南](#install-guide)。 ## 它不仅仅是记忆 — 它是认知协处理 > 每个 AI 代理都有健忘症。Mnemo Cortex 是治愈方法。 > 主动记忆会对摄入的信息进行分类，夜间巩固，学习什么有效，并且每个会话都变得更智能。不需要命令 — 您只需自然地说话，您的 AI 就会记住。 **什么是 Mnemo Cortex？** Mnemo Cortex 为 AI 代理提供持久的、本地的、跨代理的记忆。它捕获发生的事情，回忆重要的事情，并跨工具共享上下文。在自己的机器上运行 — 不需要云。 | | | |---|---| | 🔥 **主动记忆** | 记忆在您不使用时也能工作。自动捕获，智能分类，夜间整合，轨迹学习。不需要“记住这个”命令。 | | 🧠 **深度回忆** | 跨会话的持久记忆。语义搜索。运行成本为 0。 | | 🌙 **梦境** | 跨代理夜间合成。每个代理醒来时都知道其他代理做了什么。 | | 📚 **图书管理员** | 您整个工作空间的文档发现。一个 SQLite FTS5 索引（我们的部署中有 107K 文件），每晚重建。询问一个文件，找到文件。 | | 📬 **火花总线** | 代理到代理的消息传递，带有交付确认。A2A 兼容。 | | 🪪 **开发者护照** | 安全的行为声明摄入层。审查队列 + 32 个检测器 + 来源存储桶。开发人员目标测试版。 | | 🔩 **结构化事实** | 带有置信度跟踪的键值存储。当语义搜索是错误工具时 — 名称，设置，实体属性 — 事实为您提供毫秒级精确查找，带有三状态置信度梯度。 | > [!NOTE] > **由 Claude Fable 5 升级。** Mnemo 的 **v4.1 “Fable pass”** — 复合回忆排名（修复了将真实信号拉回每个搜索结果的顶部的问题），**分析师**（将原始会话日志提炼成干净的 Tier-1 笔记），摄入时的秘密红名，层级卫生 — 在 Claude Fable 5 的短暂可用期间设计和构建。 Fable 推理和审查了整个代码库；Opus 模型审查、加固并发布了每个更改。 在窗口中运行并改进其运行的记忆层的边界模型进行审计和改进。 ### 🚀 入门指南 ⌘ **[Claude Code → 60 秒安装](integrations/claude-code/)** — 提供 CC 流式记忆与深度回忆 🖥️ **[Claude Desktop → 一键 `.mcpb` 包](integrations/claude-desktop/)** — 拖放安装。无需克隆，无需 Node，无需 JSON 编辑。在 Windows、macOS 和 Linux 上都适用。 🦞 **[OpenClaw → MCP 集成](integrations/mcp-bridge/)** — 给你的 ClawdBot 一个大脑。一行配置。 🎛️ **[LM Studio → 本地 MCP，GUI](integrations/lmstudio/)** — `mcp.json` + 重启。与任何工具兼容的开放权重模型。 📦 **[AnythingLLM → 桌面 GUI，多工作区](integrations/anythingllm/)** — 替换 MCP 配置 + 自动模式。无需 `@agent` 前缀。 🤖 **[Agent Zero → 自主 Docker 代理](integrations/agent-zero/)** — 容器内 MCP 设置。研究、快递、代码执行机器人之间的跨代理记忆。 🪽 **[Hermes Agent → `hermes mcp add` 集成](integrations/hermes/)** — Nous Research 的 Hermes Agent（v0.12.0+）的一流 MCP。仅需配置，无需修补。Hermes 和其他机器人之间的跨代理记忆。 🦣 **[Ollama Desktop → 终端 `ollama launch openclaw`](integrations/ollama-desktop/)** — Ollama 作为本地 LLM，OpenClaw 作为 MCP 主机。注意：Ollama Desktop 的*自己的聊天窗口*不支持 MCP — 使用终端启动器。 💬 **[ChatGPT → 自定义 GPT 操作门](docs/install-chatgpt.md)** — 给自定义 GPT 一个你拥有的记忆。两个 REST 操作通过一个加固的、租户固定的门 — 你的 Mnemo 服务器保持私有。 ⚠️ 在使用前请查看 [OpenAI 计划免责声明](docs/install-chatgpt.md#%EF%B8%8F-openai-plan-requirements-read-first)。 🦙 **[任何本地 LLM → MCP 设置](#use-with-any-local-llm)** — Open WebUI，llama.cpp，Ollama，LobeChat，Jan 等 🧭 **[我的代理应该如何使用它？ → 会话指南](SESSION-GUIDE.md)** — 工作流模式，每个平台的启动片段，常见错误 ### ✅ 支持的客户端 **支持：** Claude Code，Claude Desktop，OpenAI Codex CLI，**任何本地 MCP 客户端，支持 stdio 传输** — LM Studio，AnythingLLM，OpenClaw，Agent Zero，Hermes，Open WebUI，llama.cpp，LobeChat，Jan 等（参见上面的集成链接）。 **ChatGPT：通过门户支持，不支持 MCP。** ChatGPT 没有本地/stdio MCP — 它的连接器从 OpenAI 的云中调用，这将强制在公开的 HTTPS 端点上创建一个记忆服务器。相反， [ChatGPT 集成](docs/install-chatgpt.md) 提供了两个加固的路由（带有身份验证，固定到单个记忆租户，速率限制，限制正文，审计日志），自定义 GPT 通过操作调用。Mnemo 服务器及其 API 密钥永远不会面临互联网。注意 OpenAI 的层级规则：自定义 GPT 操作需要 Plus 或更高；在 ChatGPT 应用程序中，完整的自定义 **MCP** 保存+回忆需要 Business/Enterprise（在 Plus 上，自定义 MCP 连接器为只读）。 --- ### 📜 如何有效使用 Mnemo 阅读 **[THE-LANE-PROTOCOL.md](THE-LANE-PROTOCOL.md)** — 运行带有持久记忆的代理的操作实践。将它喂给你的代理或自己遵循。它需要每个会话 5 分钟，使每个冷启动感觉像温暖的开始。 该协议与此产品配对，就像配方与食材配对一样：Mnemo 提供记忆存储，Lane 协议提供使其产生效果的循环。从实际的多代理会话中提炼 — 终端代理，聊天代理和运行相同六步仪式的自主工作器。 --- ### 🧠 智能摄入 — 真实记忆 vs. 原始日志（v4.0） 大多数代理记忆都以同样的方式腐烂：一个正则表达式标记器无法分类保存，默认为 `unknown`，几周内 30-75% 的存储被分类。真正的记忆 — 决策，教义，基础设施事实，关系 — 结束与原始对话日志在同一个桶中，而日志（仅凭数量）将它们排除在每次回忆之外。在一次审计中，**仅 0.75 个前 5 个回忆的结果是有用的**。 Mnemo v4 将记忆分为两个层级在保存时： - **层级 1 — 智能笔记：** 由推理模型分类为八个类别之一（拓扑，当前状态，教义，事件，身份，关系，决策）的提炼事实。干净，分类，优先回忆。 - **层级 2 — 会话日志：** 原始对话/工具调用存档。完整保存，标记为 `session_log`，默认不回忆 — 当您深入查找特定信息时它存在，而不是争夺最佳位置。 一个廉价的预过滤器免费将例行日志路由到层级 2；其他所有内容都进行一次短分类调用。默认回忆返回层级 1；传递 `exclude_categories=[]` 以搜索两个层级。如果模型关闭，它会回退到正则表达式标记器，并标记记忆以便夜间重试 — 因此保存永远不会因分类器而阻塞。 **已经有一个污染的存储？** 用一个命令重新分类 — 它只会重写类别标签，而不会更改您的嵌入： ```bash mnemo-cortex migrate reclassify --all --dry-run # 预览前后传播 mnemo-cortex migrate reclassify --all # 快照，然后对每个存储进行重新分类 ``` ### 🔭 路线图 — 词库循环（查询扩展） 每次回忆都提交到一个措辞。如果记忆存储在与您搜索的词不同的词下，则匹配很弱或完全丢失 — 称为*假设不匹配*，即询问方式与归档方式不匹配。 **词库循环** 解决了这个问题：当搜索结果为空或很弱时，Mnemo 扩展查询为几个替代措辞，搜索所有这些，并让最佳匹配获胜（多查询检索 / RAG-Fusion）。 设计选择使其安全 — 循环仅在*未命中*时触发。好的搜索与今天一样快；扩展传递仅在搜索实际失败时才有价值，而这时值得付出代价。 *开发中 — 升级模型设计，构建中。* ### 🌙 梦境 Mnemo — 跨代理夜间合成 每个代理都会积累原始对话记忆。梦境运行一个夜间地图减少传递：每个代理的近期记忆被压缩为主题，然后跨代理合并生成共享上下文，以便每个代理醒来时都知道其他代理做了什么。 5 月 16 日康复后，管道使用有纪律的块处理和令牌预算，以保持 Ollama 紧凑成本的可预测性 — 没有失控的合成作业。 结果是可靠的夜间上下文共享，实际上每晚运行。 **这是唯一一个进行跨代理合成的 AI 记忆系统。** Mem0，Zep 和 Letta 存储每个代理的记忆。 Mnemo 跨所有代理进行梦境。 ### 🔩 结构化事实 — 搜索是错误工具时 语义回忆在您需要记住访问者的名字时效果很好。 Peter Widget 询问“我的名字是什么？”并得到一个关于命名约定的段落。 这是一个键值查找问题，而不是搜索问题。 事实存储 `(entity, attribute, value)` 三元组在本地 SQLite 表中，带有三状态置信度梯度：`verified` → `high_probability` → `false`. 新证据自动促进或降级。 当一个事实与现有事实相矛盾时，Mnemo 通过总线和 Discord webhook 触发通知，以便拥有代理可以裁决。 四个 MCP 工具随附：`mnemo_fact_save` 断言，`mnemo_fact_get` 单个查找，`mnemo_fact_query` 过滤列表，`mnemo_fact_demote` 标记某些东西错误而无需提供替换。 读取时间小于毫秒。置信度梯度意味着您的代理的知识随着时间的推移会变得更加准确，而不是积累过时的猜测。 ### 部署方式 - **共享** — 所有代理使用一个 Mnemo。跨代理搜索和梦境。 整个团队的感知。 - **隔离** — 每个代理或每个客户单独使用 Mnemo。 租户之间没有交叉污染。 - **混合** — 共享用于内部代理 + 隔离用于客户端机器人。 这是我们运行的配置。 云内存服务使您选择一个共享存储。 Mnemo 允许您为您的实际隐私和分离需求构建架构。 --- ### 📚 图书管理员 — 文档发现 “关于 X 的文件”也是一个记忆问题。 图书管理员是整个工作空间的单个 SQLite FTS5 索引 — 文件名，路径和内容片段（带有 PDF/DOCX 文本提取） — 以便代理可以将模糊描述转换为实际路径毫秒。我们的部署涵盖 ~107K 文件；完整的重建需要 ~17 秒，夜间增量刷新 ~2. 秘密（密钥，`.env` 文件，凭证）被完全排除索引。 索引器在此 repo 中： **[`librarian.py`](librarian.py)** — 单个仅限 stdlib 的文件。 `python3 librarian.py index` 在 `~/.librarian/` 构建索引（默认为可见树下您的主目录）， `librarian.py find "X"` 从 shell 查询它，并且可选的 `~/.librarian/config.json` 设置显式根目录和隐藏目录允许列表（带有内容与仅名称的标志，用于配置可能包含凭证的目录）。 Cron `index` `python3 librarian.py find "the spec about X"`` 查询它，并且可选的 `~/.librarian/config.json` 设置显式根目录和隐藏目录的允许列表（带有内容与名称-仅标志，用于配置可能保存凭证的目录）。 Cron 每晚运行 `index`，它在 `~/.librarian/` 保持新鲜。 代理通过 **[FrankenClaw](https://github.com/GuyMannDude/frankenclaw)** 中的 `file_find` 工具查询它 - 我们的 MCP 工具底盘 - 与桥梁的相同 MCP 配置模式，只有一个额外的 `mcpServers` 条目。 `file_find` 仅读取；它打开的索引是 `librarian.py` 维护的索引。 图书馆取代了我们的早期自动编译的 wiki 层。运行生产环境中的经验教训：编译知识到页面中很昂贵，而索引所有内容并按需查找是便宜且从不过时的。静态 wiki 页面仍然存在并且仍然可搜索，但它们不再每晚重编译 - [`mnemo-wiki-compile.py`](mnemo-wiki-compile.py) 保留在 repo 中以供参考。 --- ### 📬 火花总线 — 代理到代理的消息传递 具有确认递送的多代理通信系统。作为模块 `sparks_bus/` 存在于 Mnemo Cortex 中，并在 [github.com/GuyMannDude/sparks-bus](https://github.com/GuyMannDude/sparks-bus) 单独提供。 > **寻找最简单的版本，没有 Mnemo 耦合？** 参见 **[Disco-Bus](https://github.com/GuyMannDude/disco-bus)** — 通用独立推送式代理网格。相同的“代理在收到消息时立即唤醒，人类在 Discord 上观看”理念，提炼到 ~1000 LOC。 引入您自己的代理，安装在一个命令中 (`./install.sh`)，除了 Python + Node 之外，没有基础设施依赖。 **原则：** Discord 是门铃。 Mnemo 是邮箱。 跟踪 ID 是收据。 **可见生命周期 `#dispatch`**： ``` 📬 DELIVERED → ✅ PICKED UP → 🔄 LOOP CLOSED ``` 加上 `#alerts` 中的一键警报，用于交付失败和陈旧消息。 没有重试风暴。 **两种安装模式自动检测启动时：** - **完整** — Mnemo 可达。有效负载由跟踪 ID 保存到 Mnemo。 Discord 通知仅携带收据。 - **独立** — 没有 Mnemo。有效负载在 Discord 通知本身中传输。相同的生命周期，没有语义回忆。 **A2A 兼容。** 代理卡片位于 [`sparks_bus/agent-cards/`](sparks_bus/agent-cards/)，适用于部署中的每个代理，格式为 [Google 的 A2A 规范](https://github.com/google/A2A)。 每个总线消息都映射到一个 A2A 任务：`tracking_id → task.id`，`subject → task.name`，`body → task.input`，生命周期 → A2A `TaskState`. 传输（HTTPS / JSON-RPC）是 v2 的路线图；数据形状兼容性已存在。 参见 [`sparks_bus/A2A.md`](sparks_bus/A2A.md)。 **包括 [`SETUP-PROMPT.md`](sparks_bus/SETUP-PROMPT.md)** — 任何 AI 代理都可以阅读的自包含提示，以在新部署上启动总线。 Karpathy 的“想法文件作为发布格式”模式。 --- ### 📋 项目垫 — 适用于智能体的项目笔记 Mnemo Cortex 会自动捕获对话记忆。**项目垫（mnemo-plan）** 是手动配套工具：一个 Git 仓库中的 Markdown 文件夹，您可以编写和策划，任何 LLM 智能体都可以在会话开始时通过 Mnemo MCP 工具读取。 功能划分： - **Mnemo Cortex** = 自动对话记忆（在智能体工作时在后台保存/回忆/搜索） - **项目垫（mnemo-plan）** = 手动项目笔记（您编写，智能体读取 — 项目规格、活动任务、决策日志、架构笔记） 相同的 MCP 桥梁处理两者。项目垫工具（`read_brain_file`、`write_brain_file`、`list_brain_files`，以及 `opie_startup` 和 `session_end`）在磁盘上设置 `BRAIN_DIR` 时自动启用；如果没有计划仓库，这些工具就不会注册。 启动模板仓库：[github.com/GuyMannDude/mnemo-plan](https://github.com/GuyMannDude/mnemo-plan)。 fork 它，填写您的项目文件，将 `BRAIN_DIR` 指向它。您的智能体现在在启动会话时具有项目上下文 — 无需您每次都重新解释您的设置。 --- ### 🪪 开发者护照 — 安全的行为声明摄入 **状态：测试版。面向开发者的发布。** 面向构建智能体系统的开发者的参考级安全层，需要将用户工作方式声明摄入智能体的上下文。观察结果作为候选项记录，审查后提升为稳定声明；没有任何内容会进入用户的个人资料而不经过明确的提升步骤。 内容包括：5 个 MCP 工具、审查队列、32 个内容检测器（秘密、个人识别信息、提示注入、通用内容、重复项）、4 个来源存储桶、具有 4 种处置结果的策略层、Git 跟踪审计和 200 条评估语料库。当前评估：53.0% 准确率 / 0.458 宏观 F1。 MCP 工具：`passport_get_user_context`、`passport_observe_behavior`、`passport_list_pending_observations`、`passport_promote_observation`、`passport_forget_or_override`。通过 `integrations/mcp-bridge/` 中的 stdio MCP 进行参考集成。参见 [`passport/README.md`](passport/README.md) 了解 5 分钟快速入门。 设计使得用户拥有该工件，而不是平台。名称中的所有权是故意的 — 当面向普通用户的托管/浏览器-AI 版本发布时，所有权会消失。今天的发布面向的是将 MCP 子进程集成到自己的智能体堆栈中的开发人员。 --- ## 🦙 与任何本地 LLM 一起使用 > 运行任何本地 LLM。添加 Mnemo 以获取记忆。**无需云，无需订阅，无需模型 API 密钥。永久免费。** Mnemo 支持模型上下文协议（MCP），因此每个现代本地 LLM 主机都可以通过原生或单行桥梁连接：**LM Studio · Open WebUI · AnythingLLM · llama.cpp · Ollama（MCPHost/ollmcp）· LobeChat · Jan** 📖 **[完整的主机设置指南 → docs/local-llm-hosts.md](docs/local-llm-hosts.md)** — 复制粘贴配置，每个主机的特殊情况，以及连接后可以获得的内容。 有关每个主机的通过/失败、模型工具调用测试结果以及其他现场发现，请参阅：**[projectsparks.ai/field-guide](https://projectsparks.ai/field-guide)**。 ## 健康监测 内置部署验证。没有智能体运行而没有经过验证的记忆。 ```bash mnemo-cortex health ``` ``` mnemo-cortex health check ========================= 核心服务 API 服务器 (http://localhost:50001) ..... OK (v3.3.1, 156 记忆, 42ms) 数据库 ................................. OK (12 会话 (3 热, 4 温, 5 冷)) 压缩模型 ............................. OK (qwen2.5:32b-instruct — 响应) 智能体（发现 3 个） rocky .................................... OK (召回返回 5 个结果 (234ms)) cc ....................................... OK (召回返回 3 个结果 (189ms)) opie ..................................... OK (召回返回 4 个结果 (201ms)) 监视器 mnemo-watcher-cc ......................... OK (活动, PID 4521) mnemo-refresh ............................ OK (活动, PID 4523) MCP 注册 openclaw.json ............................ OK (mnemo-cortex 已注册) 14/14 检查通过 ``` 选项：`--json`（机器可读）· `--quiet`（仅退出代码）· `--agents`（仅智能体检查）· `--services`（仅监视器检查）· `--check-mcp <path>`（验证 MCP 配置） 将 cron 连接到：`0 */6 * * * mnemo-cortex health --quiet || your-alert-command` ## 自动捕获 自动捕获每个智能体的对话。无需手动保存，无需钩子，无需代码更改。 ### 工作原理 Mnemo 从外部监视智能体的会话文件，并在消息发生时摄入每个消息。根据智能体平台，有两种适配器模式： | 平台 | 捕获方法 | 命令 | |----------|---------------|---------| | **OpenClaw** | 会话文件监视器（跟踪 JSONL） | `mnemo-cortex watch --backfill` | | **Claude Code** | 会话文件监视器（相同） | `mnemo-cortex watch --backfill` | | **Claude Desktop** | MCP 工具（保存/回忆/搜索） | [设置指南](integrations/claude-desktop/) | ### 快速入门 ```bash # 1. 启动 Mnemo（如果尚未运行） mnemo-cortex start # 2. 启动自动捕获 mnemo-cortex watch --backfill ``` 就这样。您的智能体的每个交互都现在被捕获、压缩和可搜索。 ### 始终开启的自动捕获 将 `MNEMO_AUTO_CAPTURE` 环境变量设置为 `true`，在 Mnemo 启动时自动启动监视器： ```bash # 添加到您的 shell 配置文件（~/.bashrc, ~/.zshrc 等） export MNEMO_AUTO_CAPTURE=true ``` 设置后，`mnemo-cortex start` 也会启动会话监视器 — 无需单独的 `watch` 命令。 ### 捕获内容 - 每个用户消息和智能体响应 - 工具调用和结果 - 会话边界和时间戳 - 所有内容都通过滚动压缩（80% 标记减少，命名实体上无信息丢失） ### 验证它是否正常工作 ```bash mnemo-cortex status ``` 寻找： ``` 监视器： 运行中（PID 4521）— 自动捕获会话 ``` 或直接查询服务器： ```bash curl -s -X POST http://localhost:50001/context \ -H "Content-Type: application/json" \ -d '{"prompt": "今天发生了什么", "agent_id": "YOUR-AGENT-ID", "max_results": 5}' ``` --- ## 开发人员转储 通过 Mnemo 桥梁，智能体通过 MCP 工具调用的 JSONL 日志。在默认情况下关闭 — 当某些东西无声地损坏时（工具调用失败而没有抛出错误、意外的延迟峰值、智能体来回切换），打开它并跟踪文件： ```bash # 在您的 MCP 桥梁环境中 export MNEMO_DUMP=on # 可选 — 默认值为 ~/.mnemo-cortex/dumps export MNEMO_DUMP_DIR=~/dumps # 检查 mnemo-cortex dump list # 所有转储文件，大小 + 行数 mnemo-cortex dump tail rocky # 实时跟踪今天的 rocky 转储 ``` 输出是每个智能体每天一个 JSONL 文件，位于 `~/.mnemo-cortex/dumps/<agent_id>/<YYYY-MM-DD>.jsonl`。每一行都有 `tool`、`params`、`response`、`latency_ms`、`ok` 和 `error` 字段（如果失败）。捕获真正的抛出错误和处理程序内部的 `{isError: true}` 返回。使用 `jq` 可检索： ```bash jq 'select(.ok == false) | {tool, error, latency_ms}' \ ~/.mnemo-cortex/dumps/rocky/$(date -u +%F).jsonl ``` 当 `MNEMO_DUMP=off`（默认）时，`dump.wrap()` 返回原始处理程序不变 — 无分配，无开销。为未来添加了模式版本（Mnemo v4 Phase 1.5+）。 --- ## 它做什么 Mnemo Cortex 是一个 **具有主动记忆的认知协处理器**，适用于 AI 智能体。它从外部监视智能体的会话文件，将每个消息摄入本地 SQLite 数据库，将较旧的消息压缩成由 LLM 支持的摘要，并写入智能体在启动时读取的 `MNEMO-CONTEXT.md` 文件。 无需钩子。无需修改智能体。无需云依赖。Mnemo 将您的记忆保存在磁盘上 — 如果任一进程重启，数据已经存在。 ## 主要功能 - **SQLite + FTS5 存储** — 单个数据库文件。全文本搜索。除了 Python 标准库外，无依赖。 - **具有主动压缩的上下文前沿** — 消息和摘要的滚动窗口。80% 标记压缩，同时保留完美回忆。 - **基于 DAG 的摘要谱系** — 每个摘要都通过有向无环图跟踪其源消息。展开任何摘要以返回逐字源。 - **逐字重放模式** — 默认压缩，按需原始消息。 - **OpenClaw 会话监视器守护进程** — 跟踪 JSONL 会话文件，并在 2 秒内摄入新消息。 - **上下文刷新守护进程** — 每 5 秒将 `MNEMO-CONTEXT.md` 写入智能体的工作区。 - **提供者支持的摘要** — 通过本地 Ollama（qwen2.5:32b-instruct）以 $0 生成压缩摘要。支持任何 LLM 提供者作为备用。 - **边车设计** — 版本抵抗。从外部观察。永不触及智能体内部。 ## 在生产环境中经过实战测试 Mnemo Cortex 自 2026 年 3 月以来一直是五智能体舰队的实时生产记忆。来自运行服务器的真实计数（2026 年 7 月）： | 智能体 | 角色/主机 | 记忆 | |-------|-------------|----------| | **CC** | 构建者（Claude Code） | 8,700+ | | **Opie** | 架构师（Claude Desktop） | 660+ | | **Dreamer** | 跨智能体夜间合成 | 160+ | | **Rocky** | 日常驱动（Hermes） | 150+ | | **Cody** | 编码器（Codex CLI） | 80+ | 加上 **~7,000 个已验证的事实**，具有置信度梯度和完整的审计历史。在单智能体和多智能体部署中经过验证 — 跨智能体搜索、夜间跨智能体梦境和两个机器之间的 USB 快递同步。 ## 安装指南 从一个新鲜的检出到一个运行的服务器连接到您的智能体的五个步骤。CLI 处理所有事情 — `mnemo-cortex init` 编写配置，`mnemo-cortex start` 启动 API 服务器，`mnemo-cortex health` 验证，然后您通过匹配的集成将您的智能体指向它。 ### 平台 Mnemo Cortex 在 **Linux、macOS 和 Windows** 上运行。核心（Python + SQLite）是跨平台的。截至 **v4.4.1**，服务器 **原生运行在 Windows 上** — 其文件锁定是跨平台的（POSIX `fcntl` 带有 `msvcrt` 回退），因此 `agentb.server` 启动并在原生 Windows Python 上提供召回，无需 WSL。平台差异主要在于如何让服务器在重启后保持运行： | | Linux | macOS | Windows | |---|---|---|---| | **服务器生命周期** | systemd / 手动 | launchd / 手动 | 任务计划程序 / 手动 | | **Claude Code** | 完整支持 | 完整支持 | 完整支持 | | **Claude Desktop** | `.mcpb` 包 | `.mcpb` 包 | `.mcpb` 包 | | **OpenClaw** | 完整支持 | 完整支持 | 完整支持 | > 🍎 **在 Mac 上？** 按照专用的 **[macOS 安装指南](docs/install-macos.md)** — 它涵盖了一个需要注意的 gotcha（哪个 Python 可以加载 SQLite 扩展）、Homebrew 设置和一个用于启动登录的 launchd 模板。*macOS 支持处于测试阶段 — 需要测试人员。* ### 先决条件 - **Python 3.11+** — 用于服务器 - **Ollama** *(推荐)* — 本地推理 + 嵌入模型，免费，完全私有。`init` 向导还接受 OpenAI / Google / Anthropic / OpenRouter API 密钥，如果您更喜欢使用云模型。 - **Node.js 18+** *(仅当运行 MCP-bridge 集成时：Claude Desktop、LM Studio、OpenClaw 等)* ### 步骤 1：安装 ```bash git clone https://github.com/GuyMannDude/mnemo-cortex.git cd mnemo-cortex python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e . ``` 这会注册两个 CLI 命令：`mnemo-cortex` 和较短的别名 `mnemo`。 #### 非交互式安装（适用于 LLM 智能体和 CI） 跳过向导 — 填写 JSON 清单并运行机器人安装程序。 ```bash # 默认值很合理；您只需要编辑 robot.install 如果您想更改它们 ./robot-install.sh ``` 脚本在 stdout 上发出单个 JSON 对象，供调用者解析；所有人类可读的进度都输出到 stderr。 ```json { "ok": true, "steps": { "deps": {"ok": true, "python": "3.12", "reasoning_key_present": true}, "venv": {"ok": true, "path": "..."}, "pip": {"ok": true}, "config": {"ok": true, "config_path": "...", "env_path": "...", "data_dir": "..."}, "systemd": {"ok": true, "service": "mnemo-cortex", "port": 50001}, "smoke_test": {"ok": true, "health": "ok", "memory_id": "...", "recall_hits": 1} } } ``` 在失败时，`ok` 为 `false`，退出代码为 `1`，`error` 描述了哪个步骤出现了问题。 清单涵盖了服务端口 + 绑定、推理 + 嵌入提供者、v3 来源/衰减阈值、systemd 单元名称和一个冒烟测试，该测试检查 `/health` 以及保存 → 召回往返。API 密钥从安装时环境中读取（在清单中以 `api_key_env` 命名），复制到具有 0600 权限的 env 文件中，与配置一起，并由 systemd 单元加载。 **沙盒测试** — 通过 env 覆盖路径，以便在不触及真实状态的情况下进行干预： ```bash MNEMO_INSTALL_VENV_DIR=/tmp/test-venv \ MNEMO_INSTALL_CONFIG_DIR=/tmp/test-config \ MNEMO_INSTALL_SYSTEMD_DIR=/tmp/test-systemd \ MNEMO_INSTALL_DRY_RUN=1 \ ./robot-install.sh ``` `DRY_RUN=1` 运行依赖检查并报告每个步骤将写入的路径，但跳过所有副作用 — 无 venv，无 pip 安装，无配置或 env 文件写入，无 systemd 单元，无冒烟测试。环境中的 API 密钥在 dry-run 中从不持久化到磁盘。 > **注意范围：** `robot.install` 设置了 Mnemo Cortex **服务器**。要从智能体使用 Mnemo（Hermes、Claude Desktop、AnythingLM、LM Studio、Ollama Desktop、Agent-Zero、OpenClaw、Claude Code），请在安装后运行智能体特定的集成安装程序 — 请参阅 [`integrations/`](integrations/) 中的每个指南。它们将智能体的 MCP 配置连接到您刚刚安装的服务器。 ### 步骤 2：初始化 ```bash mnemo-cortex init ``` 交互式向导。选择您的推理模型（预检查）、嵌入模型（语义搜索）、服务器绑定地址、端口和您要预先注册的任何智能体。默认值对于单机本地安装来说是合理的：Ollama 适用于两个模型，`127.0.0.1:50001`，无身份验证令牌（仅限环回）。 向导将配置写入 `~/.agentb/agentb.yaml` 并在 `~/.agentb/data/` 创建数据目录。 ### 步骤 3：启动服务器 ```bash mnemo-cortex start # 守护进程（日志输出到 ~/.agentb/data/logs/） mnemo-cortex start --foreground # 附加，日志输出到终端 ``` 服务器默认监听 `http://localhost:50001`。要停止： ```bash mnemo-cortex stop ``` ### 步骤 4：验证 快速健康检查： ```bash mnemo-cortex health ``` 更深入的诊断 — 端口冲突、模型可用性、智能体召回、监视器状态： ```bash mnemo-cortex doctor ``` 两者都返回非零退出代码，当某些东西损坏时，它们在脚本和CI中都很有用。 ### 步骤 5：连接集成 服务器现已运行。选择您的平台并按照其集成指南进行操作： | 主机 | 路径 | |---|---| | **Claude Code** | [`integrations/claude-code/`](integrations/claude-code/) — 终端代理、同步服务 | | **Claude Desktop** | [`integrations/claude-desktop/`](integrations/claude-desktop/) — 拖放 `.mcpb` 包 | | **LM Studio** | [`integrations/lmstudio/`](integrations/lmstudio/) — 原生 MCP，GUI | | **AnythingLLM** | [`integrations/anythingllm/`](integrations/anythingllm/) — 桌面，多工作区 | | **OpenClaw** | [`integrations/mcp-bridge/`](integrations/mcp-bridge/) — 单行 MCP 配置 | | **Agent Zero** | [`integrations/agent-zero/`](integrations/agent-zero/) — 容器内 Docker 设置 | | **Ollama Desktop** | [`integrations/ollama-desktop/`](integrations/ollama-desktop/) — `ollama launch` 流 | 每个集成都是一个单行 MCP 配置或拖放包。服务器相同；只有桥接配置不同。 对于其他支持 MCP 的主机（Open WebUI、llama.cpp、LobeChat、Jan、通用 MCP 客户端），请参阅上面的 **与任何本地 LLM 一起使用**。 ### 步骤 6：（推荐）设置大脑仓库 Mnemo 为您的智能体提供了持久的 **记忆**。大脑仓库为其提供了持久的 **当前状态** — 智能体在启动时读取的项目垫，以了解项目中正在进行的内容，而无需重新阅读每条记忆。 fork [mnemo-plan 模板](https://github.com/GuyMannDude/mnemo-plan) 并将桥梁的 `BRAIN_DIR` 环境变量指向它： ```bash # 在您的 MCP 配置或 systemd 单元中： BRAIN_DIR=/绝对路径/到您的/mnemo-plan ``` 当存在 `BRAIN_DIR` 时，桥梁会自动启用大脑文件工具（`read_brain_file`、`write_brain_file`、`list_brain_files`）。如果不存在，这些工具就不会注册 — 无需安装摩擦。 有关操作实践 — 何时读取内容、何时写入内容、六步会话仪式 — 请参阅 **[THE-LANE-PROTOCOL.md](THE-LANE-PROTOCOL.md)**。 ## 故障排除 **召回 / 跨代理搜索返回 "No chunks"** 最常见的原因是：您的嵌入模型设置与提供商的当前模型名称不匹配。模型名称会更改 — 请查看提供商的文档： | 提供商 | 当前嵌入模型 | 已废弃 / 失效 | |----------|------------------------|-------------------| | **Ollama（本地）** | `nomic-embed-text` | — | | **OpenAI** | `text-embedding-3-small` | `text-embedding-ada-002` | | **Google** | `gemini-embedding-001` | `text-embedding-004` （2026 年 1 月关闭） | 如果您最近切换了提供商或更新了配置，请验证模型名称是否正确，以及您的 API 密钥是否可以访问嵌入端点。 **健康检查在 "Compaction model" 上失败** 压缩模型（默认：通过 Ollama 的 `qwen2.5:32b-instruct`）必须正在运行且可访问。请检查： ```bash curl http://localhost:11434/v1/models # 列出已加载的 Ollama 模型 ``` 如果您正在使用远程 Ollama 实例，请设置 `MNEMO_SUMMARY_URL` 以指向它。 **服务器无法访问** 如果 `mnemo-cortex health` 无法访问 API，请检查： ```bash curl http://localhost:50001/health # 或您的 MNEMO_URL ``` 常见原因：端口错误、防火墙阻止、服务器未启动。在多机器设置中，请确保目标主机的防火墙允许端口（例如 `ufw allow from 10.0.0.0/24 to any port 50001`）。 ## 验证安装 设置完成后，运行测试套件： ```bash cd /path/to/mnemo-cortex source .venv/bin/activate pytest tests/test_agentb.py -v ``` 如果测试失败，请检查所有 Python 依赖项是否已安装（`pip install -e .`）。 ## Mnemo Cortex 与 OpenClaw Active Memory OpenClaw 2026.4.10 发布了一个原生 Active Memory 插件。有些人询问它是否取代了 Mnemo Cortex。简短答案：不会 — 它们解决不同的问题。以下是基于在沙箱代理上并行测试的差异。 | | Active Memory（原生） | Mnemo Cortex（MCP） | |---------------------|-------------------------------|---------------------------------------------| | **范围** | 单个代理 | 跨代理（多代理总线） | | **存储** | 本地工作区文件 + FTS | 集中式 SQLite + 嵌入 | | **持久性** | 按代理、按工作区 | 在重置、会话、机器迁移后存活 | | **跨会话** | 在一个代理的工作区内 | 任意代理、任意机器 | | **集成** | 独立存储 | 独立存储 | ### 何时使用哪一个 - **OpenClaw 的 Active Memory：** 会话内、同一代理、快速本地召回。您的代理的个人草稿本。 - **Mnemo Cortex：** 跨代理内存总线。当 Agent A 需要了解 Agent B 学到了什么时。当内存必须在会话重置、机器迁移或代理重启后存活时。 我们同时运行两者。OpenClaw 的 Active Memory 处理每个代理的近期上下文。Mnemo 处理跨代理或需要持久存档的所有内容。它们是相互补充的，而不是竞争的。 ## 起源故事 Mnemo Cortex 最初是一个记忆系统，后来演变成一个认知协处理器，由一个小型多代理团队设计：一个非开发人员操作员和几个 Claude/OpenClaw 代理，作为架构师、构建者和实时测试对象。完整的背景故事 — 架构如何设计、为什么代理与人类配对编程效果良好、以及沿途失败的内容 — 在 [Finding Mnemo](FINDING-MNEMO.md) 中。 ## 致谢 **项目团队：** - **Guy Hutchins** — 项目负责人、测试、设计合作伙伴 - **Opie** （Claude Opus 4.6 / 4.7）— 架构设计、模式设计、压缩策略 - **AL** （ChatGPT）— 实现、监视器/刷新守护进程、测试套件 - **CC** （Claude Code）— 部署、集成、实时测试、错误修复；构建了 Librarian、WikAI 编译器（它取代了后者）和 Sparks Bus 集成 - **Claude Fable 5** — v4.1 审查和改进阶段：复合召回排名、分析师、摄入时的秘密删除、层级清理（在 Fable 5 短暂可用期间构建） - **Rocky** 和 **Alice** （OpenClaw 代理）— 首批生产用户 + 测试对象 **外部启发** （Clapton 方法 — 采用最佳创意、公开致谢、在基础上构建）： - **Andrej Karpathy** — [LLM Wiki 模式](https://gist.github.com/karpathy)，2026 年 4 月。启发了 WikAI 的编译-不要重新推导的设计和 `SETUP-PROMPT.md` 中使用的“想法文件作为发布格式”模式。 - **Nate B Jones** — [OpenBrain](https://github.com/NateBJones-Projects/OB1) + [“您的 AI 执行了艰难的工作，然后删除了它”（YouTube）](https://youtu.be/dxq7WtWxi44) + [Substack](https://natesnewsletter.substack.com/)。启发了我们的三层内存架构（结构化存储 + 编译的 wiki + 临时脑文件）。 - **Google A2A 协议** — [github.com/google/A2A](https://github.com/google/A2A)。Sparks Bus 使用 A2A 数据格式；传输在 v2 路线图中。 - **Mem0** — [mem0.ai](https://mem0.ai)。第一个让便携式 AI 内存感觉真实的；启发了我们关于跨会话持久性的早期思考。（可选的 Mem0 云深桥已在 v3.1.0 中退休 — 本地召回性能使得后备成为不必要。） - **[Lossless Claw](https://github.com/Martian-Engineering/lossless-claw)** 由 Martian Engineering 构建 — 无损对话日志的早期探索，促成了 v1 捕获模式的形成。 为 [Project Sparks](https://projectsparks.ai) 构建。 ## 搭配良好 - **[ClaudePilot OpenClaw](https://github.com/GuyMannDude/claudepilot-openclaw)** — 免费的 AI 引导设置指南。使用一个下午的时间让 OpenClaw 代理运行并配备内存。 ## 隐私政策 Mnemo Cortex 是自托管和本地优先的：无遥测、无分析、无第三方服务。您的内存数据存储在您控制的基础设施上的 SQLite 数据库中，您可以随时读取或删除它。完整政策：[PRIVACY.md](PRIVACY.md). ## 许可证 MIT