chunxiaoxx/nautilus-compass · 上手攻略

  • 仓库：chunxiaoxx/nautilus-compass
  • 链接：https://github.com/chunxiaoxx/nautilus-compass
  • 分类：agent / rag / evaluation / llm-infra
  • 作者：spark
  • 更新：2026-10-24

一、它是什么

nautilus-compass 是一个 Agent 的「记忆层 + 可靠性层」，由 Nautilus Platform 维护，主语言 Python。它不是又一个提示词框架，而是以 MCP 插件 的形式插进你的 Agent 宿主（Claude Code / Claude Desktop / Cursor / Cline / Continue.dev / Zed），在 Agent 每次行动前后做三件事：回忆、漂移检测、画像聚合。

它由三条相互独立的能力组成：

  1. 黑盒长期记忆（Black-box long-term memory） —— 用 BGE-m3 在本地对原始文本做向量化，写入路径零 LLM 调用，不做抽取、不建图谱、数据不出本机。检索层做「utterance-routed chunk retrieval」：单会话类/知识更新类问题路由到 turn-window 分块，其余走 session 级 BM25 + dense 的 RRF 混合。
  2. 漂移检测（Drift detection） —— Agent 动手之前，先把当前 prompt 与一组真实失败样本构成的 anchor set（25 正 + 35 负）做 BGE-m3 余弦比对，打分。这是它主打的差异点：白盒记忆层在写入时就把 prompt 抽象成事实，结构上无法在事后检测漂移。
  3. 跨 Agent 契约与治理（Cross-agent contracts） —— 多 Agent（或多个对话窗口）共享文件时，从 handoff 文件中推导隐式契约，追踪闭合状态，审计「假闭合」与「红色漂移」。

2026 年 10 月起，项目又长出第四条腿：独立评审与验证层（Independent Judging & Verification），包含 NACRE judge（把评审能力压进 1.7B LoRA）、caliber-bench（给「基准本身」打分的元基准）、预注册判据等。注意这一层的产物与开源的记忆层不是同一件事，部分是 SaaS 侧的。

成熟度自评：仓库卡片标注 research，PyPI 上 PyPI Classifier 写的是 Development Status :: 4 - Beta。许可为 Modified MIT（不是标准 MIT）。

二、它解决什么问题

  • Agent 记不住跨会话的东西。常规做法是「写入时用 LLM 抽取成结构化事实」，但这是在赌未来的查询分布——项目称之为 write-time wager。compass 把这个赌注全推到读取侧，e2e 分数因此从 42.6% 涨到 75.4%。
  • 召回了记忆也救不了这一次。记忆注入上下文后，Agent 仍可能当场违反某条项目规则。漂移检测补的就是这一段。
  • 多 Agent 协同时的责任黑洞：交接文件写了、状态说「已完成」，实际没做。没有契约追踪就只能靠人肉 review。
  • LLM-as-judge 的评分不可信：没有预注册判据的基准排行榜基本等于虚构。项目自己把这套叫 judge hygiene，并用「双账目（dual accounting）」同时报出「全集分」与「剔除 judge 掉线题后的分」。

三、快速安装

方式 A：PyPI（推荐，纯 Python 包）

pip install nautilus-compass
# 会装出这些可执行入口：
#   nautilus-compass        主 CLI
#   compass-mcp              MCP server
#   compass-a2a              A2A adapter
#   compass-drift-history
#   compass-session-search
#   compass-session-writer
  • 版本：PyPI 最新 3.3.0（发布于 2026-10-04），要求 Python ≥ 3.10。
  • ⚠️ 版本号有坑：仓库 main 分支 README 写的是「PyPI · 3.3.0」，但 PyPI JSON 接口里的 description 字段（即打包时冻结的 README 副本）仍写着 3.2.0。两者不冲突（3.3.0 确实是最新），但如果你在文档里看到 3.2.0，那是打包副本过期，不是版本回退。

