chunxiaoxx/nautilus-compass

nautilus‑compass – Open‑source memory & reliability layer for AI agents

What it is – A locally‑run, plug‑in style service that gives large‑language‑model agents a long‑term memory store, a drift‑detection guard, and a lightweight governance system for multi‑agent workflows. It ships as a Python package (nautilus‑compass), a Model‑Context‑Protocol (MCP) server, and a set of command‑line tools.

Why it matters –

• State‑of‑the‑art retrieval – Uses the BGE‑m3 embedding model and a hybrid BM25 + dense‑RRF search. On the public LongMemEval‑S benchmark it scores P@1 0.890, P@5 0.978, MRR 0.929, beating the popular mem0 baseline by >10 percentage points while staying fully local and ~14× cheaper to run.
• Drift detection – Every prompt is compared to a curated set of failure‑pattern “anchors”. The detector achieves an AUC of 0.83 on held‑out data, with sub‑50 ms latency, and only fires on ~0.5 % of production traffic.
• Cross‑agent contracts – When several Claude‑based agents share files, the plugin infers implicit hand‑off contracts, tracks their closure, and audits for “fake‑closure” or rule‑drift. A 28‑hour field study is documented in the repo.
• Open, reproducible evidence – All benchmark runs, data, and scripts are in the repo (e.g., scripts/reproduce_lmes_retrieval.sh). The authors also publish a paper, a Hugging Face dataset, and a live demo space.

How you use it

1. Install – pip install nautilus-compass (installs the CLI, MCP server, and A2A adapter).
2. Plug into an MCP client – The repo provides a tiny installer that drops three hooks into Claude Desktop (or Cursor, Cline, Continue.dev, Zed, etc.) so that on every user‑prompt submit the system:
   • recalls the most relevant past memory chunk,
   • runs the drift check, and
   • adds a profile summary.
3. Run the daemon – A BGE‑m3 embedding daemon is started once per boot (daemon_start.sh). The daemon watches a directory for new files (inotify), indexes them, and serves fast recall queries.
4. Optional cloud gateway – A hosted multi‑tenant MCP endpoint (https://compass.nautilus.social/mcp/) is available for teams that prefer a managed service. Tokens are scoped per user and all traffic is mTLS‑protected.

Key commands / tools (exposed via MCP JSON‑RPC):

Tool	What it does	Typical latency
ingest_obs	Store a new observation (auto‑anchors for drift)	~150 ms
recall	Semantic + keyword search across all indexed text	~200 ms
session_search	Time‑bucketed search inside a single chat session	~80 ms
drift_check	Score a prompt against failure anchors	<50 ms
profile	Summarise an agent’s current workload & drift trend	~100 ms

Benchmarks at a glance

Benchmark	Score (compass)	Comparison
LongMemEval‑S (500 q)	P@1 0.890, P@5 0.978, MRR 0.929	Beats mem0 0.774/0.916/0.834
LOCOMO‑10 (1 986 q)	P@1 0.644, P@5 0.890, MRR 0.740	+5.2 pp over mem0
EverMemBench‑Dynamic	44.4 % – 47.3 %	Highest among four published baselines
Drift detector AUC	0.83 (held‑out)	Only public memory layer offering drift detection
Cost per 500 q eval	≈ $3.50	~14× cheaper than GPT‑4o‑judged stacks

Where it fits in the AI stack

• Memory layer – sits between the LLM and the user, providing long‑term, searchable context without sending any data off‑device.
• Reliability guard – the drift detector acts as a safety net, flagging prompts that resemble known failure patterns before the model generates output.
• Governance – the contract system helps teams coordinate multiple agents that operate on shared resources.

Getting started quickly (Claude Desktop example)

# clone into Claude’s plugin folder
git clone https://github.com/chunxiaoxx/nautilus-compass ~/.claude/plugins/nautilus-compass
bash ~/.claude/plugins/nautilus-compass/install.sh   # installs hooks & daemon
bash ~/.claude/plugins/nautilus-compass/daemon_start.sh

After that, typing /compass-recall <query> in Claude will return the best matching memory chunk, and the system will automatically run drift checks on every prompt.

Resources

• PyPI – nautilus-compass (v3.3.0) – CLI, server, adapters.
• Paper & evidence – paper/BLACKBOX_VS_WHITEBOX.md, benchmark JSON files, and a full reproducibility script.
• Live demo – Hugging Face Space: https://huggingface.co/spaces/chunxiaox/nautilus-compass
• Model for judging – nautilus-compass/nacre-judge-v1 (1.7 B LoRA) on Hugging Face.
• MCP registry entry – io.github.chunxiaoxx/nautilus-compass.

---

All statements above are taken directly from the repository’s README; no additional features have been inferred.