Rememb

运行 AI Agent，不再丢失会话间的上下文。rememb 是本地优先的长期记忆工具：支持结构化条目、关键词搜索、版本管理、差异比较、恢复和审计追踪——无需云服务或 API 密钥。

问题

以真实速度使用 Agent 的团队，失败的原因很少是生成能力不足。他们失败是因为每天运行 Agent 会造成上下文债务：

• 每个会话都要反复解释太多项目事实
• 聊天窗口之外的持久记忆太少
• 无法充分追踪某项变更的原因
• 回忆正确上下文时噪声太多

每个以专业方式运行 Agent 的团队或独立开发者都会遇到这个瓶颈：

Session 1: "We're using PostgreSQL, auth at src/auth/, prefer async patterns."
Session 2: Agent starts from zero. You explain everything again.
Session 3: Same thing.

现有解决方案往往依赖托管记忆层、API 密钥或不透明的上下文管道。 你真正需要的是用最少且正确的上下文恢复下一次会话，并保留可供检查的记录。

rememb 围绕四类记忆问题构建：

• 持久保存事实和决策，而不是仅保留会话聊天记忆
• 使用关键词搜索，而不是重读所有内容（由 Agent 判断相关性）
• 使用非破坏性版本管理，而不是静默覆盖
• 为 AI 工作提供本地优先的审计追踪，而不是不透明的云端日志

---

安装

pip install rememb

---

快速开始

使用 MCP（推荐）

1. 安装入口，或手动添加 MCP 配置块：

rememb install --apply --project

如果宿主支持（目前为 Cursor 和 Claude），此操作会写入 MCP 服务、Memory Rules 以及 SessionStart / PostToolUse / Stop hooks。不带 --apply 时只会打印计划。--host 用于限制目标；省略它则会写入 rememb install 支持的所有宿主（cursor、claude、codex、vscode、copilot、windsurf、continue、gemini、opencode、zed、cline）。

或者将以下内容添加到 IDE 的 MCP 配置中，并粘贴 MCP_TOOLS.md 中的规则：

{
  "mcpServers": {
    "rememb": {
      "command": "rememb",
      "args": ["mcp"]
    }
  }
}

添加可重复的 --project /path/to/repo 参数，为每个项目设置存储位置，并与全局 ~/.rememb 并存。详情见：MCP_TOOLS.md。

2. 重启 IDE。

SessionStart 会注入最近的条目、标签和简短的统计信息块。当有内容发生变化时，Agent 会写入持久记忆；只有在需要定向回忆时才会搜索。

无需额外设置存储。在 MCP 模式下，rememb 会在首次使用时自动初始化 ~/.rememb 和可选的 --project 存储。公开工具：MCP_TOOLS.md（18 个工具）。

如果你希望同一台机器上的多个 MCP 客户端复用一个已运行的 rememb 进程，请启动持久的本地 SSE 传输：

rememb mcp --transport sse --host 127.0.0.1 --port 8765

这样可以让一个 MCP 进程持续运行，使多个客户端可以通过 http://127.0.0.1:8765/sse 和 http://127.0.0.1:8765/messages/ 连接。

不要在 stdio MCP 客户端配置中加入 --transport sse。stdio 客户端需要通过 stdin/stdout 使用 JSON-RPC；SSE 模式会公开一个 HTTP 端点，必须单独启动。

不使用 MCP 的本地用法

rememb                    # Open the web UI (http://localhost:18181)
rememb --port 9000        # Custom port

---

工作原理

~/.rememb/                 ← default store location (MCP and Web UI)
  entries.json             ← default JSON backend (or entries.db with SQLite)
  meta.json                ← project metadata
  config.json              ← limits, sections, storage backend, UI paging

磁盘上的本地存储。你的 Agent 可以读取之前的决策、按关键词和词元搜索、更新条目而不丢失历史记录，并恢复到之前的版本，无需依赖云端记忆服务。将 ~/.rememb/ 复制到任意位置即可迁移存储。

User: "We're using PostgreSQL, auth at src/auth/, async patterns"
Agent: [rememb_write] → Saved

[New session]
SessionStart injects recent + tags + stats (handoff first)
Agent: "I see you're using PostgreSQL with auth at src/auth/..."

写入、编辑和删除操作通过 rememb_write、rememb_edit 和 rememb_delete 完成。主机钩子也会通过 rememb hook post-tool / stop 写入 actions。完整的 MCP 接口请参阅 MCP_TOOLS.md。

搜索会对条目内容和标签进行关键词与词元匹配。rememb_search 会返回 id、分数、标签、日期和简短摘录（search_excerpt_chars，默认值为 160）。完整正文可通过 Agent 选定的 id 调用 rememb_get / rememb_read 获取，也可在搜索时设置 max_chars=0。相关性判断由 Agent 根据语义完成。无需 API 密钥、云服务或运行时下载嵌入模型。

初始化时会写入包含所有受支持配置项的 config.json：