方式 B：Claude Code / Desktop 插件（30 秒）

git clone https://github.com/chunxiaoxx/nautilus-compass ~/.claude/plugins/nautilus-compass
bash ~/.claude/plugins/nautilus-compass/install.sh

# 启动 BGE-m3 守护进程（每次开机跑一次）
bash ~/.claude/plugins/nautilus-compass/daemon_start.sh

安装脚本会往 ~/.claude/settings.json 里写三个 hook：

Hook 作用
UserPromptSubmit 时间分桶记忆召回 + 漂移检测
PostToolUse 会话中途写入观察
Stop 会话结束总结（写入 ~/.claude/.cache/compass-last-session.txt）

可用斜杠命令：/compass-verify /compass-drift /compass-recall /compass-search /compass-status。

方式 C：其他 MCP 客户端

python ~/.claude/plugins/nautilus-compass/scripts/install_to_agent.py

自动识别 Claude Desktop / Cursor / Cline / Continue.dev / Zed 并改写其 MCP 配置。

方式 D：云托管（公测，自助注册）

# 1) 注册：https://compass.nautilus.social/signup
# 2) Web 控制台建 token（或 POST /tokens）
# 3) MCP 端点（streamable-http + Bearer token）：
https://compass.nautilus.social/mcp/

# A2A 发现
curl https://compass.nautilus.social/.well-known/agent.json

同时在 官方 MCP Registry 以 io.github.chunxiaoxx/nautilus-compass 收录（远程 + PyPI 自托管双条目）。

想先看效果，不想装

HuggingFace 上有 CPU-only 的在线 demo（漂移检测 + Merkle 完整性），无需注册： https://huggingface.co/spaces/chunxiaox/nautilus-compass

四、核心用法

4.1 MCP 工具（17 个，核心七个）

工具 用途 本地守护进程延迟
ingest_obs(name, body, agent_id?) 写入观察，自动生成 anchor + 漂移信号 ~150 ms
recall(query, project?, top_k?) BGE-m3 语义 + 关键词混合检索 ~200 ms
session_search(query, since?) 按时间分桶检索会话日志 ~80 ms
profile(user_id?) 工作画像聚合（主题、Agent、漂移趋势） ~100 ms
drift_check(prompt, project?) 对 anchors 打漂移分 <50 ms
drift_history(since?, agent_id?) 漂移分时间线 ~30 ms
feedback_log(direction, reason) 记录正/负 anchor 信号 <20 ms

