nautilus-compass: a local memory layer that insists on being audited

Installing three packages that do different jobs

The README presents nautilus-compass as one plugin with three pillars, and the PyPI table then splits it into four distributions. The main package installs the CLI, the MCP server and the A2A adapter:

pip install nautilus-compass

The install is one line because the surface is a set of console scripts rather than a library API: `nautilus-compass` for the CLI, `compass-mcp` for the MCP server, `compass-a2a` for agent-to-agent transport, plus `compass-drift-history`, `compass-session-search` and `compass-session-writer` for session tooling. The README names Claude Code, Claude Desktop, Cline, Cursor, Continue.dev and Zed as hosts, which all speaks MCP.

Two companion packages sit alongside it. `assay-verify` handles ed25519 signed receipts for AI output, described in the README as attest at generation and verify on consume. `jev-trust` is trust middleware for a decision API that logs calls and measures calibration in your own domain. Neither is imported by the main package as far as the README explains, and that separation matters if you only want the memory layer.

The repo carries 1,255 stars, 36 forks and 32 open issues, is licensed as Modified MIT in its own manifests, and was pushed on 2026-10-06. The homepage is compass.nautilus.social, and the topics list is agent-heavy: `agent-memory`, `long-term-memory`, `cross-agent`, `local-first`, `mcp`, `a2a` and `rag`.

Two benchmark numbers that do not agree with each other

The README claims the layer beats mem0 on all three LongMemEval-S metrics and prints a table. On a full 500 question run, compass records P@1 0.890, P@5 0.978 and MRR 0.929, against mem0 2.0.19 at 0.774, 0.916 and 0.834. The badge at the top of the file repeats the 97.8% P@5 figure and names the evidence file it came from, `docs/evidence/headhead_mem0_full500_20260826.json`.

The packaging disagrees. `package.json` for the same version 3.3.0 carries the description `LongMemEval-S 56.6%`, and `pyproject.toml` describes itself with `LongMemEval-S 500q head-to-head retrieval P@1 0.890 vs mem0 0.774` plus `e2e 42.6% to 75.4%`. So three numbers circulate for one release: 56.6% in the npm-style manifest, 75.4% end to end in the Python manifest, and 89.0% retrieval P@1 in the README table. None of them is wrong about its own metric, but only the README explains what is being measured, and the manifest string a package index will show you is the one most people read.

There is a second caveat the README states plainly. Both sides ran `infer=False` with each project on its own default embedder, which means compass used bge-m3 locally while mem0 used Vertex AI text-embedding-005. That is the fairest available comparison in the sense that neither side was tuned, but it is not an equal-compute comparison, and a reader deciding between the two should know it before treating the margin as a property of the memory architecture.

The README also publishes its failures, which is rarer than it should be. It states that cross-encoder reranking hurts on this corpus, that candidate pool size is a no-op and that swapping in a Qwen3-0.6B embedder is a wash.

Reproducing the retrieval claim without an LLM in the loop

Because the comparison is retrieval-only, the project can offer a reproduction that needs no model calls. The README gives one command for the full set and an environment variable for a smoke run:

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

The twelve question subset is the sensible first move, since it exercises the same routing logic without the full cost. The README states the run works on CPU with a GPU recommended for all 500.

What the script actually reproduces is retrieval quality, not agent behaviour. The end to end numbers live elsewhere: `BENCHMARKS_REPRODUCE.md` sits at the repo root, and the 3.0.0 release notes describe a paired control experiment on recall usefulness where the delta was 1.0 on a sample of three items, moving from 0 of 3 to 3 of 3. A three item result should be read as a direction, not a rate, and the project links a long blog post with the underlying data.

The 3.2.0 release is where the evidence story gets its shape. VerifyPack 0.2 turns each public figure into a sealed pack containing `pack.json`, a sha256 manifest, claims recomputable from payload bytes and an ed25519 signed receipt, verified through `python -m tools.verifypack`. One figure is deliberately left unsealed: the 81.6% dual accounting number, because it cannot be recomputed from bytes inside the pack. Refusing to seal a number because it will not recompute is a better signal than a wall of badges, and it is worth checking whether the figure you care about is one of the sealed ones.

Drift scoring runs before the agent does anything

The second pillar is the one the README argues no competitor ships. Rather than trusting that recalled memory prevents a repeat mistake, compass scores every incoming prompt against an anchor set built from real failures, 25 positive and 35 negative examples, and reports a risk signal with the response. The stated numbers are AUC 0.83 on held-out data, p95 latency under 50 ms and a 0.5% fire rate on production traffic. The argument is structural: a system that only stores text has to abstract a prompt into facts before it can judge it, and the project claims that abstraction step is out of reach for white-box memory layers.

