Nautilus Compass MCP
An MCP server of long-term memory for coding agents: search over past sessions on a local BGE-m3 model and a check for drift from earlier rules
- 1,254 ★ on the repository
- Last commit
Broad access
Why this level
- Plugin installation registers hooks on every prompt, tool call and session end in `~/.claude/settings.json` and injects results into the system prompt
- Stores and indexes past session text that may contain secrets and code; the hosted gateway accepts such data over HTTPS with a token
- Runs a persistent local daemon and writes files under `~/.claude`; tokens with read access across all projects need a separate flag
Install
- Works in
Manual install
pip install nautilus-compassRequires Python 3.10 or newer. Brings the commands nautilus-compass, compass-mcp, compass-a2a and others.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Plugin installation registers hooks on every prompt, tool call and session end in `~/.claude/settings.json` and injects results into the system prompt
- Stores and indexes past session text that may contain secrets and code; the hosted gateway accepts such data over HTTPS with a token
- Runs a persistent local daemon and writes files under `~/.claude`; tokens with read access across all projects need a separate flag
This is third-party code. Review the repository files before installing.
What it does
Nautilus Compass keeps a coding agent's memory between sessions and serves it over MCP. The `nautilus-compass` package installs from PyPI with `pip install nautilus-compass` and brings the console commands `nautilus-compass`, `compass-mcp`, `compass-a2a`, `compass-drift-history`, `compass-session-search` and `compass-session-writer`. For Claude Code there is a plugin route: the repository is cloned into `~/.claude/plugins/nautilus-compass`, `install.sh` installs the plugin and `daemon_start.sh` starts a local daemon with the BGE-m3 embedding model. The installer writes three hooks into `~/.claude/settings.json`. `UserPromptSubmit` pulls relevant past context before each prompt and checks for drift from rules, `PostToolUse` writes notes during the session, and `Stop` saves a summary to `~/.claude/.cache/compass-last-session.txt` at the end. Results are injected into the agent's system prompt. Drift is scored by comparing the prompt with a set of anchors describing real failures, so the warning arrives before the agent acts. The plugin's slash commands are `/compass-verify`, `/compass-drift`, `/compass-recall`, `/compass-search` and `/compass-status`. The server exposes 17 tools. The core seven: `ingest_obs` records an observation, `recall` searches memory by meaning and keywords, `session_search` searches session logs, `profile` aggregates a work profile, `drift_check` scores drift, `drift_history` shows its timeline, `feedback_log` records a positive or negative signal. For other clients (Claude Desktop, Cursor, Cline, Continue.dev, Zed) the `install_to_agent.py` script detects them and patches their MCP configuration. A hosted HTTPS gateway with tokens and per-user memory isolation also exists.
Who it is for. For developers who work heavily with Claude Code or Cursor and want the agent to remember past decisions and warn when it repeats an old mistake.
Good fit when
- The agent forgets decisions and agreements between sessions and you retell the project context each time
- You need search over an archive of past sessions: what was discussed, which mistakes were fixed, with `/compass-search` or the `session_search` tool
- You want a warning before an action when a new prompt resembles earlier failure patterns: `drift_check` handles that
- Memory should work locally on the built-in BGE-m3 embeddings, without sending text to an outside service
- Several agents or dialogs work on shared files and you need to track their agreements and task closure
Not a fit when
- You want memory as readable Markdown files with a link graph: Basic Memory in the catalog does that
- You are not ready for hooks in `~/.claude/settings.json`: the plugin install writes them, while the MCP route through `compass-mcp` does without
- The machine has no Python 3.10 or newer, or no room for the embedding model and the daemon
- You need memory that never stores past session text on disk: the server is built on storing and searching it
Example request
Connect Nautilus Compass to Claude Code and find in memory how we settled the database migration last timeMCP
- Transport
- stdio, http
- Authentication
- not required
Limitations
- The license is MIT with additional terms: the project's names and logo may not be used as trademarks, and the software may not be offered to third parties as a hosted service without a separate commercial license once the service has more than 100 paying users a month. Self-hosting, personal and internal use are allowed. GitHub shows the license as non-standard.
- The BGE-m3 daemon is started by hand after every boot. The first call after idle can take up to 90 seconds because the model loads; the client retries once with a longer timeout.
- `COMPASS_USE_INOTIFY=0` silently disables detection of new files, so search will not see fresh writes. With that value the daemon logs a warning.
- `recall` latency on the local daemon is about 200 ms; over the hosted HTTPS gateway the author measured 0.9–1.7 seconds per call.
- The hosted gateway is in open beta and needs sign-up and a token. Check that the gateway and the model download are reachable from your network.
- The repository holds many internal project documents, not only the plugin code, so find what you need through `docs/AGENT_ONBOARDING.md` and `docs/mcp-usage.md`.
How to disable. For the MCP route remove the server entry from the client settings and run `pip uninstall nautilus-compass`. For the plugin remove the three Compass hooks from `~/.claude/settings.json` and the `~/.claude/plugins/nautilus-compass` folder, then stop the daemon.
FAQ
How do I make Claude Code remember decisions from past sessions?
Install the Nautilus Compass plugin: clone the repository into `~/.claude/plugins/nautilus-compass` and run `install.sh` and `daemon_start.sh`. The `UserPromptSubmit` hook injects relevant past context into the prompt and `Stop` saves a summary at the end of the session.
Which hooks does Compass add to Claude Code settings?
Three: `UserPromptSubmit` for memory recall and drift checking, `PostToolUse` for writing notes during the session and `Stop` for the end-of-session summary. All of them are written to `~/.claude/settings.json`.
What does drift_check do?
The tool compares a prompt with a set of anchors describing real earlier failures and returns a drift score. If the anchors file is missing next to the plugin, the response carries `drift.anchors_error` and `should_alert: true` rather than a silent "no drift".
How do I connect Compass to Cursor or Cline?
Run `python ~/.claude/plugins/nautilus-compass/scripts/install_to_agent.py`. The script detects Claude Desktop, Cursor, Cline, Continue.dev and Zed and extends their MCP configuration. Ready-made configs per agent are in `docs/AGENT_ONBOARDING.md`.
Can I use Compass without the cloud?
Yes, the default mode is local: the daemon on your machine computes BGE-m3 embeddings. The `compass.nautilus.social` hosted gateway with a user token is optional and connected separately.
How do I limit a token's access to projects?
Tokens are issued with scopes: `ops/compass_token_admin.py grant <agent> --scopes read:<project>,write:<project>`. Reading across all projects requires the explicit `--yes-i-want-star` flag, and the quickstart script issues read-only, current-project tokens by default.
Discussion
No questions or reviews yet.
Related
MCP serversKnowledge-graph memory for agents: Claude Code and Codex plugins, an MCP server and a Python library
Self-hosted long-term memory for agents: semantic search, a knowledge graph and autonomous consolidation over MCP and a REST API
Local memory for agents: stores conversations and project files verbatim and retrieves them with semantic search over MCP
Local memory for Claude Code, Codex and Cursor Agent: learns from your activity on a Mac and gives agents context with source receipts over MCP
Local persistent memory for coding agents: hooks record every session, and Claude Code, Codex or Cursor recall past decisions through 54 MCP tools
Engram by Gentleman Programming
Engram (Gentleman Programming)
Persistent memory for AI coding agents in a single Go binary: an MCP server on SQLite with full-text search that remembers your project across sessions
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Nautilus Compass (this entry) | no | not required | 1,254 | |
| Mem0 | no | 67,710 | a memory layer with plugins for Claude Code, Codex, Cursor and OpenCode, plus a CLI and SDK | |
| MegaMemory | no | not required | 726 | an MCP memory server built as a graph of concepts, architecture and project decisions |
| Basic Memory | no | not required | 4,323 | memory in local Markdown files with a link graph, semantic search and MCP access |
README in short
The front page opens with a section on the project's new direction, independent judging and verification within the Nautilus platform, then describes three pillars: long-term memory, drift detection and contracts between agents. Next come installation from PyPI and as a plugin, connecting other MCP clients and the hosted gateway, a table of seven core tools and token scopes. The page ends with a comparison against other memory layers, environment variables, links to documents and a summary of measurements that the author presents as their own reproductions.