nautilus-compass

Open-source memory & reliability layer for AI agents. Long-term memory that now beats mem0 on all three LongMemEval-S metrics while staying fully local & 14× cheaper — plus drift detection and cross-agent contracts that no other memory layer ships.

Plugin for Claude Code / Desktop · Cline · Cursor · Continue.dev · Zed · any MCP client.

Built by Nautilus Platform · open agent ecosystem · join as agent →

🇬🇧 English (this file) · 🇨🇳 中文

What this is (2026-08 state)

Three pillars, one plugin:

1 · Black-box long-term memory — now with SOTA retrieval. Raw text embedded locally with BGE-m3. No extraction LLM at ingest, no graph, no data leaving your machine. In Aug 2026 we added utterance-routed chunk retrieval: single-session and knowledge-update questions route to turn-window chunks (the answer usually lives in ONE user turn; whole-session embedding dilutes it), everything else uses session-level hybrid (BM25 + dense RRF). Result on LongMemEval-S full 500 questions, same-question head-to-head vs mem0 2.0.19 (both sides infer=False, each on its own default embedder — bge-m3 vs vertexai text-embedding-005 — our reproduction):

One-command reproduction (retrieval-only, no LLM calls, CPU works / GPU recommended for the full 500):

bash scripts/reproduce_lmes_retrieval.sh            # full 500
SUBSET=12 bash scripts/reproduce_lmes_retrieval.sh  # smoke

The same utterance ammo overtakes mem0 on its own home benchmark (LOCOMO-10, n=1986: 0.644 / 0.890 vs 0.592 / 0.802) and fixes the single-session collapse on LongMemEval-M (0.20 → 1.00). Full evidence chain with per-type breakdowns and every config flag: docs/evidence/headhead_mem0_full500_20260826.json — including the experiments that failed (cross-encoder reranking hurts on this corpus; candidate-pool K is a no-op; Qwen3-0.6B swap is a wash).

2 · Drift detection — the half nobody else solves. Memory recalled doesn't stop the AI from breaking the rule this time. compass scores every prompt against an anchor set of real failure patterns (25 positive + 35 negative) before the agent acts. AUC 0.83 held-out, p95 latency <50 ms, fire rate 0.5% in production traffic. White-box layers abstract prompts into facts before drift becomes checkable — structurally out of their reach.

3 · Cross-agent contracts + governance. When you run multiple agents (or multiple Claude dialogs) on shared files, compass derives implicit contracts from handoff files, tracks closure, and audits for fake-closure / red drift. A 4-dialog 28-hour field study lives in docs/case_study_4dialog_compass.md.

The trade that flipped: earlier versions traded −30 points on LongMemEval-S for local deployment and cost. As of 2026-08 there is no trade — full sweep at 1/14 the reproduction cost (~$3.50 per 500 questions vs $50+ for GPT-4o-judged stacks). Full argument: paper/BLACKBOX_VS_WHITEBOX.md.

Quickstart

Packages on PyPI

Python package (PyPI · 3.3.0)

pip install nautilus-compass
# ships the CLI, the MCP server, the A2A adapter and session tools:
#   nautilus-compass · compass-mcp · compass-a2a
#   compass-drift-history · compass-session-search · compass-session-writer

30 seconds (Claude Code / Desktop · local daemon)

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

# start the BGE-m3 daemon (one-time per boot)
bash ~/.claude/plugins/nautilus-compass/daemon_start.sh

Deploy notes (field-verified pitfalls, 2026-08-28):

• COMPASS_USE_INOTIFY=0 disables new-file discovery — recalls won't see fresh writes, silently. Only set it if you know why; the daemon logs a WARNING when it's off.
• drift fails loudly now: if anchors.json is missing from the plugin dir, responses carry drift.anchors_error + should_alert: true (it used to silently return "no risk" — that was a security hole).
• Token changes to tokens.json hot-reload via mtime check (no systemd restart needed since v3.1.0).
• First recall after daemon idle may take up to 90 s (model cold-load); the MCP client auto-retries once with the extended timeout.

The installer wires three hooks into ~/.claude/settings.json:

• UserPromptSubmit → time-bucketed memory recall + drift check
• PostToolUse → mid-session writer
• Stop → end-of-session summary (writes a session battle-report to ~/.claude/.cache/compass-last-session.txt)

Slash commands: /compass-verify · /compass-drift · /compass-recall · /compass-search · /compass-status.

Any other MCP client

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

Auto-detects Claude Desktop, Cursor, Cline, Continue.dev, Zed and patches their MCP config. Per-agent copy-paste configs: docs/AGENT_ONBOARDING.md · raw protocol: docs/mcp-usage.md.

Cloud-hosted (open beta · self-serve)

The hosted gateway — MCP over HTTPS with scoped tokens and per-user memory isolation — is open for self-serve registration: sign up at https://compass.nautilus.social/signup, then create a token in the web console (or POST /tokens). Scopes are server-bound to your own space (read+write); cross-user access is denied and verified by automated probes. Design: docs/plans/2026-08-30-multi-tenant-memory-design.md.

MCP endpoint: https://compass.nautilus.social/mcp/ (Bearer token · streamable-http). Also listed in the official MCP Registry as io.github.chunxiaoxx/nautilus-compass (remote + PyPI self-host, dual entry) — registry-aware clients (Glama and other aggregators) can discover it from there. A2A discovery: curl https://compass.nautilus.social/.well-known/agent.json

Nautilus platform agents (cloud ssh quickstart)

For agents on machines with ssh access to your Nautilus cloud box — generates a scoped token, wires the cloud MCP bridge, writes .mcp.json, and runs an end-to-end self-check. Add --hud to install the fused status line (live recall hit-counter 🧠, drift state, 5-min traffic).

bash ~/.claude/plugins/nautilus-compass/ops/agent_quickstart.sh my-agent

Headline numbers