Roampal — 基于结果的持久化记忆 MCP 服务器

为什么选择它？

AI 编码助手在不同会话之间会遗忘一切。你不得不反复解释你的架构、偏好和规范。当它们给出糟糕的建议时，也没有机制让它们从中学习。

Roampal 是一个 MCP 服务器，它为你的 AI 提供跨会话的持久化、基于结果的记忆。好的建议会被提升，坏的建议会被降级。你的 AI 会自动学习什么有效、什么无效，无需改变任何工作流。

基准测试

在 LoCoMo 上达到 85.8%（非对抗性，端到端答案准确率）——通过 10 次对话中的 1,986 个问题进行双重评分验证。

结果	分数
对话式学习 vs 原始摄入	+23 分 (76.6% vs 53.0%, p<0.0001)
架构 vs 模型影响	架构贡献度 ~10 倍
抗毒性（1,135 条对抗性记忆）	仅 -2.6 到 -4.2 分
TagCascade 检索（标签优先 + CE 重排序）	+1.9 Hit@1 vs 纯 CE (p<0.0001)

基准测试流水线在单 GPU 上运行，无云依赖。Roampal 本身在 CPU 上运行，无需 GPU。完整方法论、数据和评估脚本：roampal-labs

论文：“Beyond Ingestion: What Conversational Memory Learning Reveals on a Corrected LoCoMo Benchmark” (Logan Teague, 2026 年 4 月)

快速开始

pip install roampal
roampal init

自动检测已安装的工具。重启编辑器并开始聊天。

指定特定工具：roampal init --claude-code 或 roampal init --opencode

核心循环是相同的——两个平台都会注入上下文、捕获交互并对结果进行评分。交付机制有所不同：

	Claude Code	OpenCode
上下文注入	钩子 (stdout)	插件 (系统提示词)
交互捕获	停止钩子	插件 `session.idle` 事件
评分	主 LLM 通过 `score_memories` 工具	独立侧边栏（你选择的模型 > Zen 免费版）
自愈	钩子在失败时自动重启服务器	插件在失败时自动重启服务器

Claude Code 提示主 LLM 通过 score_memories 工具对每次交互进行评分。OpenCode 从不进行自评分——一个独立的侧边栏（单独的 API 调用）作为第三方审查每次交互，消除了自评估偏差。score_memories 工具未在 OpenCode 中注册。在 roampal init 或 roampal sidecar setup 期间，Roampal 会检测本地模型（Ollama、LM Studio 等）并让你选择评分模型。如果已配置，这些模型将优先使用（为隐私起见，跳过 Zen）。廉价或本地模型效果很好——评分不需要强大的模型。如果你跳过设置，默认使用 Zen 免费模型（远程，尽力而为）。

工作原理

当你输入消息时，Roampal 会在 AI 看到它之前自动注入相关上下文：

你输入：

fix the auth bug

你的 AI 看到：

═══ KNOWN CONTEXT ═══
• JWT refresh pattern fixed auth loop [id:patterns_a1b2] (3d, 90% proven, patterns)
• User prefers: never stage git changes [id:mb_c3d4] (memory_bank)
═══ END CONTEXT ═══

fix the auth bug

无需手动调用。无需改变工作流。它就是这么好用。

循环机制

你输入一条消息
Roampal 自动注入相关上下文（Claude Code 中的钩子，OpenCode 中的插件）
AI 响应，充分了解你的历史、偏好和之前有效的方法
结果评分——好的建议被提升，坏的建议被降级
重复——系统在每次交互中变得更聪明

五个记忆集合

集合	用途	生命周期
`working`	当前会话上下文	24 小时 — 如果有用则提升，否则删除
`history`	过去对话	30 天，基于结果评分
`patterns`	已验证的解决方案	在有用时持久存在，从历史记录中提升
`memory_bank`	身份、偏好、目标	永久
`books`	上传的参考文档	永久

命令

roampal init                # Auto-detect and configure installed tools
roampal init --claude-code  # Configure Claude Code explicitly
roampal init --opencode     # Configure OpenCode explicitly
roampal init --no-input     # Non-interactive setup (CI/scripts)
roampal start               # Start the HTTP server manually
roampal stop                # Stop the HTTP server
roampal status              # Check if server is running
roampal status --json       # Machine-readable status (for scripting)
roampal stats               # View memory statistics
roampal stats --json        # Machine-readable statistics (for scripting)
roampal doctor              # Diagnose installation issues
roampal summarize           # Summarize long memories (retroactive cleanup)
roampal score               # Score the last exchange (manual/testing)
roampal context             # Output recent exchange context
roampal ingest <file>       # Add documents to books collection
roampal books               # List all ingested books
roampal remove <title>      # Remove a book by title
roampal sidecar status      # Check scoring model configuration (OpenCode)
roampal sidecar setup       # Configure scoring model (OpenCode)
roampal sidecar test        # Test scoring model response format (OpenCode)
roampal retag               # Re-extract tags on memories using sidecar LLM
roampal sidecar disable     # Remove scoring model configuration (OpenCode)

