# Nautilus Compass [Health: Active] **Category:** 🧠 Knowledge & Memory **Repository:** https://github.com/chunxiaoxx/nautilus-compass **GitHub Stars:** 7 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/nautilus-compass ## Description Drift-aware cross-agent memory Β· MCP/A2A Β· LongMemEval-S 56.6% Β· 1/15 Zep cost ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `uvx` (confidence: high): ```json "mcpServers": { "nautilus-compass": { "command": "uvx", "args": ["nautilus-compass"] } } ``` ## Documentation & README # 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](https://nautilus.social)** Β· open agent ecosystem Β· [join as agent β†’](https://nautilus.social) πŸ‡¬πŸ‡§ English (this file) Β· [πŸ‡¨πŸ‡³ δΈ­ζ–‡](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/README.zh-CN.md) [![CI](https://github.com/chunxiaoxx/nautilus-compass/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/chunxiaoxx/nautilus-compass/actions/workflows/ci.yml) [![arXiv build](https://github.com/chunxiaoxx/nautilus-compass/actions/workflows/build-paper.yml/badge.svg?branch=main)](https://github.com/chunxiaoxx/nautilus-compass/actions/workflows/build-paper.yml) [![LongMemEval-S](https://img.shields.io/badge/LongMemEval--S-full500%20P%405%2097.8%25%20%C2%B7%20vs%20mem0%2091.6%25-brightgreen)](docs/evidence/headhead_mem0_full500_20260826.json) [![EverMemBench](https://img.shields.io/badge/EverMemBench-44.4%E2%80%9347.3%25-brightgreen)](paper/sections/paper2_06_5_evermembench.tex) [![drift-AUC](https://img.shields.io/badge/drift_AUC-0.83_held--out-brightgreen)](#how-it-works) [![PyPI](https://img.shields.io/pypi/v/nautilus-compass?label=PyPI&color=blue)](https://pypi.org/project/nautilus-compass/) [![MCP](https://img.shields.io/badge/MCP-17%20tools%20%C2%B7%20TLS%20%C2%B7%20RBAC-blue)](docs/mcp-usage.md) [![A2A](https://img.shields.io/badge/A2A-mTLS%20%C2%B7%20scoped%20peers-blue)](examples/a2a_tls_demo.py) [![license](https://img.shields.io/badge/license-Modified%20MIT-blue)](LICENSE) --- ## 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): | LongMemEval-S Β· n=500 | P@1 | P@5 | MRR | |---|---|---|---| | **compass** | **0.890** | **0.978** | **0.929** | | mem0 2.0.19 | 0.774 | 0.916 | 0.834 | One-command reproduction (retrieval-only, no LLM calls, CPU works / GPU recommended for the full 500): ```bash 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`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/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`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/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](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/paper/BLACKBOX_VS_WHITEBOX.md). --- ## Quickstart ### Python package (PyPI Β· 3.1.1) ```bash 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) ```bash 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 ```bash 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`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/docs/AGENT_ONBOARDING.md) Β· raw protocol: [`docs/mcp-usage.md`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/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`](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`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/docs/plans/2026-08-30-multi-tenant-memory-design.md). MCP endpoint: `https://compass.nautilus.social/mcp/` (Bearer token Β· streamable-http). 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 bash ~/.claude/plugins/nautilus-compass/ops/agent_quickstart.sh my-agent ``` --- ## Headline numbers | Benchmark | Score | Honest compare | |---|---|---| | **LongMemEval-S 500q full** (utt-routed + hybrid, n=500) | **P@1 0.890 Β· P@5 0.978 Β· MRR 0.929** | sweeps mem0 2.0.19 (0.774/0.916/0.834, our reproduction, each side on its own default embedder): +11.6/+6.2/+9.5pt. Largest flip: single-session-user P@1 0.90 vs 0.49 | | **LOCOMO-10** (n=1986 Β· mem0's home benchmark) | **P@1 0.644 Β· P@5 0.890 Β· MRR 0.740** | overtakes mem0 (0.592/0.802/0.677, our reproduction) +5.2/+8.8pt | | **LongMemEval-M 500q full** (~501 sessions/question) | **P@5 0.888** | 12x larger session pools cost only 9pt vs S500; ssu collapse fixed at n=500 (0.20 β†’ 0.93); ssp 0.53 newly exposed; no mem0 M head-to-head yet | | **EverMemBench-Dynamic** (n=500) | **44.4% (Run 1) / 47.3% (Run 2)** | tops the four published Table 4 baselines (Mem0 37.09, Zep 39.97, MemOS 42.55, MemoBase 34.27). Not claiming "industry SOTA" β€” OMEGA / Mem0g haven't reported publicly | | **LongMemEval-S e2e 500q full + summary layer** (doubao subject Γ— glm judge, 2026-09-03) | **75.4%** (377/500; 81.6% when excluding judge-disconnect questions, all re-judged and resolved) by type: ssu **96.9%** Β· ssa **85.4%** Β· tr **83.3%** Β· ms **73.2%** Β· ku 79.5% Β· ssp 75.0% | summary-layer verdict **PASS** (preregistered gates: msβ‰₯35/ssaβ‰₯40/trβ‰₯30 β€” all cleared 2Γ—). Cross-session types jumped +45~60pt (ms 22.6β†’73.2, ssa 25.0β†’85.4, tr 15.8β†’83.3) via per-session summary cards + date-anchored timeline β€” zero retrieval change, zero training, pure context engineering. All 71 judge-disconnect questions re-judged and resolved (same judge, retry only). Full verdict: [`vtf/_e2e_diag/arm_a_final_verdict.md`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/vtf/_e2e_diag/arm_a_final_verdict.md); baseline JSON: [`docs/evidence/e2e_500_full_20260829.json`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/docs/evidence/e2e_500_full_20260829.json) | | **LongMemEval-V2** (official benchmark by [xiaowu0162](https://github.com/xiaowu0162/LongMemEval-V2), 451q agent-trajectory memory Β· our tuned run, rejudged clean 2026-09-02) | **web 40.0% / enterprise 38.4%** (first untuned run 2026-08-30: 19.6% / 12.8%; paper reports frontier LLMs ≀14.1% without trajectory evidence) | brand-new multi-session benchmark (webarena agent trajectories); published untuned baseline AND tuned v2. Two levers: abstention judging alignment (bare-UNKNOWN 121β†’0; unanswerable-from-snapshot questions 2.8% β†’ 45.8% via the rubric's two legitimate routes) + retrieval unit upgrade (a11y-structure pruning, per-trajectory dense rerank, budget 12kβ†’24k; procedure +16.6pt). **Scoring correction 2026-09-02**: the original judge (4096 max tokens) was silently eaten by reasoning, systematically zeroing answers; full re-judge of all 156 LLM-graded questions (low-reasoning / 16384 tokens) moves web 36.7β†’40.0, ent 40.3β†’38.4 β€” these clean numbers are the current headline. Honest caveats: abstention route relies on judge discretion; web dynamic-type dipped -3.9pt. Follow-ups: LoRA retrieval-augmentation closed at parity (2026-08-31, not adopted); abstention-gate patch rejected by preregistered criteria (2026-09-02 β€” refusal template leaked into answerable questions, 92/89 items). Evidence: [`vtf/_compass_lmev2_out/`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/vtf/_compass_lmev2_out/) | | **Drift detector AUC** | **0.83 held-out / 0.92 in-set** | only public memory layer doing drift detection at all | | **Reproduction cost** | **~$3.50** / 500 questions | ~14Γ— cheaper than GPT-4o-judged stacks | | **p95 hook latency** | **<50 ms** | safe for every-prompt invocation | We deliberately report Run 1 (44.4%) as the EverMemBench headline to avoid cherry-picking; cross-run mean 45.84% clears MemOS by +3.3pt. Dual-run + Gemini cross-judge sensitivity analysis: [`paper/sections/paper2_06_5_evermembench.tex`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/paper/sections/paper2_06_5_evermembench.tex). **Try it without installing**: live drift-detection + Merkle-integrity demo at [huggingface.co/spaces/chunxiaox/nautilus-compass](https://huggingface.co/spaces/chunxiaox/nautilus-compass) (CPU only Β· metadata-mode jaccard fallback Β· no signup). **Reproduce the numbers** β€” eval dataset (behavioral anchors + labeled traces + LongMemEval-S / EverMemBench scoring) on the Hub: [huggingface.co/datasets/chunxiaox/nautilus-compass-test-data](https://huggingface.co/datasets/chunxiaox/nautilus-compass-test-data) ```python from datasets import load_dataset ds = load_dataset("chunxiaox/nautilus-compass-test-data") ``` Benchmark entrypoint: `bash ops/bench_all.sh l0` (fast layer, no GPU) Β· `bash ops/bench_all.sh l1 30` (LongMemEval subset). Retrieval levers are env-switched in `tests/eval_longmemeval_accuracy.py` (`ZMM_UTTERANCE_RETRIEVE` / `ZMM_UTTERANCE_TYPES` / `ZMM_HYBRID` / `ZMM_RETRIEVE_K` / `ZMM_DATE_ANCHOR` / `ZMM_EMBED_CACHE`). --- ## Glossary Terms this project coined and uses precisely. Other teams are welcome to use them for their own systems β€” that's what terms are for. **Judge hygiene** β€” the discipline of keeping an LLM judge trustworthy: preregistered criteria, function-level smoke tests, silent-failure detection, dual accounting, confidence intervals. If your benchmark uses an LLM judge without these, the leaderboard is fiction. See [the judging protocol](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/docs/nautilusmem/PROTOCOL.md) Β· [paper2](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/docs/papers/paper2_judge_hygiene.pdf). **Write-time wager** β€” compressing or summarizing memory at write time is a bet on the future query distribution, which is structurally unknowable. That's why the compass write path makes zero LLM calls; all intelligence lives at read time (e2e 42.6% β†’ 75.4% on identical memories and questions). **Dual accounting** β€” every headline score is reported twice: full set, and judge-outage-excluded set (75.4% / 81.6%). A single number hides judge failures; two numbers disclose them. --- ## How it works ``` User prompt: "Fix bug X for me" β”‚ β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ UserPromptSubmit Hook (this plugin)β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β–Ό β–Ό β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ recall β”‚ β”‚ drift β”‚ β”‚ profile β”‚ β”‚ memory β”‚ β”‚ check β”‚ β”‚ aggregateβ”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β–Ό Hooks inject results into Claude's system prompt: - Time-bucketed past memory (BGE-m3 semantic + keyword hybrid) - Drift score + nearest negative anchor (if score < threshold) - Profile facts ("you have 3 unfinished tasks in this repo") β”‚ β–Ό Claude answers β€” with full context loaded ``` Drift detector: each prompt vs anchor set (real failure transcripts), BGE-m3 cosine. AUC 0.83 held-out. --- ## What's exposed (MCP tools) **17 tools** β€” core seven: | Tool | Purpose | Latency (local daemon) | |---|---|---| | `ingest_obs(name, body, agent_id?)` | Write observation with auto-anchor + drift signal | ~150 ms | | `recall(query, project?, top_k?)` | BGE-m3 semantic + keyword hybrid search | ~200 ms | | `session_search(query, since?)` | Time-bucketed session-log search | ~80 ms | | `profile(user_id?)` | Work-profile aggregate (topics, agents, drift trend) | ~100 ms | | `drift_check(prompt, project?)` | Black-box drift score against anchors | <50 ms | | `drift_history(since?, agent_id?)` | Drift score timeline for trend audit | ~30 ms | | `feedback_log(direction, reason)` | Log positive/negative anchor signal | <20 ms | > Latencies are local-daemon figures. Over the public HTTPS MCP endpoint > (`https://compass.nautilus.social/mcp/`) add TLS + WAN round-trip: > measured p50 β‰ˆ 0.9–1.7 s per call (2026-08-28 field test). Plus: `thread_recall` Β· `proof_of_impact` Β· `long_task` Β· platform bridge (`submit_platform_task` / `ingest_platform_task_result`) Β· governance (`governance_dispatch` / `governance_audit` / `governance_lock_check` Β· `governance_plan`) Β· `add_worker`. JSON-RPC 2.0 over stdio / TCP / TLS / mTLS; `notifications/*`, `logging/setLevel`, `resources/*` spec-complete. Full guide: [`docs/mcp-usage.md`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/docs/mcp-usage.md). ### Token scopes (v2.3.1) Tokens are scoped, not global. `ops/compass_token_admin.py grant --scopes read:,write:` issues a least-privilege token; `read:*` (all-project recall, incl. `scope=user`) requires an explicit `--yes-i-want-star`. The HTTP server enforces scopes per call (fail-closed); legacy list-format tokens map to full access for backward compatibility. The quickstart script signs **read-only, current-project** tokens by default. --- ## Comparison | Capability | this | mem0 | Letta | Zep | claude-mem | MemOS | Smriti | |---|:---:|:---:|:---:|:---:|:---:|:---:|:---:| | Cross-agent memory | βœ… | βœ… | βœ… | βœ… | ❌ | βœ… | archive-only | | MCP A2A protocol native | βœ… TLS+mTLS+RBAC | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | Drift detection | βœ… AUC 0.83 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | Merkle integrity audit log | βœ… | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | LongMemEval-S retrieval (500q head-to-head) | βœ… **0.890 / 0.978 / 0.929** | 0.774 / 0.916 / 0.834 (our reproduction) | n/r | n/r | n/r | ❌ | ❌ | | LOCOMO-10 retrieval (n=1986) | βœ… **0.644 / 0.890 / 0.740** | 0.592 / 0.802 / 0.677 (our reproduction) | n/r | n/r | n/r | n/r | n/r | | EverMemBench verified | βœ… 44.4-47.3% | 37.09 | n/r | 39.97 | n/r | 42.55 | ❌ | | LongMemEval-S e2e (their own harness) | **500q full 75.4%** with summary layer (2026-09-04, all questions judged) β€” by type (final re-judged n=500): ssu 97.1 / ssa 83.9 / tr 62.4 / ms 69.2 / ku 80.8 / ssp 80.0; clean accounting excl. 71 outage: 96.9/85.4/83.3/73.2/79.5/75.0. Preregistered verdict PASS ([link](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/vtf/_e2e_diag/arm_a_final_verdict.md)) | 94.4% (self-reported) | n/r | n/r | n/r | n/r | n/r | *2026 newcomers not yet same-machine reproduced by us: Hindsight, Supermemory (self-reports LongMemEval SOTA), Cognee, LangMem, Membase β€” rows pending; their published numbers use their own harnesses and are not directly comparable to our head-to-head protocol.* | Self-host + hosted both | βœ… | ☁ only | βœ… | ☁ only | βœ… | OSS only | OSS only | | License | Mod. MIT | Apache | Apache | proprietary | MIT | Apache | MIT | `n/r` = not reported in their published evaluations. Smriti is a team conversation archive β€” different scope, listed for completeness. --- ## Case study Β· 4-dialog OSS multi-agent reliability 28 hours, four Claude Code dialogs on shared filesystem protocols: drift fired 314Γ—/7d (act-on rate instrumented), contract `cnt_compass_soul_sub_a1` closed in 17.92h vs 6d21h budget, 13 plan-dup audits saved ~40-50h, first cross-dialog L4 fire settled 50 NAU. Field log + 7 generalizable patterns: [`docs/case_study_4dialog_compass.md`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/docs/case_study_4dialog_compass.md). --- ## Advanced (opt-in surface)
Drift loop closure Β· act-on rate Every fired alert gets a stable `alert_id` in `.cache/drift_mitigation_log.jsonl`. Acknowledge via `feedback.py log fp|tp`; `audit_kpi.py` reports `act_on_rate(window_hours)` (target β‰₯0.70; <0.30 = cry-wolf β†’ raise threshold or retrain anchors). ```python from audit_kpi import act_on_rate m = act_on_rate(window_hours=168) assert m["rate"] >= 0.70 ```
v3 opt-in LLM switches (all default-off, byte-equal promise) With no opt-in env set, daemon behavior is byte-equal to v2.0.1 β€” gated by `tests/test_llm_opt_in.py` on every PR. | env var | tier | feature | |---|---|---| | `COMPASS_USE_LLM_RESOLVE` | 1 (session-end) | LLM contradiction resolution | | `COMPASS_USE_LLM_VERIFY` | 4 (runtime) | anti-confabulation cite-or-refuse | | `COMPASS_USE_LLM_DRIFT_PAY` | 4 (runtime) | drift Γ— outcome anchor feedback | | `COMPASS_USE_LLM_REFLECT` | 3 (periodic) | self-reflection semantic emit | | `COMPASS_USE_LLM_ECON` | 4 (runtime) | memory-as-economy NAU budget | Deterministic v3 surface (always on): typed knowledge graph layer (NO-OP until built), confidence scoring + contradiction hook, `MEMORY_REPORT.md` auto-gen, `implementation_notes` frontmatter. Registry: [`llm_opt_in.py`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/llm_opt_in.py).
Platform integration Β· BP1/BP3 + V7 governance OSS↔platform bridge without a new HTTP server: `submit_platform_task` (compass β†’ platform queue, file-based or HTTP when `COMPASS_PLATFORM_QUEUE_URL` is set) Β· `ingest_platform_task_result` (platform β†’ compass, searchable via `recall`). Round-trip demo: `python examples/platform_flywheel_demo.py`. V7 governance (multi-executor deployments): `governance_dispatch` (decompose 1 task β†’ N routed sub-tasks) Β· `governance_audit` (fake-closure / red-drift scan) Β· `governance_lock_check` (SHA256 lock on the L0 core). Demo: `python examples/v7_governance_demo.py`. Contract details: [`docs/PLATFORM_HANDSHAKE.md`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/docs/PLATFORM_HANDSHAKE.md).
Release history Β· v3.0.0 / v2.1.0 / v2.0.0 **v3.0.0 Β· "from memory library to evolution engine"** β€” same system closing the loop: memories feed a **extract fuel β†’ external verdict β†’ distill** cycle. Semantic-recall revival (Windows torch long-path fix), GOAL-SSOT ledger + hourly heartbeat, cloud capacity root-cause fixes (load 10-14 β†’ 1.x), daemon atomic pkl + per-project locks, paired-control evidence (tribal-fact retrieval 0/3 β†’ 3/3), fused HUD, 30-second quickstart. **v2.1.0 Β· drift v2 + line reconciliation** β€” cry-wolf fix (fire rate 64.5% β†’ 0.5% via rule-hit OR drift_score < βˆ’0.07), cross-agent contract scanner (L4 substrate), L3 tier promotion + PoI, daemon hardening (bounded pools, in-flight semaphore, BM25+vector RRF opt-in). **v2.0.0 Β· Opinionated EvoMap** β€” deterministic lifecycle layer on the black-box base. No LLM at ingest / tier promotion / forgetting; no vendoring of GBrain/OpenViking; no graph rerank for closed haystacks (cost βˆ’6.2pt in v0.8 β€” [`paper/RESULTS_v0.8.md`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/paper/RESULTS_v0.8.md)). Full notes: [`CHANGELOG.md`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/CHANGELOG.md) Β· release: [`v3.0.0`](https://github.com/chunxiaoxx/nautilus-compass/releases/tag/v3.0.0)
--- ## Documentation - [`docs/AGENT_ONBOARDING.md`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/docs/AGENT_ONBOARDING.md) β€” per-agent install configs (6 platforms + 3 frameworks) - [`docs/mcp-usage.md`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/docs/mcp-usage.md) β€” raw MCP protocol guide, TLS setup, RBAC - [`docs/PLATFORM_HANDSHAKE.md`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/docs/PLATFORM_HANDSHAKE.md) β€” OSS↔SaaS coordination contract - [`docs/evidence/`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/docs/evidence/) β€” raw benchmark evidence files (JSON, per-question rows) - [`paper/`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/paper/) β€” two papers (drift detection + memory pipeline) and eval scripts - [`ops/GPU_EVAL_RECIPE_4090.md`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/ops/GPU_EVAL_RECIPE_4090.md) β€” 12-minute rented-GPU benchmark recipe - [`CHANGELOG.md`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/CHANGELOG.md) Β· [`CONTRIBUTING.md`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/CONTRIBUTING.md) --- ## Citation **Paper 1 Β· drift detection**: ```bibtex @misc{nautiluscompass-drift-2026, title = {Nautilus Compass: Black-box Persona Drift Detection for Production LLM Agents}, author = {Chunxiao Wang}, year = {2026}, note = {Yiluo Technology Co., Ltd.}, howpublished = {\url{https://github.com/chunxiaoxx/nautilus-compass}} } ``` **Paper 2 Β· memory pipeline + EverMemBench cross-bench**: ```bibtex @misc{nautiluscompass-memrecall-2026, title = {Closing the Memory Recall Gap with Chinese LLMs: A Multi-Stage Retrieval Pipeline Achieving Zep-SOTA Performance on LongMemEval-S at 1/15 Cost}, author = {Chunxiao Wang}, year = {2026}, note = {Yiluo Technology Co., Ltd.}, howpublished = {\url{https://github.com/chunxiaoxx/nautilus-compass}} } ``` Prior work we build on (cite as appropriate): BGE-m3 / BGE-Reranker (BAAI 2024) Β· Persona Vectors (Anthropic, [arXiv:2507.21509](https://arxiv.org/abs/2507.21509), complementary white-box) Β· DPT-Agent ([arXiv:2502.11882](https://arxiv.org/abs/2502.11882)) Β· A-MEM ([arXiv:2502.12110](https://arxiv.org/abs/2502.12110)) Β· LongMemEval (Wu et al., NeurIPS 2024) Β· EverMemBench (Hu et al., 2026). --- ## License - **Code, plugin, MCP wrapper, papers, scripts** β€” Modified MIT License (MIT + trademark clause + hosted-service cap; self-hosting / internal deployment / personal use stay free forever β€” [`LICENSE`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/LICENSE)) - **Behavioral anchor files** (`anchors*.json`) β€” CC0 1.0 Universal ([`LICENSE-ANCHORS`](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/LICENSE-ANCHORS)) - Historical releases before this license's introduction were pure MIT. --- ## Star history [![Star History Chart](https://api.star-history.com/svg?repos=chunxiaoxx/nautilus-compass&type=Date)](https://star-history.com/#chunxiaoxx/nautilus-compass&Date) ## Contributors Contributors PRs welcome β€” see [CONTRIBUTING.md](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/CONTRIBUTING.md). ## Contact - **Author**: Chunxiao Wang Β· Yiluo Technology Co., Ltd. Β· `chunxiaoxx@gmail.com` - **Issues**: [github.com/chunxiaoxx/nautilus-compass/issues](https://github.com/chunxiaoxx/nautilus-compass/issues) - **Hosted gateway**: [compass.nautilus.social](https://compass.nautilus.social) - **δΈ­ζ–‡ζ–‡ζ‘£**: [README.zh-CN.md](https://github.com/chunxiaoxx/nautilus-compass/blob/HEAD/README.zh-CN.md)