The deploy notes describe how this fails, which is more useful than a success rate. If `anchors.json` is missing from the plugin directory, drift responses now carry `drift.anchors_error` and `should_alert: true`. The README is explicit that this used to silently return no risk and calls that a security hole. That admission is a good sign about the current code and a warning about versions before the fix.

A second silent failure is documented alongside it. Setting `COMPASS_USE_INOTIFY=0` disables new file discovery, which means recalls stop seeing fresh writes without an error, so the daemon logs a warning when the flag is off. Both of these are the kind of detail that only surfaces in a README written by someone who has been burned, and both are reasons to check the plugin directory contents before trusting a silent result.

Contracts between dialogs, and the handoff notes left in the tree

The third pillar covers several agents or several chat dialogs touching shared files. Compass derives implicit contracts from handoff documents, tracks whether they closed, and audits for fake closure and red drift. The evidence offered is a field study of four dialogs over 28 hours in `docs/case_study_4dialog_compass.md`. The `examples/` directory backs the claim with runnable pieces including `a2a_tls_demo.py`, `a2a_peer_demo.py`, `full_capability_demo.py`, `multi_client_demo.py` and a set of `v7_governance_demo.py` and default capability JSON files.

The repository root tells a different story about how the project is run. It contains fourteen `HANDOFF_*.md` files, dated from 20260704 through 20261006, eight `_BROADCAST_*.md` coordination snapshots, a `DECISION_LEDGER.md`, a `GOAL_SSOT_20260823.md`, a `TASK_NEXT_capsule_distillation.md` and a stray patch file named `0001-perf-tools-memory_git_keeper-1513-Stop-49s.patch`. A committed `.coverage` file and a `.seen_compass` marker sit alongside them. For a repository whose selling point is disciplined cross agent state, the root reads like an operations diary that was published rather than curated.

Neither fact cancels the other. The same project that publishes twelve handoff notes can also ship a working governance demo, and plenty of well used repositories accumulate dated notes. What it changes is what to expect from the tree: if you are evaluating the project by how it organizes code, expect `nautilus_compass/` plus `tools/`, `docs/`, `examples/` and `sdk/`, and ignore the markdown at the root. If you want to see how the authors actually coordinate agents, those handoff files are the most direct evidence in the repository, more direct than any case study.

Deployment paths, and a compose file from an older version

The README's thirty second path clones into the Claude plugin directory and runs an installer:

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

The installer wires hooks into the host's configuration, and a separate script starts the BGE-m3 daemon once per boot. Token edits to `tokens.json` hot reload through an mtime check as of 3.1.0, and the first recall after the daemon has been idle can take up to 90 seconds while the model loads, with the MCP client retrying once on an extended timeout.

The container route is where the version drift shows. Both `Dockerfile` and `docker-compose.yml` are headed `compass v1.0` with a status line of 2026-05-05, while the shipped version is 3.3.0. The compose file documents an initial migration step through `tools/migrate_to_sqlite.py` and lists a `postgres` service marked optional for v1.1 and later, which sits oddly against a release that introduced SQLite as the write target with atomic pkl writes and per project locks. Nothing in the tree says whether the compose template is still maintained.

Licensing needs a note too. GitHub's own license detection returns NOASSERTION for this repository, while `pyproject.toml` and `package.json` both declare `LicenseRef-Modified-MIT`, the README badge says Modified MIT, and a `LICENSE-ANCHORS` directory sits at the root. A modified MIT is not a standard OSI identifier, so if your compliance process needs to resolve a license automatically, read `LICENSE` and `LICENSE-ANCHORS` directly rather than trusting the badge. The same caution applies to the badge row that says ClawHub audit Pass: nothing in the README explains what was audited.

Editorial conclusion

nautilus-compass is at its best as a self-hosted recall store for a coding agent, where the local embedding model and the MCP tool surface are the whole point and you control the storage. Drift scoring is the genuinely different piece, and the install notes are honest about how it fails. The benchmark claims are the part to handle carefully: the README table, the two package manifests and the release notes all carry different figures, so pick the evidence file you are willing to re-run rather than the badge. Start with the pip install and a smoke reproduction of twelve questions, then read docs/evidence/ and the reproducibility notes before deciding whether the retrieval numbers matter to your workload.

Frequently asked questions

Official sources

1. chunxiaoxx/nautilus-compass on GitHub
2. Issues
3. Project website
4. README
5. Releases