Skip to main content
Agent skill

Neotoma Agent

Canonical turn protocol for agents writing to Neotoma. Bounded retrieval on the user message, store user message PARTOF conversation with REFERSTO edges to retrieved entities, store assistant reply the same way. Use this skill in any agent loop that should persist conversation state to Neotoma.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Neotoma Agent when an AI agent needs a reusable SKILL.md workflow for this job: Canonical turn protocol for agents writing to Neotoma. Bounded retrieval on the user message, store user message PARTOF conversation with REFERSTO edges to retrieved entities, store assistant reply the same way. Use this skill in any agent loop that should persist conversation state to Neotoma.

When not to use it

Skip Neotoma Agent when the task is outside the writing category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/neotoma-agent
# Save SKILL.md to ~/.claude/skills/neotoma-agent/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/neotoma-agent/SKILL.md. For a shared project, commit the folder at .claude/skills/neotoma-agent/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Neotoma Agent skill for this task: Use Neotoma Agent when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

69/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
56/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • chatgptinferred

    The skill text mentions ChatGPT or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • geminiinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • copilotinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • llamainferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • perplexityinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • mistralinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • grokinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# 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.

## Forbidden patterns

- **Persisting the user message without storing the assistant reply when you did reply.** The pair is the unit; orphan user messages misrepresent the conversation. - **Ending the turn without the closing assistant store when you produced a user-visible reply.** Same as above — both halves or neither. - **Skipping Neotoma for an entire rapid-fire session.** Even minimal turns (greetings, "ok", "yes") still get stored. Long runs of unstored turns leave the graph stale. - **Storing inferred content as `content`.** The `content` field is the literal user/assistant text. Summaries belong in observations on derived entities (`summary`, `tldr`), not as the message content.

## Using `@neotoma/agent`

```ts import { HttpTransport } from "@neotoma/client"; import { withMemory } from "@neotoma/agent";

const wrapped = withMemory( async (userMessage, ctx) => { // Build prompt with ctx.retrieved entities, call your LLM, return reply. return await callLLM(userMessage, ctx.retrieved); }, { transport: new HttpTransport({ baseUrl: "https://your-neotoma.example.com", token: process.env.NEOTOMA_TOKEN! }), conversationId: "conv-2026-05-20", platform: "my-agent", } );

const { assistantMessage } = await wrapped("Hello, what do you know about Acme Corp?"); ```

For explicit control over the open/close lifecycle (streaming, multi-step tool loops), use `NeotomaMemory` directly:

```ts import { NeotomaMemory } from "@neotoma/agent";

const memory = new NeotomaMemory({ transport, conversationId, platform }); const opened = await memory.openTurn({ turnId, userMessage }); // ... run agent loop, possibly multiple tool calls, using opened.retrieved ... await memory.closeTurn({ turnId, assistantMessage, refersTo: opened.retrievedEntityIds }); ```

## Provider-agnostic

`@neotoma/agent` does not call any LLM. It composes around any agent loop — Anthropic, OpenAI, custom HTTP, whatever. The protocol is the value; the LLM is the caller's choice.

Intended uses

  • Use Neotoma Agent when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.