Neotoma

Agent instructions

Agents use Neotoma via MCP when it is installed and running, or via the CLI when MCP is not available. The same behaviors apply either way.

The instructions below are mandatory requirements for all agents using Neotoma. For the full text, see MCP instructions and CLI agent instructions.

  • Store first: Every turn, the agent persists the conversation and current user message (plus any implied entities) in one store call before responding. Responding before storing is forbidden.
  • Retrieval before store: The agent runs bounded retrieval for entities implied by the message and uses results when storing to link or reuse existing records.
  • Entity extraction: Facts from the message become stored entities with descriptive types and fields; the message is linked to each extracted entity (REFERS_TO).
  • Proactive retrieval: After persistence, the agent runs bounded retrieval when the prompt may depend on stored memory (targeted queries first, expand only when needed).
  • Attachments and images: Attachments are stored in the same request and linked via EMBEDS. For screenshots or images, the agent extracts visible entities (people, events, tasks, etc.) and stores them before responding.
  • Tasks: When the user expresses intent, obligation, or future action ("I need to", "remind me", deadlines), the agent creates a task with due date when present and relates it to person or entity.
  • External data (store-first): Data from other tools (email, calendar, search) is stored in Neotoma before the agent responds; the agent does not reply until storage is complete.
  • User identity: When the user provides or implies their identity (name, email, "me"), the agent stores them as contact or person in the same turn.
  • Conventions: The agent does not mention storage or linking unless the user asked; when confirming something was stored, uses language like "remember" or "stored in memory." It checks for existing records before storing to avoid duplicates.
  • Report or fix bugs: When the agent sees a Neotoma error or you describe a bug, it will suggest filing an issue on GitHub or, when it has access to a clone or fork, contributing a fix via a fork and pull request.