Nautilus Compass MCP: Setup for Claude, Cursor and Other Apps

• Finds relevant notes from your past sessions

  Searches the memory files under your Claude projects folder by meaning and by keyword, and returns the best matches plus anything from the last 24 hours that was not already in them. It needs the local search service running.

  Try: “What did I decide about the database schema last week?”

  Files · recall

• Searches past session notes by keyword

  Looks through the session notes in your projects for a word or phrase, and can filter by drift colour or entry type over a number of days.

  Try: “Search my old sessions for "rate limit".”

  Files · session_search

• Replays one long conversation thread in order

  Returns every saved message for one thread id in time order, so a multi-day back-and-forth is not squashed into a summary.

  Try: “Show me the whole thread_devto_launch conversation.”

  Files · thread_recall

• Summarises how you have been working

  Builds a profile from your saved sessions: top projects, kinds of work and the spread of drift colours over a number of days.

  Try: “Give me my work profile for the last 90 days.”

  Files · profile

• Shows how often the assistant drifted off course

  Counts green, yellow and red drift sessions across your projects and lists the worst red ones with their signals.

  Try: “Show my drift history for the last 30 days.”

  Files · drift_history

• Checks whether a prompt or action looks off course

  Compares the text to a set of good and bad example behaviours and returns a drift score and an alert flag. It needs the local search service running.

  Try: “Run a drift check on this plan before I start.”

  Read · drift_check

• Saves a note to your long-term memory

  Writes one observation as a memory file with a title, type, drift colour and optional links to other notes, so later sessions and other agents can recall it.

  Try: “Remember that we chose Postgres over MySQL because of JSONB.”

  Write · ingest_obs

• Records whether a drift alert was right

  Appends a good or bad signal with a short reason to a local feedback log, used later to retrain the drift examples.

  Try: “Mark that last drift alert as a false positive.”

  Write · feedback_log

• Scores which saved notes helped an action

  Records which memories an agent cited for an action and its outcome, computes a fixed-formula impact score and writes it to local log files.

  Try: “Log that note X helped task 42 succeed.”

  Write · proof_of_impact

• Looks for tasks marked done with nothing behind them

  Scans recent session notes for red drift, completed entries with an empty body and platform results with no published channel, then saves an audit file. It reports suspects and corrects nothing.

  Try: “Audit the last 7 days for fake completions.”

  Write · governance_audit

• Checks that core files were not changed

  Compares file hashes of the core recall and anchor files with a lock file, and writes a fresh lock if none exists or a rebuild is asked for.

  Try: “Check the governance lock.”

  Write · governance_lock_check

• Queues a task for the Nautilus platform

  Saves a task file in your projects folder for the Nautilus platform agents, and also posts it to a URL if COMPASS_PLATFORM_QUEUE_URL is set.

  Try: “Queue a publishing task for dev.to.”

  Write · submit_platform_task

• Splits a multi-channel task into sub-tasks

  Writes one queue file per channel so each part can be routed to a different executor. It does not run anything itself.

  Try: “Dispatch this launch to dev.to, X and GitHub.”

  Write · governance_dispatch

• Builds a step-by-step plan for a bigger goal

  Reads the local phase and capability registries, produces an ordered plan of sub-tasks with dependencies and writes a queue file for each unless dry_run is set.

  Try: “Plan the research, write and publish steps for this launch.”

  Write · governance_plan

• Used by the assistant behind the scenes

  Saves the result of a platform task

  Records a finished platform task as a JSON file and a searchable session note. It is normally called by the platform, not by you.

  Write · ingest_platform_task_result

• Registers a worker description

  Saves the spec of a background worker (cron, queue, http or custom) to a local file. The source says it does not run any code.

  Try: “Register a daily cron worker spec.”

  Write · add_worker

• Demo tool that sends progress updates

  Sends a number of progress messages and checks for cancellation between them. It exists to test clients that show progress.

  Try: “Run the long task demo with 5 steps.”

  Read · long_task

Watch out for

• Hosted use sends your notes to a third party

  The hosted gateway stores your memory on compass.nautilus.social under your token. Use the local route if your notes are private. github.com

• It writes memory, queue and audit files

  Several tools write files under ~/.claude/projects and the plugin folder. Some of these, including the platform task tools, are not in the read-only tool scope. github.com

• The PyPI package cannot start the server

  In the nautilus-compass 3.3.0 wheel, mcp_server.py runs `from mcp_durable.event_store import EventStore`, but the wheel ships only the gep and nautilus_compass packages and no mcp_durable. pip install or uvx therefore fails with an import error when compass-mcp starts. The module exists in the repository, so use the cloned repository route. pypi.org

• The installer says it registers hooks but does not write them

  The README says install.sh wires three hooks (UserPromptSubmit, PostToolUse, Stop) into ~/.claude/settings.json. The script in the v3.3.0 tag installs dependencies, starts a background service and prints that UserPromptSubmit and Stop are registered, but it contains no command that edits settings.json. The README and script disagree, so read it first and check settings.json afterwards. github.com

• Some write tools count as read scope

  Tools missing from the scope table default to the read scope in the code, even though they write files. Do not rely on a read-only token to block them. github.com

• License adds terms to MIT

  The LICENSE file is MIT plus extra terms: no use of the project's names or logo as your own, and no offering it as a hosted service to third parties once that service has more than 100 paying users in a month, unless you have a separate commercial license. The author and parties it authorizes in writing are exempt from the cap. Self-hosting, internal and personal use stay allowed. github.com

Security advisories