Iron-mem

<p align="center"> <img src="memorylogo.png" alt="IronMem" width="120"/> <br/> <img src="assets/title.png" alt="IRON-MEM" width="300"/> </p> <p align="center"> <strong>用于 AI 编程辅助的持久化内存。</strong> </p> <p align="center"> 每次开始新会话时，不再需要重复解释你的项目。 </p> <p align="center"> <a href="#安装">安装</a> • <a href="#工作原理">工作原理</a> • <a href="#命令行界面">命令行界面</a> • <a href="#多提供商支持">多提供商支持</a> • <a href="#贡献">贡献</a> </p> <p align="center"> <img src="https://img.shields.io/badge/built_with-Rust-F74C00?style=for-the-badge&logo=rust&logoColor=white" alt="Built with Rust"/> <img src="https://img.shields.io/badge/MCP-Native-6c5ce7?style=for-the-badge" alt="MCP Native"/> <img src="https://img.shields.io/badge/SQLite%20%2B%20Postgres-003B57?style=for-the-badge&logo=sqlite&logoColor=white" alt="SQLite + Postgres"/> <img src="https://img.shields.io/badge/Docker%20Ready-2496ED?style=for-the-badge&logo=docker&logoColor=white" alt="Docker Ready"/> <img src="https://img.shields.io/badge/license-Apache--2.0-brightgreen?style=for-the-badge" alt="License"/> <img src="https://img.shields.io/github/stars/BMC-INC/Iron-mem?style=for-the-badge&color=yellow" alt="Stars"/> <img src="https://img.shields.io/github/issues/BMC-INC/Iron-mem?style=for-the-badge" alt="Issues"/> <a href="https://github.com/BMC-INC/Iron-mem/actions/workflows/rust.yml"><img src="https://github.com/BMC-INC/Iron-mem/actions/workflows/rust.yml/badge.svg" alt="CI"/></a> </p> <p align="center"> <img src="https://img.shields.io/badge/works_with-Claude_Desktop-D97706?style=flat-square&logo=anthropic&logoColor=white" alt="Claude Desktop"/> <img src="https://img.shields.io/badge/works_with-Claude_Code-D97706?style=flat-square&logo=anthropic&logoColor=white" alt="Claude Code"/> <img src="https://img.shields.io/badge/works_with-Cursor-000000?style=flat-square&logo=cursor&logoColor=white" alt="Cursor"/> <img src="https://img.shields.io/badge/works_with-ChatGPT_Desktop-10a37f?style=flat-square&logo=openai&logoColor=white" alt="ChatGPT Desktop"/> <img src="https://img.shields.io/badge/works_with-Copilot-2b3137?style=flat-square&logo=github&logoColor=white" alt="Copilot"/> <img src="https://img.shields.io/badge/works_with-Windsurf-06B6D4?style=flat-square" alt="Windsurf"/> <img src="https://img.shields.io/badge/works_with-Zed-000000?style=flat-square" alt="Zed"/> </p> --- <!-- SEO Keywords: AI coding assistant memory, session-aware AI tools, Rust AI tools, context preservation, Claude Code memory, Cursor context --> ## v0.4.0 新增功能 > IronMem 现已成为一个完整的持久化内存栈：可逆原始数据、类型化内存、时间图检索、过程内存、自适应摘要/展开上下文，以及 21 种 MCP 工具。 - **CCR — 无损可逆内存** （Headroom pattern）：每次截断的工具输出和逐字记录的预 LLM 会话记录都保存在数据库内的内容寻址、重复数据删除、字节精确压缩的 blob 存储中。 **`retrieve_original`** 通过 `observation_id`、`memory_id`、原始 blob `hash` 或新的 `chunk_id` 扩展句柄拉回确切的原始数据。 - **内存范围和类型化内存** （Supermemory patterns）：内存具有 **范围** （`project` vs. `user`/跨项目）和 **类型** （`session`、`fact`、`error_solution`、`preference`、`procedural`、`architecture`、`learned_pattern`、`project_config`、`profile`）。会话开始注入优先考虑 **project ∪ user** 内存并提升持久类型。 - **双输出压缩**：会话压缩同时写入叙事内存和可搜索的 `kind=fact` 内存，以便日期、名称、数量和直接答案在总结时存活下来。 - **时间检索 + 图检索**：已标记的事实和 `event_time` 元数据支持时间戳查找，而 `memory_edges` 存储带有有效时间过滤器和出处证明的结构化 `source | relation | target` 边。时间查询路由到带有日期的事实；关系查询路由到图边。 - **自适应工作内存摘要**：每个压缩或显式内存都具有持久的 `memory_chunks`，包含密度（`high`、`medium`、`low`）、类型、标题、令牌估计和可选的精确转录偏移。代理可以广泛使用 **`memory_skim`**，然后使用 **`retrieve_original(chunk_id=...)`** 展开确切的证据。 - **受控检索**：内存现在具有持久的治理信封：命名空间、源类型、信任层、编写者/源出处、分类、同意状态、驻留地、保留元数据、法律冻结、墓碑状态、记录哈希和附加日志哈希链。读取默认情况下具有命名空间范围和仅活动；PHI/PII 编写失败，除非授予同意。 - **闭环内存质量**：注入事件和显式反馈现在加强有用的内存并衰减重复忽略或纠正的内存，减少陈旧上下文而不删除出处。 - **AST-bound Rust anchors**：`ironmem code-relink` 使用 Tree-sitter 来哈希 Rust 符号并在代码跨文件移动时重新链接内存。 - **反射、快照和同步**：dry-run-first 整合提案、CCR 支持的项目脑快照和 idempotent Lamport-clock sync 事件日志支持长期和多代理内存工作流。 - **`remember` 工具**：在一次调用中存储显式、类型化的内存（`scope`、`kind`、`text`、`tags`）。用户范围的事实跟随您进入每个项目，也进入摘要层。 - **用户配置文件**：跨项目内存被提炼成一个单一的、始终注入的配置文件（LLM 摘要，或离线时确定性的本地汇总）。使用 **`get_profile`** / **`refresh_profile`** 读取/重新生成。 - **纠正矿工**：会话中的错误→修复循环（失败的命令、编辑，然后相同的命令通过）被挖掘成 `error_solution` 内存，并通过 **`list_corrections`** 展现，以便在工作重新出现时，过去的修复会重新出现。 - **21 种 MCP 工具**：包括 `memory_skim`、`retrieve_original`、`remember`、`get_profile`、`refresh_profile`、`list_corrections`、`memory_graph` 和 `reconcile_memory_graph`。 - **当前验证**：`cargo test --bin ironmem` 通过 **160 个测试** 和 **1 个被忽略的基准测试**，`cargo test --test mcp_stdio_clean` 通过，`cargo clippy --bin ironmem -- -D warnings` 是干净的。 - **仍然没有遥测数据。仍然本地优先。您的数据仍然属于您。** <details> <summary>v0.3.0</summary> - **多提供商压缩**：使用 OpenAI、Google Gemini 或 Anthropic 作为您的 LLM。在设置中添加 `"provider": "openai"`。 - **Neovim 插件**：原生 Lua 插件，具有自动会话生命周期、`:IronMemSearch`、`:IronMemStatus` - **Windows 支持**：`install.ps1`、平台感知消息、强大的主目录检测 - **Web UI**：在 `http://localhost:37778/ui` 处浏览、搜索和删除内存 - **发现工具**：列出已知项目、跨项目搜索和检查每个项目的会话历史 - **仍然没有遥测数据。仍然本地优先。您的数据仍然属于您。** </details> <details> <summary>v0.2.0</summary> - **13 种 MCP 工具**：session_start、session_end、record_event、compress_session、get_context、get_status、list_memories、search_memories、search_global、list_projects、list_sessions、inject_context、wipe_project - **双数据库**：SQLite（本地，FTS5 全文搜索）+ Postgres（自托管，tsvector）通过 `DATABASE_URL` - **每个 MCP 客户端**：Claude Desktop、Claude Code、Cursor、Windsurf、ChatGPT Desktop、Zed 等 - **Docker 部署**：`docker-compose up` 用于远程/团队设置与 Postgres - **`ironmem mcp`**：用于直接 MCP stdio 传输（Claude Desktop/Code）的新子命令 - **REST 服务器仍然有效**：现有的钩子和基于 curl 的工作流不受影响 </details> --- IronMem 为 AI 编程工具提供跨会话的持久化内存。 它会悄悄记录会话期间发生的事情，将其压缩成简洁的内存，然后自动将该上下文注入到您的下一个会话中。 无需复制粘贴。 无需重建上下文。 无需“记得我们昨天重构了身份验证吗？” **与所有主要的 AI 编程工具配合使用**：Claude Code、Claude Desktop、Cursor、Windsurf、ChatGPT Desktop、GitHub Copilot、Zed、VS Code 和任何与 MCP 兼容的客户端。 **使用您已经付费的 LLM 进行压缩**：Anthropic Claude、OpenAI GPT-4o 或 Google Gemini。只需更改一次配置即可切换提供商。 **免费且开源**。在本地或您自己的基础设施上运行。没有遥测数据。没有云依赖。没有订阅。支持 SQLite 或 Postgres 存储。纯 Markdown 输出。单个 Rust 二进制文件。 <p align="center"> <img src="assets/demo.gif" alt="IronMem in action" width="640"/> </p> ## 为什么存在 AI 编程工具在会话内非常出色，但在会话之间却很糟糕。 它们可以帮助您更快地交付产品，但每个新的会话都会忘记您的架构决策、调试线索和昨天更改的内容。 IronMem 解决了交接的问题。 ## 之前 vs 之后 没有 IronMem： > “我们已经更改了身份验证中间件，切换到 JWT，更新了迁移并修复了计费中的测试。让我再次解释整个过程。” 使用 IronMem： > 打开一个新会话。您的助手已经具备最近的项目上下文。 --- ## 快速入门 1. **安装 IronMem**： ```bash curl -fsSL https://raw.githubusercontent.com/BMC-INC/Iron-mem/main/install.sh | bash ``` 2. **将您的 API 密钥添加到 IronMem 的密钥文件中**： ```bash echo "your-key-here" > ~/.ironmem/api_key && chmod 600 ~/.ironmem/api_key ``` > **优先使用密钥文件而不是 `export ANTHROPIC_API_KEY`**。Claude Code（以及其他一些工具）会在 shell 中设置 `ANTHROPIC_API_KEY` 时，使用按需付费的 API 信用额度，而不是您的 Claude 订阅。密钥文件将 IronMem 的密钥从环境中分离出来，以免影响其他工具的计费方式。（IronMem 仍然会遵守 `ANTHROPIC_API_KEY` 如果您更喜欢环境变量。） 3. **开始编码！** IronMem 会在后台悄悄处理其余部分。 --- ## 目录 - [快速入门](#快速入门) - [问题](#问题) - [解决方案](#解决方案) - [谁应该使用此工具？](#谁应该使用此工具？) - [工作原理](#工作原理) - [当前内存栈](#当前内存栈) - [安装](#安装) - [命令行界面](#命令行界面) - [多提供商支持](#多提供商支持) - [MCP 设置](#mcp-设置) - [MCP 工具](#mcp-工具) - [Web UI](#web-ui) - [受控内存](#受控内存) - [配置](#配置) - [测试状态](#测试状态) - [故障排除](#故障排除) - [架构](#架构) - [为什么选择 Rust？](#为什么选择rust？) - [设计原则](#设计原则) - [为什么不直接使用 CLAUDE.md？](#为什么不直接使用-claudemd？) - [路线图](#路线图) - [贡献](#贡献) - [支持](#支持) - [许可证](#许可证) --- ## 问题 每次您与 Claude Code、Cursor、Copilot 或任何 AI 编程助手启动新会话时 - 它都会从零开始。它不知道您昨天构建了什么。它不知道什么东西坏了。它不知道您做出了什么决定。 **您最终会在每次会话中重复解释上下文。** ## 解决方案 IronMem 悄悄记录编程会话期间发生的事情，使用您选择的 LLM 提供商将其压缩成简洁的内存，然后自动将该上下文注入到您的下一个会话中。 无需每次都设置。无需复制粘贴。无需“记得我们之前……” <p align="center"> <img src="assets/demo.gif" alt="IronMem in action" width="640"/> </p> > **没有 IronMem：** _“嘿 Claude，记得我们昨天重构了身份验证中间件并切换到 JWT 了吗？还有用户表的数据库迁移？还有……”_ > > **使用 IronMem：** 您打开一个新会话。它已经知道。 --- ## 谁应该使用此工具？ IronMem 设计适用于： - **对 AI 工具每次会话都感到沮丧的开发者**。 - **在大型、多会话项目中合作的团队**，其中上下文很容易丢失。 - **在多个 AI 工具（如 Copilot、Claude Code、Windsurf 或 Cursor）之间频繁切换的开发者**。 - **希望保持流程和连续性而不费力的独立开发者**。 --- ## 工作原理 ```mermaid flowchart LR A["🟢 会话开始"] -->|注入内存| B["📄 IRONMEM.md"] B --> C["🤖 AI 读取上下文"] C --> D["🔧 您编码"] D -->|每次工具调用| E["🗄️ SQLite"] D --> F["🔴 会话结束"] F -->|通过 LLM 压缩| G["🧠 内存"] G -->|下一个会话| A style A fill:#22c55e,color:#fff,stroke:none style F fill:#ef4444,color:#fff,stroke:none style G fill:#8b5cf6,color:#fff,stroke:none style E fill:#0ea5e9,color:#fff,stroke:none ``` 一切都在本地运行。您的数据保留在您的机器上。 --- ## 当前内存栈 IronMem 现在将内存存储在多个协作层中，而不是一个扁平的摘要中： | 层级 | 存储内容 | 重要性 | | ----- | -------------- | -------------- | | **会话转录 CCR** | 逐字记录的预 LLM 会话转录和大型/截断的工具输出的内容寻址压缩的 blob | 可恢复确切的原始数据；摘要永远不是唯一的副本 | | **叙事内存** | `memories` FTS 表中的简洁会话摘要 | 快速的项目历史和普通的会话召回 | | **类型化事实** | 从压缩中提取的单独 `kind=fact` 内存 | 直接答案、日期、名称、数量和基准样式的查找在总结中存活下来 | | **过程内存** | 作为 `kind=procedural` 的可重用工作流规则 | 未来代理可以回忆“我们如何工作”而不将过程混入叙事内存中 | | **错误解决方案** | 挖掘的 fail→edit→pass 环作为 `kind=error_solution` | 过去的修复在出现相同的失败模式时会被恢复 | | **用户配置文件** | 全局 `scope=user`、`kind=profile` 内存 | 稳定的跨项目事实始终被注入 | | **时间图** | 带有有效时间字段、置信度和内存出处的 `source | relation | target` 边 | 关系问题和操作员 OS 实体状态可以使用图遍历而不是仅向量相似性 | | **自适应摘要块** | 带有 `chunk_id`、密度、类型、标题、摘要、令牌估计和可选的精确转录字节偏移的 `memory_chunks` 行 | 代理可以扫描广泛的压缩历史，然后在需要时展开确切的证据 | 检索方式根据查询形状路由： - **时间查询** （`when`、`what date`、`which year`、`before`、`after` 等）优先考虑带有日期的 `kind=fact` 内存，并抑制图仅命中，否则会促进关系内存而非时间戳答案。 - **关系查询** 保持图融合启用，并按关系/源/目标重叠对边进行排序。 - **一般项目召回** 混合 FTS、向量（如果可用）、事件时间提升、图信号、种类提升、重要性和新鲜度。 - **摘要/展开工作流** 首先使用 `memory_skim` 或 `/skim`，然后使用 `retrieve_original` 并带有 `chunk_id` 以获取确切的转录证据。 这是故意与模型无关的。持久存储是硬令牌、结构化且可审计的，因此 Claude、Codex、Operator OS、桌面客户端和远程 MCP 客户端可以共享相同的后台内存。 --- ## 安装 ```bash curl -fsSL https://raw.githubusercontent.com/BMC-INC/Iron-mem/main/install.sh | bash ``` 或克隆并手动构建： ```bash git clone https://github.com/BMC-INC/Iron-mem.git cd Iron-mem chmod +x install.sh ./install.sh ``` **Windows： ```powershell git clone https://github.com/BMC-INC/Iron-mem.git cd Iron-mem powershell -ExecutionPolicy Bypass -File install.ps1 ``` 将 IronMem 添加到您的 `PATH`（在 `~/.zshrc` 或 `~/.bashrc` 中）并将您的 API 密钥写入 IronMem 的密钥文件： ```bash export PATH="$HOME/.ironmem/bin:$PATH" # in ~/.zshrc / ~/.bashrc echo "your-key-here" > ~/.ironmem/api_key && chmod 600 ~/.ironmem/api_key ``` > 使用密钥文件，而不是 `export ANTHROPIC_API_KEY` — 全局 `ANTHROPIC_API_KEY` 会使 Claude Code（以及类似工具）使用按需付费的 API 信用额度，而不是您的订阅。IronMem 读取 `~/.ironmem/api_key` 自动。 重启您的终端和 Claude Code。就是这样。 **要求：** Rust/Cargo（安装程序会告诉您是否缺少） ## CLI 命令 ```bash ironmem server # 启动 REST + MCP SSE 服务器 ironmem mcp # 启动 MCP stdio 服务器（适用于 Claude Desktop/Code） ironmem serve # 启动带有 bearer token 认证的 SSE 服务器 ironmem serve --public # 相同 + Cloudflare Tunnel 适用于远程 MCP 客户端 ironmem serve --public --no-auth # 无认证的公共隧道，适用于 claude.ai 个人使用 ironmem status # 健康检查 + 数据库统计 ironmem projects # 所有具有存储记忆的项目 ironmem list # 当前项目的最近记忆 ironmem search "身份验证中间件" # 跨记忆的混合（关键词 + 语义）搜索 ironmem search-global "身份验证中间件" # 跨所有项目的搜索 ironmem sessions # 当前项目的会话历史 ironmem inject # 手动重建 IRONMEM.md（按相关性排名） ironmem remember "..." # 存储显式记忆（--scope 用户，--kind 首选项，--tags） ironmem remember "..." --classification pii --consent-state granted --namespace tenant-a ironmem forget <memory-id> --reason "用户请求擦除" ironmem profile # 显示用户配置文件（--refresh 重新生成） ironmem corrections # 挖掘的错误→修复记忆列表（--all 适用于每个项目） ironmem graph "操作员操作系统" # 查询时间图边（--history 包括被取代的边，--at 过滤有效时间） ironmem graph-delete <edge-id> # 将坏图边标记为 user_deleted ironmem graph-update <edge-id> --source A --relation owns --target B # 人工策划图边 ironmem reconcile --dry-run # 预览重复/当前状态图协调 ironmem graph-backfill --limit 50 # 从较旧的记忆中提取图关系 ironmem feedback <memory-id> --signal used --weight 1 # 加强或衰减记忆 ironmem reflect --dry-run # 提出持久记忆巩固 ironmem code-relink --dry-run # Tree-sitter Rust AST 锚定/重新链接 ironmem snapshot create --label before-refactor # CCR 备份的项目脑快照 ironmem sync publish --node ci --op error_solution --payload '{"memory_id":1}' # 多代理事件日志 ironmem eval # 运行确定性记忆质量评估到 docs/evals ironmem compress <id> # 手动压缩会话 ironmem embed # 为现有记忆添加语义嵌入 ironmem gc # 回收未引用的 CCR 块（在擦除后） ironmem wipe # 删除当前项目的所有记忆 ironmem config # 打印当前设置 ``` <p align="center"> <img src="assets/demo-list.png" alt="ironmem list" width="600"/> </p> <p align="center"> <img src="assets/demo-search.png" alt="ironmem search" width="600"/> </p> --- ## 多提供商支持 IronMem 作为 **MCP 服务器**（原生集成）或通过 **IRONMEM.md**（纯 markdown，通用）： | 平台 | MCP 原生 | IRONMEM.md | 设置 | | -------- | :--------: | :--------: | ----- | | **Claude 代码** | **是** | 是 | [设置 →](#claude-code-mcp-setup) | | **Claude 桌面端** | **是** | 是 | [设置 →](#claude-desktop-mcp-setup) | | **claude.ai** | **是** | 是 | [设置 →](#claudeai-web) | | **Cursor** | **是** | 是 | [设置 →](#cursor--windsurf-mcp-setup) | | **Windsurf** | **是** | 是 | [设置 →](#cursor--windsurf-mcp-setup) | | **ChatGPT 桌面端** | **是** | — | [设置 →](#other-mcp-clients) | | **Zed** | **是** | — | [设置 →](#other-mcp-clients) | | **VS Code (Copilot/Continue/Cline)** | **是** | 是 | [设置 →](#other-mcp-clients) | | **任何 MCP 客户端** | **是** | — | stdio 或 SSE 传输 | | **任何 AI 工具** | — | 是 | 读取 `IRONMEM.md` 作为项目上下文 | --- ## MCP 设置 IronMem 支持两种 MCP 传输方式： - **stdio** — 适用于启动服务器本身的本地客户端（Claude 代码、Claude 桌面端、Cursor） - **可流式 HTTP** — 适用于通过 HTTP 连接的远程/云客户端。使用标准请求/响应和 bearer-token 认证，因此它适用于支持静态 bearer token 的客户端。 一旦通过 MCP 连接，客户端就可以记录会话、检索记忆、检查图状态、扫描自适应 skims 和扩展原始证据直接。 ### Claude 代码 MCP 设置 Claude 代码通过 **stdio** 连接 — 它直接启动 `ironmem mcp`。 **选项 A：CLI（推荐）** ```bash claude mcp add ironmem -- ~/.ironmem/bin/ironmem mcp ``` **选项 B：项目 `.mcp.json`** （与您的团队共享） 在项目根目录下创建 `.mcp.json`: ```json { "mcpServers": { "ironmem": { "command": "~/.ironmem/bin/ironmem", "args": ["mcp"], "env": { "ANTHROPIC_API_KEY": "您的密钥" } } } } ``` > **注意：** Claude 代码钩子（由 `install.sh` 安装）和 MCP 可以共存。钩子使用 REST API 进行自动观察记录；MCP 为您提供直接的工具访问。您可以同时使用两者或仅使用其中之一。 ### Claude 桌面端 MCP 设置 Claude 桌面端也通过 **stdio** 连接。 将以下内容添加到您的 `claude_desktop_config.json`: **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "ironmem": { "command": "/Users/YOU/.ironmem/bin/ironmem", "args": ["mcp"], "env": { "ANTHROPIC_API_KEY": "您的密钥" } } } } ``` 用您的实际主目录路径替换 `/Users/YOU`。保存后重启 Claude 桌面端。 ### claude.ai（网页） claude.ai 运行在云端，因此它 **无法** 访问 `localhost`。 IronMem 是一个本地优先的工具。完整的 MCP 访问的推荐设置是使用 **stdio** 的 **Claude 代码** 或 **Claude 桌面端**。 Anthropic 当前的 `claude.ai` 自定义连接器 UI 支持 **无认证** 和 **基于 OAuth** 的远程 MCP 服务器，但不支持手动静态 bearer-token 字段。对于个人使用，诚实的兼容性路径是 **无认证的临时隧道**: ```bash ironmem serve --public --no-auth ``` 该命令执行三个操作： 1. 启动 **无认证** 的 SSE 服务器 2. 启动一个 **Cloudflare Tunnel** （免费，无需帐户）以公开暴露它 3. 打印公共 URL ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ IronMem SSE 服务器 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 本地： http://127.0.0.1:37779/mcp 认证： 禁用（--no-auth） ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 公共 URL： https://xxx-yyy-zzz.trycloudflare.com 远程 MCP 设置： URL： https://xxx-yyy-zzz.trycloudflare.com/mcp 认证： 无 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` 在 claude.ai 中： 1. 打开 `设置` 2. 打开 `集成` 3. 选择 `添加自定义连接器` 4. 将 `名称` 设置为 `IronMem` 5. 将打印的 `https://...trycloudflare.com/mcp` URL 粘贴到 `远程 MCP 服务器 URL` 6. 留空 OAuth 字段 `trycloudflare.com` URL 是临时的，每次您重启公共隧道时都会更改，因此请在每次启动 `ironmem serve --public --no-auth` 时更新您的连接器 URL。 **没有 `--no-auth`**：`ironmem serve` 和 `ironmem serve --public` 为支持静态 bearer-token 的客户端使用 bearer-token 认证。 **要求：** 安装 [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) 以获得最佳结果（`brew install cloudflared` 在 macOS 上，`winget install Cloudflare.cloudflared` 在 Windows 上）。如果未安装，则回退到 `npx cloudflared`。 ### Cursor / Windsurf MCP 设置 两者都使用 stdio。添加至您的 MCP 设置： **Cursor:** 设置 → MCP → 添加服务器 **Windsurf:** 设置 → MCP → 添加服务器 ```json { "ironmem": { "command": "~/.ironmem/bin/ironmem", "args": ["mcp"] } } ``` ### 其他 MCP 客户端 任何支持 **stdio** 传输的 MCP 客户端都可以使用 IronMem： ```json { "command": "~/.ironmem/bin/ironmem", "args": ["mcp"] } ``` 对于支持 **可流式 HTTP** 的客户端，启动服务器并将客户端指向 `http://localhost:37779/mcp`: ```bash ironmem serve ``` ## MCP 工具 IronMem 目前公开了 **21 个 MCP 工具**: | 工具 | 用途 | | ---- | ------- | | `session_start` | 启动新的项目会话并返回 `session_id` | | `record_event` | 记录工具调用观察 | | `session_end` | 结束会话并触发压缩 | | `compress_session` | 手动压缩会话 | | `get_context` | 检索项目记忆；结果包括具有 `chunk_id` 句柄的扩展块 | | `memory_skim` | 返回项目或全局压缩的skim块，用于广泛的工作记忆扫描 | | `retrieve_original` | 通过 `chunk_id`、`observation_id`、`memory_id` 或 blob `hash` 展开确切的原始文本 | | `get_status` | 返回数据库统计信息、CCR 统计信息、图边计数和记忆块计数 | | `list_memories` | 列出项目的最近记忆 | | `search_memories` | 项目内混合搜索 | | `search_global` | 跨每个项目的混合搜索 | | `list_projects` | 列出具有存储记忆的已知项目 | | `list_sessions` | 列出项目的会话历史 | | `inject_context` | 将 `IRONMEM.md` 写入项目根目录 | | `remember` | 存储显式类型/作用域记忆 | | `get_profile` | 返回当前跨项目用户配置文件 | | `refresh_profile` | 重新生成用户配置文件 | | `list_corrections` | 列出挖掘的 `error_solution` 记忆 | | `memory_graph` | 查询实体的时间图边，具有可选的有效时间过滤 | | `reconcile_memory_graph` | 干燥运行或应用重复/当前状态图协调 | | `wipe_project` | 删除一个项目的全部记忆 | 预期的代理循环是： 1. 调用 `get_context` 进行聚焦回忆或 `memory_skim` 进行更广泛的扫描。 2. 检查返回的 `chunk_id` 值。 3. 调用 `retrieve_original` 并选择 `chunk_id` 以获取确切证据。 ### Neovim 插件 IronMem 包括一个原生 Neovim 插件，通过 MCP stdio 通信。 **使用 lazy.nvim 安装：** ```lua { "BMC-INC/Iron-mem", config = function() require("ironmem").setup({ -- binary = "~/.ironmem/bin/ironmem", -- 默认 -- auto_start = true, -- 在 VimEnter 上启动 session_start -- auto_end = true, -- 在 VimLeavePre 上结束 session_end -- record_events = true, -- 记录缓冲区写入 }) end, } ``` **命令：** | 命令 | 描述 | |---------|-------------| | `:IronMemStart` | 手动启动会话 | | `:IronMemEnd` | 结束会话并压缩 | | `:IronMemStatus` | 显示数据库统计信息 | | `:IronMemSearch <query>` | 在分割缓冲区中搜索记忆 | --- ## 网页 UI 当 REST 服务器运行时，内置的记忆浏览器可在以下网址访问： ``` http://localhost:37778/ui ``` UI 显示会话、记忆和数据库统计信息。您可以直接在浏览器中浏览、搜索和删除记忆。 ### REST API REST 服务器默认在 `http://localhost:37778` 运行。当前高信号端点： | 端点 | 用途 | | -------- | ------- | | `POST /session/start` | 启动会话 | | `POST /event` | 记录观察 | | `POST /session/end` | 结束并压缩会话 | | `POST /compress` | 手动压缩会话 | | `GET /context?project=&query=&namespace=&limit=&rerank=` | 检索项目记忆以及一个治理命名空间中的扩展块 | | `GET /skim?project=&namespace=&limit=` | 返回一个治理命名空间中的自适应项目skim块 | | `GET /skim?global=true&namespace=&limit=` | 返回一个治理命名空间中的自适应全局skim块 | | `POST /retrieve_original` | 通过 `chunk_id`、`observation_id`、`memory_id` 或 `hash` 展开 | | `POST /remember` | 存储显式类型/作用域记忆 | | `GET /profile` / `POST /refresh_profile` | 读取或重新生成用户配置文件 | | `GET /corrections` | 列出挖掘的错误解决方案记忆 | | `GET /graph?entity=&project=&history=&at=&limit=` | 查询时间图边 | | `GET /status` | 健康、数据库统计信息、CCR 统计信息、图边计数和记忆块计数 | --- ## 受管记忆 IronMem 仍然独立于 SovereignClaw，但它现在有自己的耐用回忆治理信封。默认命名空间是 `local`，因此现有的单用户安装继续有效，无需新标志。多租户或控制平面调用者可以设置 `namespace` 以隔离读取、搜索、skim、列表、上下文注入和显式记忆写入。 CLI、REST `/remember` 和 MCP `remember` 接受的治理字段包括： | 字段 | 用途 | | ----- | ------- | | `namespace` | 租户/领域边界。默认为 `local`。 | | `source_type` | `user_input`、`tool_output`、`agent_generated`、`derived`、`external` 或 `sync_peer`。 | | `trust_tier` | `high`、`medium`、`low` 或 `untrusted`。 | | `writer_identity` / `source_ref` | 记忆的来源/写入者。 | | `parent_memory_id` | 导出的事实和压缩子节点的血统。 | | `classification` | `public`、`internal`、`confidential`、`restricted`、`pii` 或 `phi`。 | | `consent_state` | `required`、`granted`、`denied` 或 `withdrawn`；`pii` 和 `phi` 需要 `granted`。 | | `residency`、`retention_policy_id`、`expires_at` | 策略元数据；`expires_at` 由主动回忆过滤器强制执行。 | | `legal_hold` | 防止受管删除同时为真。 | 示例： ```bash ironmem remember "客户要求保留审计导出 7 年" \ --namespace tenant-a \ --classification confidential \ --consent-state granted \ --writer ops-agent \ --residency us \ --retention-policy-id audit-7y ironmem search "审计导出" --namespace tenant-a ironmem forget 42 --actor privacy-admin --reason "保留窗口过期" ``` --- ## 配置 `~/.ironmem/settings.json`: ```json { "port": 37778, "provider": "anthropic", "model": "claude-sonnet-4-6", "inject_limit": 5, "max_observation_bytes": 2048, "db_path": "/Users/you/.ironmem/mem.db", "database_url": null, "mcp_transport": "stdio", "mcp_sse_port": 37779, "auth_token": null, "embedding": { "provider": "auto", "model": null, "ollama_url": "http://localhost:11434", "weights": { "relevance": 0.5, "recency": 0.3, "importance": 0.2, "kind_boosts": {} }, "recency_half_life_days": 30 }, "rerank": { "enabled": false, "model": "", "pool": 20 } } ``` 所有字段都是可选的。提供合理的默认值。 `auth_token` 在首次运行 `ironmem serve` 且 `--no-auth` 时自动生成。 `embedding` 块是可选的 - 完全省略它，IronMem的行为与以前完全相同（仅关键词搜索，回忆注入）。 `rerank` 0 } ``` 所有字段都是可选的。提供了合理的默认值。`auth_token` 在没有 `--no-auth` 的情况下首次运行 `ironmem serve` 时自动生成。`embedding` 块是可选的 - 如果没有，则 IronMem 的行为与以前完全相同（仅关键词搜索，回忆注入）。`rerank` 块默认关闭，因为它对每个重新排序的查询都会调用一个LLM。 # IronMem 的 "auto" 提供程序将自动检测并使用它。 ## 内置 ONNX（无 Ollama，无网络）： 编译时添加可选功能，以便嵌入式运行完全在进程内： ```bash cargo install --path . --features local-onnx ``` ## 混合权重 （`embedding.weights`）控制会话启动注入排名：`relevance`（与当前 git 上下文的语义匹配），`recency`（由 `recency_half_life_days` 设置的真实半衰期衰减），和 `importance`（LLM 分配的 1-10 分数每记忆）。它们不必合计为 1。 ## 重排序 （`rerank.enabled`）是可选的，默认情况下禁用。当启用时，IronMem 拉取更广泛的候选池，请求配置的 LLM 对紧凑的片段进行重排序，然后重新锚定结果，以便不会丢失强大的基本时间答案。每个请求的 REST 调用者可以使用 `?rerank=true` 或 `?rerank=false` 进行覆盖。 ## 回填现有记忆 — 在启用嵌入后，索引之前创建的记忆： ```bash ironmem embed # 嵌入缺少向量（所有项目）的记忆 ironmem embed --project . # 限定为一个项目 ironmem embed --force # 从头开始重建索引 ``` ### 提供程序 IronMem 支持三种 LLM 提供程序用于会话压缩： | 提供程序 | `provider` 值 | 默认模型 | API 密钥环境变量 | |----------|-----------------|---------------|-----------------| | **Anthropic** | `"anthropic"` | `claude-sonnet-4-6` | `ANTHROPIC_API_KEY` | | **OpenAI** | `"openai"` | `gpt-4o` | `OPENAI_API_KEY` | | **Google Gemini** | `"google"` | `gemini-2.0-flash` | `GOOGLE_API_KEY` | 要切换提供程序，请在 `~/.ironmem/settings.json` 中设置 `"provider"`，并确保设置了相应的 API 密钥。`model` 字段覆盖提供程序的默认模型。 ### 环境变量 | 变量 | 默认值 | 描述 | |:---------|:--------|:------------| | `DATABASE_URL` | _(无)_ | Postgres URL。当设置时，覆盖 `db_path`。 | | `IRONMEM_MCP_TRANSPORT` | `stdio` | MCP 传输：`stdio` 或 `sse` | | `ANTHROPIC_API_KEY` | _(无)_ | 当提供程序为 `anthropic`（默认）时需要 | | `OPENAI_API_KEY` | _(无)_ | 当提供程序为 `openai` 时需要 | | `GOOGLE_API_KEY` | _(无)_ | 当提供程序为 `google` 时需要 | ### API 密钥 IronMem 需要一个 LLM API 密钥来压缩会话观察为记忆。 **推荐（Anthropic）：** 将密钥写入 `~/.ironmem/api_key`（`echo "your-key" > ~/.ironmem/api_key && chmod 600 ~/.ironmem/api_key`）。将其保存在此文件中，而不是全局 `ANTHROPIC_API_KEY` 导出，避免更改其他工具的计费方式 — 例如，Claude Code 按照付费方式使用 API 积分，而不是使用您的订阅。IronMem 会自动读取文件（当后台服务器通过 `nohup` 启动时，它也有效，其中一些 shell 会从子进程中剥离环境变量）。 IronMem 仍然会遵循每个提供程序的环境变量（如果您更喜欢的话）- `ANTHROPIC_API_KEY`、`OPENAI_API_KEY` 或 `GOOGLE_API_KEY`。文件备用适用于默认的 Anthropic 提供程序。 --- ## 测试状态 当前 README 状态的本地验证： ```bash CARGO_TARGET_DIR=/tmp/ironmem-codex-target cargo test --bin ironmem -- --nocapture CARGO_TARGET_DIR=/tmp/ironmem-codex-target cargo clippy --bin ironmem -- -D warnings ``` 结果： - **157 个测试通过** - **1 个基准测试故意忽略** (`bench_ccr_dict_vs_floor`) - **0 个失败** - **Clippy 干净，带有 `-D warnings`** 覆盖范围包括 CCR 往返和损坏检查、UTF-8 安全截断、类型/作用域记忆、用户配置文件再生、纠正挖掘、语义检索、时间查找路由、图协调、块快速/展开流程、MCP 身份验证/工具、REST 面向行为通过共享处理程序、向量回填/清除、提供程序解析和端到端语义管道。 --- ## 故障排除 **服务器未启动：** ```bash ironmem status # 检查服务器是否响应 cat ~/.ironmem/server.log # 检查服务器日志 ~/.ironmem/bin/ironmem server # 手动运行以查看错误 ``` **观察结果未被记录：** ```bash ironmem status # 检查观察结果数量 sqlite3 ~/.ironmem/mem.db "SELECT count(*) FROM observations;" ``` 如果计数保持为 0，您的钩子可能未安装。重新运行 `./install.sh` 或检查 `~/.claude/hooks/post-tool-use.sh` 是否存在且可执行。 **压缩失败（记忆始终为 0）：** ```bash # 检查 API 密钥是否可访问（密钥文件是推荐的来源） cat ~/.ironmem/api_key # 应该包含您的密钥 echo $ANTHROPIC_API_KEY # 可选环境变量备用（可能为空） # 尝试手动压缩 ironmem compress <session-id> # 从 server.log 获取会话 ID ``` **钩子未触发：** 检查 `~/.claude/settings.json` 是否在 `"hooks"` 键下注册了钩子。重新运行 `./install.sh` 将修复此问题。 --- ## 架构 ```text ~/.ironmem/ ├── bin/ironmem # 单个编译二进制文件 ├── mem.db # SQLite 数据库：FTS 记忆、元数据、向量、图边、块、CCR 块 ├── settings.json # 配置 ├── api_key # Anthropic API 密钥（chmod 600；使其远离 shell 环境） ├── current_session # 活动会话 ID（短暂） └── server.log # 工作器日志 ~/.claude/hooks/ # 自动安装的 Claude Code 钩子 ├── session-start.sh # 会话启动时注入记忆 ├── post-tool-use.sh # 记录每个工具调用 ├── stop.sh # 触发压缩 └── session-end.sh # 清理 ``` **约 14,000 行 Rust 代码。** MCP 原生。SQLite 或 Postgres。无损、可逆记忆。时间图。自适应块快速/展开。单个二进制文件。无外部运行时。 --- ## 为什么选择 Rust？ 选择 Rust 来实现 IronMem，以提供： - **最大性能：** 最小的开销和闪电般快速的执行，对于一个钩入每个 CLI 命令的工具至关重要。 - **零依赖：** 编译为单个二进制文件。无需安装 Python、Node.js 或复杂的运行时环境。 - **内存安全性和可靠性：** 保证安全，无需垃圾回收，确保后台工作器保持稳固且无泄漏。 --- ## 设计原则 - **零摩擦** — 钩子静默运行，绝不中断您的工作流程 - **本地优先** — 默认在您的机器上运行，您的数据仍然属于您 - **MCP 原生** — 采用每种主要 AI 客户端正在采用的协议 - **提供程序无关** — MCP 用于原生集成，纯 Markdown 用于其他所有情况 - **可自我托管** — Docker + Postgres 用于团队部署，仍然零云依赖 - **故障安全** — 如果 IronMem 崩溃，您的编码会话不受影响 --- ## 适用人群 IronMem 适用于大量使用 AI 编码工具并希望在会话之间保持连续性的开发人员。 它特别适用于以下情况： - 在 Claude Code、Cursor、Copilot 或 Windsurf 之间切换 - 处理跨多个会话的项目 - 厌倦重新解释架构、错误和最近的更改 - 希望本地优先的记忆，而不是托管服务 ## 不适用人群 IronMem 并不试图成为： - 适用于每种代理的通用记忆平台 - 云同步产品 - 团队知识库 - 带有大量仪表板的流程工具 它很好地解决了狭窄的问题：AI 编码工作流的会话记忆。 --- ## 为什么不直接使用 CLAUDE.md？ `CLAUDE.md` 适用于静态项目上下文 — 类似“使用 tab 而不是空格”或“我们使用 Axum 进行路由”的内容。但它是手动的。您编写它，维护它，并且它不知道上一会话发生了什么。 IronMem 是 **自动且会话感知的：** | | CLAUDE.md | IronMem | | - | --------- | ------- | | **更新** | 您手动编写 | 从会话活动自动生成 | | **范围** | 静态项目规则 | 动态会话历史 | | **轮换** | 您管理它 | 旧记忆自动老化 | | **搜索** | Ctrl+F | 跨所有会话的全文本搜索 | | **努力** | 高 | 零 — 钩子处理一切 | 它们一起工作。`CLAUDE.md` 包含您的项目规则。IronMem 包含发生了什么。 --- ## Docker 部署 使用 Postgres 运行 IronMem 以进行团队/远程设置： ```bash ANTHROPIC_API_KEY=your-key docker-compose up --build ``` 这启动 IronMem，带有 Streamable HTTP，位于 `http://localhost:37779/mcp` 和 Postgres 16，以及 REST 服务器，位于 `http://localhost:37778`。 --- ## 路线图 ### 已在 v0.2.0 中发布 - [x] MCP 原生服务器（stdio + Streamable HTTP） - [x] 双数据库 — SQLite（本地，FTS5）+ Postgres（自我托管） - [x] 带有 Postgres 的 Docker 部署 - [x] 持有者令牌身份验证 - [x] `ironmem serve --public`，带有 Cloudflare Tunnel，用于远程 MCP 客户端 - [x] `ironmem serve --public --no-auth`，用于 claude.ai 个人使用 - [x] 与 Claude Code、Claude Desktop、Cursor、Windsurf、ChatGPT Desktop、Zed、VS Code 配合使用 ### 已在 v0.3.0 中发布 - [x] 多提供商压缩 — OpenAI、Google Gemini 或 Anthropic（通过设置中的 `provider` 配置） - [x] Neovim 插件（`nvim/lua/ironmem/`）— 自动会话生命周期、`:IronMemSearch`、`:IronMemStatus` - [x] Windows 原生支持 — `install.ps1`、平台感知安装消息、强大的主目录检测 - [x] Web UI 记忆浏览器 — `http://localhost:37778/ui`，当 REST 服务器运行时 ### 已在 v0.4.0 中发布 - [x] **语义基础** — 混合 FTS + 向量 + 时间图（RRF）检索、本地优先嵌入和相关性排名的会话启动注入 - [x] **可靠性和安全性强化** — stdio MCP 流不会被日志输出损坏，UTF-8 安全截断防止多字节工具输出崩溃，修复了 7 个依赖顾问 - [x] **CCR — 无损可逆记忆** （Headroom 模式）：内容寻址、重复数据删除的 blob 存储 + 字节精确的每种内容类型的压缩（zstd + 每种类型字典）+ `retrieve_original` 工具，以便始终可以恢复任何压缩记忆的原始内容 — 无损截断。引用计数 GC（`ironmem gc`）+ `get_status` 中的存储统计信息。 [设计 »](docs/superpowers/plans/2026-06-07-ironmem-ccr-supermemory.md) - [x] **记忆范围和类型** （Supermemory 模式）：项目与用户（跨项目）范围、类型记忆（`error_solution` / `preference` / `procedural` / `architecture` / `learned_pattern` / …），范围感知注入，具有每种类型提升，并且具有 `remember` 工具 - [x] **双输出压缩** — 每个压缩会话都可以保留一个叙事记忆和一个单独的 `kind=fact` 记忆；事实在可用时继承事件时间元数据，并为直接检索建立索引。 - [x] **始终注入的用户配置文件** — 跨项目事实提炼成一个配置文件记忆（LLM 摘要或确定性本地汇总）；`get_profile` / `refresh_profile` - [x] **纠正矿工** — 错误→修复循环成为 `error_solution` 记忆，通过 `list_corrections` 显示 - [x] **时间图精简版** — 压缩现在提取具有日期、置信度、记忆出处和调和的结构化 `source | relation | target` 边。完全相同的重复项和已取代的当前状态边在历史中被标记，而不是删除。查询使用 `ironmem graph`、REST `/graph` 或 MCP `memory_graph`；活动边也作为关系排名的检索信号馈送到混合搜索中。 - [x] **图操作** — `ironmem reconcile` / MCP `reconcile_memory_graph` 修复遗留重复/当前状态边，具有干燥运行计数，并且 `ironmem graph-backfill` 为旧记忆提取图关系，而不改变摘要。 - [x] **时间和程序回忆** — 图查询支持有效时间过滤器（`--at`、`at_time`、REST `at`），压缩验证日期，可重用工作流规则被提取/存储为 `kind=procedural`，并且时间查找查询路由到具有日期的事实而不是图上的关系命中。 - [x] **自适应工作记忆快速浏览** — `memory_chunks` 存储具有密度、种类、标题、令牌估计、源偏移和 `chunk_id` 展开句柄的模型无关压缩块图。使用 MCP `memory_skim`、REST `/skim` 或 `get_context` 展开，然后使用 `retrieve_original` 展开确切的证据。 - [x] **操作 OS 适配器 + 评估框架** — `docs/operator-os-memory-adapter.md` 定义租户/工作器/工作项记忆映射，并且 `ironmem eval` 编写具有命令、模型和提交元数据的可重复图/时间/程序评估报告。 - [x] **闭环质量 + 整理** — 使用情况反馈和注入事件调整排名；Web UI 可以检查图边并将幻觉链接标记为用户删除。 - [x] **AST 绑定记忆 + 反射 + 时间旅行 + 同步** — Tree-sitter Rust 代码锚点、干燥运行/应用反射提案、CCR 支持的快照和一个恒等同步事件日志已实现。 - [x] **当前验证** — 160 个 Rust 测试通过，1 个基准测试故意被忽略，独立 MCP stdio 清洁度通过，Clippy 在 `-D warnings` 下清洁。 ### 下一步 - [ ] **定制每种内容类型的转换** — 在字典编码器之上实现可逆日志时间戳增量/差异令牌/AST 感知代码规范（目前是文档化的未来；字节精确合同是门槛） - [ ] **观察 blob 生命周期 GC** — 回收已删除观察后面的 CCR 块（内存会话块已经是 GC'd） --- ## 贡献 欢迎贡献。请在打开 PR 之前阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。 **TL;DR:** 首先打开一个问题。错误修复和提供者兼容性改进始终受欢迎。我们不接受增加运行时依赖或复杂性的更改。 --- ## ⭐ 支持 如果您觉得 IronMem 有用，请考虑给它一个星星！ 🌟 这有助于其他人发现该项目，并激励进一步开发。 也欢迎贡献、问题和功能请求。 --- ## 许可证 Apache-2.0 © 2026 ExecLayer Inc **维护者：** [James Benton](https://github.com/BMC-INC)