{
  "max_content_length": 1000000,
  "max_tag_length": 500,
  "max_tags_per_entry": 100,
  "max_entries": 100000,
  "sections": ["project", "actions", "systems", "requests", "user", "context"],
  "section_colors": {
    "project": "#d84848",
    "actions": "#d08020",
    "systems": "#d4c430",
    "requests": "#40c040",
    "user": "#20d4c4",
    "context": "#c060f0"
  },
  "entry_batch_size": 24,
  "entry_load_threshold": 6,
  "search_excerpt_chars": 160,
  "storage_backend": "json"
}

对于较大的存储，请将 storage_backend 设置为 sqlite。切换存储后端时，Web UI 和 MCP 会自动迁移现有的 JSON 条目。

entry_batch_size 和 entry_load_threshold 控制 Web UI 中的分页行为——每次加载多少张卡片，以及何时触发“加载更多”。

分区名称会规范化为小写，规范化后重复的名称会被忽略；如果移除的分区中已有条目，这些条目会自动迁移到 uncategorized。meta.json 会与当前有效的分区列表保持同步。

较旧的存储中可能仍包含与嵌入相关的旧版配置项；下次加载或保存配置时，这些配置项会被移除。

---

记忆分区

分区	存储内容
project	技术栈、架构、目标
actions	已完成的事项、做出的决策
systems	服务、模块、集成
requests	用户偏好、重复请求
user	姓名、风格、专业知识、偏好
context	其他相关内容

---

Web UI

rememb 提供本地 Web 界面，用于监督——浏览记忆、检查历史记录并调整运行时设置。该 SPA 不提供创建、编辑或删除控件。HTTP API 仍提供写入、删除和恢复路由。

rememb                       # Open the web UI (http://localhost:18181)
rememb --host 0.0.0.0        # Bind to all interfaces
rememb --port 9000           # Custom port
rememb --no-browser          # Start server without opening the browser

概览页面显示条目总数和近期记忆活动。

统计页面显示总数、分区细分、日期范围和近期条目。

设置页面用于调整限制、存储后端、分区颜色和维护操作。

技能浏览器，用于浏览 rememb 附带的 Agent 技能。

视图：

• 概览 — 条目总数、已删除条目数、存储大小和近期记忆
• 记忆 — 浏览、按关键词搜索、按分区筛选、排序以及包含已删除条目
• 统计 — 总数、后端、分区条形图、最早/最新时间戳和近期条目
• 设置 — 编辑限制、存储后端和分区颜色，合并重复项并保存运行时配置
• 技能 — 浏览随包附带的 Agent 技能（包中包含 61 项技能）

通过 UI 检查条目时，可以查看版本历史记录和并排差异。条目变更和恢复需通过 MCP（rememb_write、rememb_edit、rememb_delete、rememb_restore）或 HTTP API 完成，而非通过 SPA 控件操作。

---

CLI

rememb                                                      # Open the web UI (http://localhost:18181)
rememb --host 0.0.0.0 --port 18181 --no-browser            # Custom bind, no auto-open
rememb mcp                                                  # Start MCP server over stdio
rememb mcp --transport sse --host 127.0.0.1 --port 8765    # One persistent local MCP process
rememb hook session-start                                   # Inject recent + tags + stats
rememb hook post-tool                                       # Write a PostToolUse event from stdin
rememb hook stop                                            # Write a Stop/handoff entry from stdin
rememb install                                              # Show MCP + rules + hooks plan
rememb install --apply --project                            # Write them for the current directory
rememb --version, -v                                        # Show version
rememb --help, -h                                           # Show help

---

兼容性

当前兼容性范围在 COMPATIBILITY.md 中有明确记录。

简而言之：

• CI 覆盖 Python 3.11 至 3.14
• CLI 合约和 MCP 工具架构（18 个工具）均有自动化测试覆盖
• stdio MCP 是主要文档化集成路径
• SSE MCP 已记录文档，并在路由层面进行了部分测试
• 发布自动化和 Trusted Publishing 已记录在 RELEASE.md 中

---

设计

• 本地优先 — 使用磁盘上的纯 JSON 或 SQLite
• 可移植 — 将 ~/.rememb/ 复制到任何位置即可使用
• 不限于特定平台 — 适用于任何 Agent、任何 IDE（MCP 或 CLI）
• 无锁定 — 无需服务、API 密钥或账户

核心功能：

• 包含分区和标签的结构化记忆
• 关键词搜索，由 Agent 端判断相关性（rememb_search 是一个索引：id、score、excerpt；完整正文通过 get/read 获取）
• 主机入口：SessionStart 注入近期内容、标签和统计数据；PostToolUse / Stop 将内容写入 actions；Stop 添加 handoff 标签，确保下一个主机优先看到
• rememb install 会写入 MCP、Memory Rules 和钩子（适用于 Cursor 和 Claude 的钩子）
• 非破坏性版本管理、差异比较、恢复和软删除
• 重复内容合并（精确匹配）和存储统计
• 通过 Web UI 管理配置和维护（设置和合并；通过 MCP 或 HTTP API 修改条目）
• 通过 Web UI 和 MCP 提供 61 个内置 Agent 技能

---

贡献

git clone https://github.com/LuizEduPP/Rememb
cd Rememb
pip install -e ".[dev]"

欢迎提交 PR、提出问题、点亮 Star。🌟

---

许可证

MIT