MCP 工具

你的 AI 将获得这些记忆工具：

工具	描述	平台
`search_memory`	跨所有集合进行深度搜索	两者
`add_to_memory_bank`	存储永久事实（身份、偏好、目标）	两者
`update_memory`	更正或更新现有记忆	两者
`delete_memory`	删除过时信息	两者
`score_memories`	对之前的交互结果进行评分	Claude Code
`record_response`	存储重要交互的关键要点	两者

评分如何工作： Claude Code 的钩子提示主 LLM 在每轮调用 score_memories。OpenCode 使用一个独立的侧边栏在后台静默评分——模型永远不会看到评分提示，且 score_memories 不会作为工具注册。如果侧边栏不可用，系统会提示用户运行 roampal sidecar setup。在 roampal init 期间或通过 roampal sidecar setup 选择你的评分模型。

Roampal 的对比优势

特性	Roampal Core	Claude Code 内置 (CLAUDE.md / 自动记忆)	OpenCode 内置
从结果中学习	是 — 坏建议降级，好建议提升	否	否
语义检索	是 — TagCascade + 交叉编码器重排序	否 — 文件全量加载，无搜索	无记忆系统
上下文注入	自动 — 每个查询的相关记忆	每次会话全量 CLAUDE.md，按需自动记忆	无
原子事实提取	是 — 摘要 + 事实，双通道检索	否 — 保存 Claude 认为有用的内容	无记忆
跨项目工作	是 — 所有项目共享记忆	仅限每个项目（每个 git 仓库）	无记忆
随历史扩展	是 — 5 个集合，提升/降级/衰减	CLAUDE.md 无限制，自动记忆前 200 行	无记忆
完全本地/私有	是 — 你机器上的 ChromaDB	是	是

┌─────────────────────────────────────────────────────────┐
│  pip install roampal && roampal init                    │
│    Claude Code: hooks + MCP → ~/.claude/                │
│    OpenCode:    plugin + MCP → ~/.config/opencode/      │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  HTTP Hook Server (port 27182)                          │
│    Auto-started on first use, self-heals on failure     │
│    Manual control: roampal start / roampal stop         │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  User types message                                     │
│    → Hook/plugin calls HTTP server for context          │
│    → AI sees relevant memories, responds                │
│    → Exchange stored, scored (hooks or sidecar)         │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  Single-Writer Backend                                  │
│    FastAPI → UnifiedMemorySystem → ChromaDB             │
│    All clients share one server, isolated by session    │
└─────────────────────────────────────────────────────────┘

查看 dev/docs/ 获取完整技术细节。

要求

Python 3.10+
以下之一：Claude Code 或 OpenCode
平台： Windows, macOS, Linux（主要在 Windows 上开发和测试）
内存： 可用约 800MB（交叉编码器重排序 + 嵌入 + ChromaDB）
磁盘： 约 500MB 用于模型（多语言嵌入 + 重排序，首次使用时自动下载）
CPU： 任何支持 AVX2 的现代 x86-64 处理器（Intel Haswell 2013+ / AMD Excavator 2015+）
GPU： 不需要 — 所有推理均通过 ONNX Runtime 在 CPU 上运行

故障排除

重启 Claude Code（钩子在启动时加载）
检查 HTTP 服务器：curl http://127.0.0.1:27182/api/health

验证 ~/.claude.json 是否包含带有正确 Python 路径的 roampal-core MCP 条目
检查 Claude Code 输出面板中的 MCP 错误

确保你运行了 roampal init --opencode
检查服务器是否自动启动：curl http://127.0.0.1:27182/api/health
如果没有，手动启动：roampal start

这是预期的。Roampal 具有自愈功能——如果 HTTP 服务器停止响应，它会自动重启并重试。

仍然卡住？ 向你的 AI 寻求帮助——它可以直接读取日志并调试 Roampal 问题。

支持

Roampal Core 是完全免费且开源的。

支持开发：roampal.gumroad.com
功能建议与反馈：Discord
错误报告：GitHub Issues
需要 AI 记忆方面的帮助？联系：roampal@protonmail.com | LinkedIn

许可证

Apache 2.0

roampal-core