Core concepts

Code shows what a system does. It does not always explain why you chose that behavior, or which alternatives you ruled out. A new agent session needs those reasons before it changes the implementation.

A Nauro decision records a choice that should guide future work: the requirement or approach, why it matters, and the alternatives you rejected.

If a later agent proposes a cloud fallback, this decision gives it a specific constraint to check. The agent can suggest a local retry, or explain why the requirement needs to change.

These answer different questions. Keep them separate so completed work and unresolved ideas do not become requirements by accident.

A routine refactor or passing test usually belongs in current state. Record a decision when the reason should constrain how future work is done.

1. Load the project context. The agent reads the current state and project summary when work begins.
2. Check the proposed approach. check_decision retrieves related decisions. For the recording app, the query should mention transcription, cloud fallback, and privacy.
3. Read the relevant decisions in full. The agent uses get_decision to inspect the requirement, reasoning, and history before choosing an approach.
4. Apply the decision or raise a conflict. The agent can change its plan, explain a tradeoff, or ask you to reconsider the requirement.

Retrieval is advisory. A match is context for the agent to assess. It is not proof that a change is wrong, and no matches does not mean a change is safe.

A decision approved while working with Codex can also inform Claude Code when both connect to the same Nauro project. A new chat or a different agent does not have to reconstruct the reasoning from an earlier conversation.

See Connect your agent for access to the same project, or Using Nauro for the session workflow.

An agent can read decisions and propose an approach. Before it adds, updates, or replaces a decision, it must show you the complete proposed change and get your approval to record it.

For the recording app, accepting a code change does not silently replace the privacy requirement. If you decide to allow cloud transcription, the agent must propose that decision change explicitly.

The approval step happens in your conversation with the agent. The write tool propose_decision writes once validation passes; it does not open a second approval prompt. See how a decision gets recorded.

Decisions can change as requirements change. Nauro keeps the earlier reasoning so an agent can tell which choice applies now and why it replaced the old one.

• Add a decision when you settle a new choice.
• Update a decision when the choice stays the same and you need to add reasoning or evidence. This appends to its rationale and increases its version.
• Supersede a decision when you replace the choice. The new decision links to the old one; the old decision becomes superseded and points to its replacement.

For example, “Keep all recordings local” might become “Allow cloud transcription only after explicit consent.” That is a replacement decision. Evidence that local retry improved reliability would be an update to the existing reasoning.

An active decision is the current choice. A superseded decision remains useful history. Neither a recent timestamp nor a high search rank is a substitute for reading its status and scope.

The local CLI and macOS app keep the project record as Markdown on your machine. Hosted MCP gives a connected agent access to context stored in your cloud project. Data storage explains both locations.

Connecting two agents to different projects does not share their decisions. A repository clone also does not contain the full local store. Use the same project when you want the same context.

Nauro stores project context, such as decisions, state, and open questions. Connected AI tools receive the context they request, so their data policies also apply. Nauro sends no product analytics. See the privacy policy for details.

The same record supports planning, implementation, testing, and maintenance. In the recording example, the privacy decision guides the design, the fallback code, and the tests for failed transcription.

Human guidance is optional in every phase. New or revised project judgment requires your approval.

• Set up your first project and connect a coding agent.
• Use Nauro in a session to check an approach and record a decision.
• Inspect your project files to understand storage and portability.