neotoma-agent

Neotoma Agent Turn Protocol

This skill describes the canonical protocol an agent follows on every turn when writing to Neotoma. @neotoma/agent enforces this protocol by construction; this document describes what the protocol is and why each step exists, for agents and developers who want to understand or extend it.

The protocol

On every turn:

1. Bounded retrieval. Extract concrete identifiers (names, ids, quoted strings, capitalized phrases) from the user message. For each, call retrieveEntityByIdentifier. Keep the result set bounded (default 8 entities). Failures are non-fatal — proceed with an empty retrieved set.

2. Store the user message. Persist a conversation_message entity with:

   • role: "user", sender_kind: "user", content: <exact user text>
   • turn_key: "{conversation_id}:{turn_id}"
   • A PART_OF relationship to the conversation entity (created in the same store if it does not exist).
   • A REFERS_TO relationship to every retrieved entity from step 1.
   • idempotency_key: "conversation-{conversation_id}-{turn_id}-user-..." so re-runs of the same turn collapse onto one observation.

3. Run the agent. Invoke the underlying LLM with the retrieved entities available as context. The agent may use them to ground its reply.

4. Store the assistant reply. Persist another conversation_message entity:

   • role: "assistant", sender_kind: "assistant", content: <exact reply text>
   • turn_key: "{conversation_id}:{turn_id}:assistant"
   • A PART_OF relationship to the conversation entity.
   • REFERS_TO relationships to every entity the reply materially cites or produces.
   • idempotency_key: "conversation-{conversation_id}-{turn_id}-assistant-...".

Why each step exists

• Bounded retrieval before write lets the agent see what is already known, so it can correct or extend rather than re-create. Skipping this step produces duplicate entities and contradicts itself across sessions.
• PART_OF to the conversation makes the conversation queryable as a single unit: every message hangs off one root.
• REFERS_TO edges are the agent's working memory in graph form. They let downstream queries answer "which conversations touched this entity?" without re-reading every message.
• Deterministic idempotency keys mean the same turn replayed (timeouts, retries, hook fires) produces one observation, not many. The key shape conversation-{conversation_id}-{turn_id}-{role} is stable, predictable, and collision-free across turns.
• Exact content (no summarization at write time) preserves provenance. Summaries are a downstream interpretation, not a substitute for the source.