其余包括 thread_recall、proof_of_impact、long_task、平台桥（submit_platform_task / ingest_platform_task_result）、治理组（governance_dispatch / governance_audit / governance_lock_check / governance_plan）与 add_worker。协议为 JSON-RPC 2.0 over stdio / TCP / TLS / mTLS，notifications/*、logging/setLevel、resources/* 规范完整。

4.2 Token 权限（v2.3.1 起 least-privilege）

# 签发一个只读、限定项目的 token
python ops/compass_token_admin.py grant <agent> --scopes read:<project>,write:<project>

# 全项目召回（read:*，含 scope=user）需要显式确认
python ops/compass_token_admin.py grant <agent> --scopes 'read:*' --yes-i-want-star

HTTP 服务端逐次调用强制校验 scope，fail-closed。旧版 list 格式 token 为向后兼容映射为全访问。

4.3 复现论文里的检索数字

bash scripts/reproduce_lmes_retrieval.sh              # 完整 500 题
SUBSET=12 bash scripts/reproduce_lmes_retrieval.sh    # 冒烟测试

纯检索、无 LLM 调用，CPU 可跑（跑满 500 题建议上 GPU）。

# 基准入口
bash ops/bench_all.sh l0        # 快速层，无需 GPU
bash ops/bench_all.sh l1 30     # LongMemEval 子集

检索相关的开关是环境变量（位于 tests/eval_longmemeval_accuracy.py）： ZMM_UTTERANCE_RETRIEVE / ZMM_UTTERANCE_TYPES / ZMM_HYBRID / ZMM_RETRIEVE_K / ZMM_DATE_ANCHOR / ZMM_EMBED_CACHE。

4.4 拉取评测数据集

from datasets import load_dataset
ds = load_dataset("chunxiaox/nautilus-compass-test-data")

4.5 跑评审层（NACRE）

评审层配套产物在 HuggingFace 上：nautilus-compass/nacre-judge-v1（模型卡 + 权重）、nautilus-compass/caliber-bench-v0（开放样本包）。⚠️ 这一层依赖 Nautilus 平台的组织流程与预注册判据，并非装个 pip 包就能独立复现。

五、典型适用场景

  • 个人长期助理：Claude Code 每天干活，希望它记得上周定下的架构约束、没做完的待办。
  • 有明确规则的项目：团队要求「所有 DB 改动必须先写迁移脚本」，需要一条在 Agent 动手前就拦一道的护栏。
  • 多 Agent 流水线：主 Agent 派活给子 Agent，需要从交接文件自动推导契约并审计假闭合。
  • 合规/受控环境：数据不出本机、无 LLM 抽取成本、可离线复现基准。
  • 做 Agent 记忆评测：需要可复现脚本 + 公开证据 JSON，而不是一张 PPT。

六、坑与注意

  1. COMPASS_USE_INOTIFY=0 会静默失效。关掉后守护进程不再发现新文件，召回看不到新写入的内容，而且不报错。守护进程会打一条 WARNING，但如果你不看日志就会以为一切正常。只在确知原因时才设它。
  2. 锚点文件缺失曾是一个安全洞。旧版本 anchors.json 缺失时 drift 会静默返回「无风险」。当前版本改为显式报错：响应里带 drift.anchors_error + should_alert: true。如果你在用旧版本，漂移检测形同虚设——务必确认版本 ≥ 该修复点。
  3. 首次召回可能耗时 90 秒。守护进程空闲后模型冷加载，MCP 客户端会用延长超时自动重试一次。手工调用时别把超时设得太短。
  4. 延迟数字有两套，别混用。README 表格里的 ~30–200 ms 是本地守护进程实测值；走公网 HTTPS MCP 端点（https://compass.nautilus.social/mcp/）会叠加 TLS + WAN 往返，实测 p50 ≈ 0.9–1.7 s（2026-08-28 实测）。每 prompt 都要调用的话，云端方案的性能画像完全不同。
  5. 评分方法上的坑，README 自己写得很坦率，值得抄作业： - LongMemEval-V2 的初始评分用的是 4096 max token 的 judge，被推理过程吃掉，导致答案被系统性判零；换 16384 token 重判后 web 从 36.7 → 40.0。 - 有一个「弃权（abstention）」补丁因「拒答模板泄漏进可回答题目」而被预注册判据否决。 - LoRA 检索增强闭到 parity（2026-08-31）未采纳。 - 域路由 LoRA 分片出现 −36.6pp 回归（E-NACRE-1，已公开的负面结果），动态权重路由被暂停到语料 ≥3,000。 - README 明确说 EverMemBench 故意报较低的 Run 1（44.4%）而非较高的 Run 2（47.3%），以避免挑结果。
  6. 「beats mem0」要看清边界。对比是作者自己复现的（mem0 2.0.19，infer=False，两侧各用各的默认 embedder：bge-m3 vs vertexai text-embedding-005），不是第三方独立评测。README 也承认在 LongMemEval-M 上「还没有 mem0 的 head-to-head」。
  7. EverMemBench 不宣称 SOTA。只说超过四个已发表基线（Mem0 37.09 / Zep 39.97 / MemOS 42.55 / MemoBase 34.27），并明说 OMEGA、Mem0g 未公开报告。
  8. 失败实验也写进证据里：cross-encoder 重排在这份语料上反而有害；候选池 K 是 no-op；Qwen3-0.6B 替换是 wash。README 里的数字并非全挑好的报——这是加分项，但也意味着别指望每个开关都有提升。
  9. 许可不是标准 MIT，是 Modified MIT，商用前请读 LICENSE 原文。
  10. Python ≥ 3.10，低于此版本 pip install 直接失败。
  11. README 自称「唯一做漂移检测的公开记忆层」——这是项目方的宣传口径，本攻略未做第三方交叉验证。已知竞争者中 Letta、Zep、MemOS 等也有各自的评估/异常能力，但没有做同等形态的 prompt 级锚点漂移打分。

七、与同类对比

README 自带一张对比表（compass / mem0 / Letta / Zep / claude-mem / MemOS / Smriti）。按能力维度可以这样理解：

维度 nautilus-compass mem0 / Zep / MemOS 类 claude-mem 类
写入路径 LLM 调用 0 次（黑盒） 多数有抽取/图谱 LLM 调用 视实现
数据是否出本机 完全本地（BGE-m3） 常用云端 embedder 视实现
漂移检测 有（AUC 0.83 held-out） 无同等形态能力 无
跨 Agent 契约/治理 有（含假闭合审计） 无 无
MCP 接入 17 工具，stdio/TCP/TLS/mTLS 多数只支持 SDK 或 HTTP 多为 Claude Code 插件
长基准可复现性 有（脚本 + 公开 evidence JSON） 部分有 普遍较弱

差异化的三张牌：漂移检测、写入零 LLM 调用、跨 Agent 契约治理。前两张有量化数字支撑，第三张目前主要是 4-dialog 28 小时的实地研究（docs/case_study_4dialog_compass.md），证据强度弱一些。

同时也要看到反面：compass 的评测多为作者自测，而 mem0/Zep 有更广泛的用户侧采用与第三方评测；compass 的成熟度（Beta / research）低于成熟商业产品。

八、一句话结论

推荐：如果你用 Claude Code 且已经遇到「Agent 每次都失忆」或「Agent 反复违反同一条项目规则」这两个具体痛点，compass 值得花半小时装上试试——它把召回、漂移护栏和写入零成本三件事捆在一个 MCP 插件里，且完全本地；但如果你要的是「有 SLA 的生产级记忆服务」，请先自建评测基线，因为它的数字目前基本是作者自证的。

附：本文来源与核验状态

来源 用途 状态
https://raw.githubusercontent.com/chunxiaoxx/nautilus-compass/main/README.md 主体事实（安装、工具表、性能数字、坑） ✅ 已 fetch（2026-10-23 21:32 UTC）
https://pypi.org/pypi/nautilus-compass/json（JSON API） 最新版本 3.3.0、Python ≥3.10、发布时间 ✅ 已 fetch
仓库卡片 organized/repo_cards/3931-chunxiaoxx-nautilus-compass.md 分类、stars 1254、周增 +236、成熟度 research ✅ 已读
https://raw.githubusercontent.com/.../README.md 中 docs/*、paper/*、ops/* 等子路径 仅作为 README 内链接引用，未逐一打开 ⚠️ 未逐一核验

待核 / 不确定处： - ⚠️ PyPI 打包的 README 副本仍写 3.2.0，GitHub main 写 3.3.0；已核实 PyPI 最新为 3.3.0，但两处文档版本号不一致本身是遗留问题。 - ⚠️ 「唯一做漂移检测的公开记忆层」为项目方口径，未独立验证。 - ⚠️ 「beats mem0」为作者自测对比（作者自述其复现方式），非第三方评测。 - ⚠️ 漂移检测的安全洞修复具体落在哪个版本号，README 只说「现在会显式报错」，未给出对应 release 号。 - ⚠️ README 中 drift AUC、召回延迟、p95 等均为项目方自测环境数据，未在独立环境复现。