Using Nauro

Once a repo is connected over MCP, the Nauro server ships instructions with the session that direct the agent to consult the record before technical work and draft choices for human approval. A typical session:

1. Catching up. At the start of a session the agent can call get_context for the project summary and diff_since_last_session for what changed since it last looked. Nothing forces this; the server instructions ask for it.
2. Before a change. When you propose something ("switch the cache to Redis", "store dollar amounts as decimal numbers"), the instructions direct the agent to call check_decision first. That returns related prior decisions by keyword-based BM25 retrieval, ranked, with a deterministic assessment. It never blocks anything and never judges the conflict; the agent is told to read the hits with get_decision and reason, and you keep the final call.
3. During the work. The record is read-heavy: search_decisions and get_raw_file answer "did we settle this?" questions without leaving the session.
4. When something gets decided. The agent drafts the addition, update, or supersession, explains the rationale, and waits for explicit approval before writing.
5. Wrapping up. One update_state call records what happened to the project state. nauro sync captures a snapshot and explicitly replaces AGENTS.md in the project's repos; it is the sole overwrite path, and a # Manual section survives replacement.

Adopt, setup, and incidental regeneration preserve an unmanaged AGENTS.md and warn.

Two honest caveats. Whether an agent follows the instructions is the agent's behavior, not a guarantee the tool can make; the check is advisory by design. And default retrieval is keyword-based BM25, with optional local embeddings as an augmenter, so a decision phrased in very different words than the proposal can still be missed; the assessment string says exactly that on every call.

Decisions enter the store through one tool, propose_decision, and the approval gate lives in the conversation, not in the kernel. The same gate applies to every add, update, and supersede. The working shape:

1. You and the agent settle a choice, including what was rejected and why.
2. The agent drafts the complete operation and shows it to you. This is the gate: it must not fire the call until you explicitly approve that write.
3. After approval, propose_decision commits immediately when structural validation passes. Similar existing decisions come back as advisory hits; they do not block the write. There is no second kernel confirmation prompt.

Changing an existing decision has two shapes. operation="update" appends to the rationale only (a dated paragraph, version bump); everything else, a changed title, new rejected alternatives, a replaced approach, goes through operation="supersede", which writes a new decision and flips the old one to superseded with cross-references both ways. Nothing is ever deleted; superseded decisions stay on disk as history. When in doubt the safe default is a plain add: a mistaken supersede is hard to reverse, an extra decision is easy to consolidate later.

You can also write from the shell without an agent: nauro note "Switched to Postgres for the audit log" -r "Need transactional writes" for quick entries, or the full nauro propose-decision form in the CLI reference.

Nauro touches three places, and only two of them are in your repo:

So: a fresh git clone of your repo carries the pointer and the committed AGENTS.md summary, not the full decision store. The store follows you (your machine, or your cloud-synced account), while the summary follows the repo. nauro status prints the absolute store path for the current repo along with which surfaces are active.

The full on-disk layout, file formats, and write discipline are on the data storage page.

The store is a directory of plain markdown and JSON. Copying it is a complete backup; there is no database and nothing hidden. snapshots/ inside it holds point-in-time captures taken by nauro sync and on every decision write. nauro validate checks a store's structure if you ever want to confirm a restored copy is intact.

Portability is the same property: if you stop using Nauro, the record remains readable markdown in that directory, and the on-disk format is a stable, semver-governed contract at 1.x.

To reach the same project from a second machine, or from surfaces with no local checkout (claude.ai web, Perplexity), promote it to cloud once and sync:

nauro auth login && nauro link --cloud && nauro sync   # machine 1, once
nauro auth login && nauro attach <project_id> && nauro sync   # machine 2, from the repo

nauro attach associates the checkout on the second machine with the existing cloud project, and nauro sync is pull-then-push. Convergence assumes sequential use by the project's single owner: finish and sync on one machine before writing from another. The cloud store has no compare-and-swap primitive or equivalent cross-request lock, so overlapping writes can lose updates. Chat surfaces read the same project through the hosted connector at https://mcp.nauro.ai/mcp; wiring details are on the connect page, and the 5,000 remote calls per month allowance is covered under plans and limits.

Hosted projects currently have exactly one member, the account that created them. There is no invite or shared-membership mechanism. A cloud project is the owner's record across their machines and surfaces, not a shared write surface.

What a teammate does get today:

• The committed summary. Every clone carries AGENTS.md, so their agent starts from the project's current context and decision summary even with no Nauro install at all. Keeping it fresh is one nauro sync before you push.
• Their own record. Nothing stops a teammate from running nauro adopt in their checkout and keeping their own store; the repos-to-projects mapping is per machine.
• The files. The store is plain markdown, so sharing a snapshot or the directory itself out of band works, with the ordinary caveats of manual copies.

The read-side summary in AGENTS.md is the current way to carry approved project context into another engineer's clone.

• Session shape: get_context / diff_since_last_session to catch up, check_decision before a change, propose_decision at the moment a choice is settled, one update_state plus nauro sync to wrap up.
• The agent is directed to consult the record by MCP server instructions; the check is advisory, never blocking, and every add, update, or supersede requires explicit human approval before propose_decision fires.
• Changing decisions: update = rationale-only append; anything else = supersede (old decision kept, flipped to superseded). Default to add when unsure.
• Commit <repo>/.nauro/config.json and <repo>/AGENTS.md; the store at ~/.nauro/projects/<id>/ is deliberately outside the repo and travels via cloud sync, not git. nauro status prints its absolute path.
• Backup = copy the store directory; it is plain markdown plus JSON snapshots, and the on-disk format is semver-stable at 1.x. nauro validate checks structure.
• Second machine: nauro auth login, nauro attach <project_id>, nauro sync (pull-then-push). Cross-machine convergence assumes sequential single-owner use.
• Hosted projects have a single member today (their creator). Teammates get the committed AGENTS.md summary with every clone.