Roampal Core 是一个面向 AI 编程助手的持久化记忆 MCP 服务器，主打“基于结果”的记忆管理：能够帮助提升编程效率的建议会被晋升，误导性的建议会被降级。它兼容 Claude Code 与 OpenCode。
用途
- 为 Claude Code 和 OpenCode 提供自动化的长期记忆，让助手记住用户的历史、偏好以及此前有效的做法。
- 通过结果评分机制对记忆进行动态排序和淘汰，减少错误或过时建议被反复使用。
主要能力
- 自动注入上下文：用户输入消息时，Roampal 会在 AI 看到消息前自动注入相关背景，无需手动调用或改变工作流。
- 结果评分循环：Claude Code 通过 hooks 提示主模型每轮调用 score_memories 工具打分；OpenCode 使用独立 sidecar 在后台静默评分，不在 OpenCode 注册 score_memories 工具。评分默认关闭，需通过 roampal sidecar setup 显式配置，可选用本地模型（Ollama、LM Studio 等）或选择 Zen 免费模型（需明确选择，数据可能经 OpenCode 代理记录）。
- 五个记忆合集与命名记忆档案（v0.5.1）：可为不同项目、不同客户端（Claude Code 与 OpenCode）或工作与家庭等场景运行独立的记忆存储，全部通过 CLI 管理，无需手动编辑配置文件。
- 目录绑定（v0.6.0）：使用 roampal profile bind <name> 可将当前目录及其子目录固定到某个档案，靠近当前工作目录的绑定优先。档案优先级依次为 --profile 参数、ROAMPAL_PROFILE 环境变量、目录绑定、roampal profile use 持久默认值、"default" 回退。
- 记忆工具：AI 可使用一组记忆工具（原文未逐一列出具体名称）。
- 自我修复：若 HTTP 服务器停止响应，会自动重启并重试。
使用方式
- 安装：pip install roampal。
- 初始化：roampal init 自动检测已安装的工具；也可指定目标：roampal init --claude-code 或 roampal init --opencode。
- 重启编辑器后即可开始聊天使用。
- 评分模型配置：在 roampal init 过程中选择，或通过 roampal sidecar setup 配置。
- 服务管理：roampal start 手动启动，roampal start --profile X 指定档案启动；roampal profile switch 切换档案不再终止运行中的服务器；roampal profile bind <name> / unbind 绑定或解绑目录。共享服务器空闲 30 分钟后自动退出，前台启动的服务器不受此限制。
- 健康检查：curl http://127.0.0.1:27182/api/health。
适用场景
- Claude Code 和 OpenCode 用户希望助手跨会话记住项目上下文、个人偏好和有效做法。
- 需要按项目、按客户端隔离记忆，或需要工作与个人场景分离记忆的开发者。
- 无 GPU 的开发者，Roampal 本身在 CPU 上运行，基准测试管线可在单块 GPU 上运行且不依赖云。
限制与要求
- Python 3.10+（支持 3.13；3.11+ 具备完整的 -P 启动保护）。注意 Python 3.10 将于 2026 年 10 月停止支持。
- 需要已安装 Claude Code 或 OpenCode 之一。
- 平台：Windows、macOS、Linux（macOS 和 Python 3.13 自 v0.6.0 起纳入 CI 测试，主要开发环境为 Windows）。
- 内存：约需 500MB 可用内存（cross-encoder 重排器 + 嵌入 + ChromaDB）。
- 磁盘：模型约 500MB（多语言嵌入与重排器，首次使用时自动下载）。
- CPU：支持 AVX2 的现代 x86-64 处理器（Intel Haswell 2013+ 或 AMD Excavator 2015+）。
- GPU：不需要，所有推理通过 ONNX Runtime 在 CPU 上运行。
- 评分默认关闭，需要用户显式配置后才启用；Zen 免费模型需明确选择，数据可能经 OpenCode 代理记录。
- 基准测试成绩（85.8%，基于修正版 LoCoMo，覆盖 1,986 个问题、10 段对话、双重评分）与相关论文、评估脚本见项目实验室资料。
版本要点
- v0.6.0：服务器生命周期改进、按目录的档案绑定、去重安全网、CLI 拆分为包结构、隐私修复（OpenCode 插件仅在显式选择后才发送数据至 Zen）。
- v0.5.9：内存占用优化，进程占用从约 2,355MB 降至约 484MB，嵌入器与重排器升级为 INT8 导出。
- v0.5.8：崩溃恢复，启用 SQLite WAL + FULL 持久性。
- v0.5.7：启动垃圾回收，状态文件过期清理。
- v0.5.4：档案绑定改为按请求维度。
项目完全免费且开源。支持开发可访问 roampal.gumroad.com；功能建议与反馈通过 Discord，缺陷报告通过 GitHub Issues，联系邮箱 roampal@protonmail.com。
