<!--
  Full-page Markdown export (rendered HTML → GFM).
  Source: https://neotoma.io/es/agent-instructions
  Generated: 2026-04-28T13:34:33.890Z
-->
# Agent instructions

These are the mandatory behavioral rules every agent follows when using Neotoma. They apply equally to [MCP](/mcp) (preferred when installed and running) and the [CLI](/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](https://github.com/markmhendrickson/neotoma/blob/main/docs/developer/mcp/instructions.md); the CLI-equivalent rules live in [docs/developer/cli\_agent\_instructions.md](https://github.com/markmhendrickson/neotoma/blob/main/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 single`conversation_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

[Store recipes and entity types

User-phase store, attachments, screenshots, chat fallbacks, schema-agnostic storage, type reuse, and schema evolution.

](/agent-instructions/store-recipes)[Retrieval, provenance, and tasks

Bounded retrieval, source provenance, three-layer analysis, session-derived artifacts, and task/commitment creation.

](/agent-instructions/retrieval-provenance)[Display, attribution, and conventions

Display rules, agent attribution, transport conventions, feedback reporting, error recovery, and onboarding.

](/agent-instructions/display-conventions)

◆

## Related references

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