Agent instructions

These are the mandatory behavioral rules every agent follows when using Neotoma. They apply equally to MCP (preferred when installed and running) and the CLI (used as a backup), so chat persistence, entity extraction, retrieval, attribution, and display behavior are identical across transports.

This page mirrors the canonical instruction block shipped to MCP clients at runtime. For the verbatim source see docs/developer/mcp/instructions.md; the CLI-equivalent rules live in docs/developer/cli_agent_instructions.md. The two are kept in parity by the sync rules under .cursor/rules/developer_agent_instructions_sync_rules.mdc.

Turn lifecycle

Every turn MUST complete in this order: (1) bounded retrieval, (2) user-phase store, (3) other MCP calls or host tool use, (4) compose the assistant reply, (5) closing store of the assistant reply. Do not respond before steps 1 and 2 are complete, and do not end the turn before step 5 unless the user explicitly waived persistence or the turn produced no user-visible reply.

• Step 1, Bounded retrieval. Use retrieve_entity_by_identifier for concrete identifiers (names, emails, ids, exact titles) and retrieve_entities for category or list queries; reuse or link existing records when matches surface.
• Step 2, User-phase store. Persist the conversation, the current user message, and any entities implied by the message in one store_structured call. If the user attached a file, include it in the same request and add the EMBEDS link. MUST NOT skip this for greetings or minimal messages.
• Step 3, Other actions. Host IDE tools (read_file, apply_patch, run_terminal_cmd, grep, codebase_search, web fetch) and other MCP tools may run only after steps 1 and 2 are complete. Host tools are not exempt from store-first.
• Step 4, Compose reply. Synthesize the answer using retrieval results and tool output.
• Step 5a, Closing store. After the user-visible reply is finalized, call store_structured with a singleconversation_message entity (role: "assistant", sender_kind: "assistant", exact reply text, turn_key: "{conversation_id}:{turn_id}:assistant") and an idempotency_key of conversation-{conversation_id}-{turn_id}-assistant-{suffix}.
• Step 5b, Closing relationship. Add create_relationship(PART_OF, assistant_message_id, conversation_id) targeting the conversation already created in step 2, never a new conversation.
• Step 5b.1, Reply-cited edges. Add REFERS_TO from the assistant message to every entity the reply materially cites or produces (synthesized notes/reports created this turn, existing entities named in the reply text). Skip when the edge already exists; chat bookkeeping (conversation, message) is excluded.
• Step 5c, Skip rules. Skip the closing store only when there is no user-visible assistant reply or the user explicitly waived persistence. FORBIDDEN: persisting the user message without storing the assistant reply when you did reply.
• Rapid-fire sessions. The store-first rule applies even during many small, fast instructions. If batching, store at minimum every 3-5 turns; never go an entire session without storing.
• Backfill. If asked to capture missed earlier turns or run /learn after a gap, store those user messages and assistant replies in the same turn (verbatim preferred; concise paraphrase when the transcript is unavailable). Do not defer to a later session.
• MCP availability detection. Do not infer availability from a workspace .mcp.json alone. If the host exposes Neotoma MCP tools or another active Neotoma transport, treat Neotoma as available and follow store-first.

Detailed instruction sections

Related references

• MCP server, actions catalog, transport modes, client configuration.
• CLI, commands, flags, and environment selection for the backup transport.
• REST API, HTTP endpoints, including GET /sources/:id/content and GET /stats.
• AAuth, agent attribution, trust tiers, and verification.
• Architecture, state-layer boundaries, determinism, and consistency model.
• Schema management, how to evolve types safely.