Your production agent has amnesia
Without a state layer:
- Context drifts across sessions.
- Facts conflict across tools and tasks.
- Decisions execute without a reproducible trail.
Neotoma is the deterministic state layer for long-running agents. Every observation is versioned. Every entity snapshot is reproducible. Every decision can be replayed.
RAG retrieves documents. Platform memory personalizes chat. Neither maintains durable state. Neotoma does — with deterministic guarantees and no silent mutation.
The problem
Same question, different outcome
Without a state layer, agents return stale or wrong data. With Neotoma, every response reads from versioned, schema-bound state.
Conflicting records, silent data loss
Two agents read different versions of the same contract. One quoted current terms; the other used a stale snapshot. Neither knew the other existed.
Stale contact, wrong recipient
The agent used an outdated org chart. The message went to someone who left the project weeks ago — and no versioned record flagged the change.
Guarantees
Agent memory systems make different guarantees
Most AI memory systems optimize storage or retrieval. Neotoma enforces state integrity.
- Platform: built-in chat memory from Claude, ChatGPT, Gemini and others.
- Retrieval / RAG: vector stores like Mem0 and Zep that recall by similarity.
- Files: markdown, JSON, or CRDT docs the agent reads and writes directly.
- Deterministic: Neotoma’s append-only state layer with versioned, auditable guarantees.
Get started
Agents install Neotoma themselves
Paste this prompt into Claude Code, Codex, Cursor, or OpenClaw. The agent handles npm install, initialization, and MCP configuration.
Follow this workflow to set up Neotoma:
1. Install Neotoma with npm install -g neotoma.
2. Initialize Neotoma with neotoma init.
3. Report what changed after install/init.
4. If I ask for integration setup after init, link the matching setup guide in docs/developer/ (for example mcp_cursor_setup.md, mcp_claude_code_setup.md, mcp_openclaw_setup.md).
...More options: Manual install · Docker · CLI reference
Agent installs and initializes via npm, scans context and platform memory, previews candidates with provenance, and stores only what you approve.
State inspection
Inspect agent state like version control
When a production agent sends the wrong data, you need to trace why. Neotoma stores every state mutation as a versioned observation so the full timeline can be inspected and replayed.
Observation timeline
$ neotoma observations list --entity-id contract:Kline
# observed_at source change
1 Oct 10 import:drive (created)
2 Oct 12 agent:renewal renewal_date
3 Oct 14 agent:amendment payment_termsEntity snapshot with version history
$ neotoma entities get contract:Kline
entity_type: contract
entity_id: contract:Kline
version: 3
payment_terms: Net 30
renewal_date: 2026-01-15
Previous (v2): payment_terms: Net 60How it works
Architecture
Privacy-first
- Your data stays local. Never used for training.
- User-controlled storage, optional encryption at rest.
- Full export and deletion control.
Deterministic
- Same input always produces same output.
- Schema-first extraction, hash-based entity IDs, full provenance.
- No silent mutation.
Cross-platform
- One state graph across Claude, Cursor, Codex, and CLI.
- MCP-based access. No platform lock-in.
- Works alongside native memory features. Nothing to uninstall.
Neotoma treats memory as state evolution, not retrieval. Every state change is versioned with full provenance.
- Deterministic. Same observations always produce the same versioned entity snapshots. No ordering sensitivity.
- Immutable. Append-only observations. Corrections add new data — they never erase.
- Replayable. Inspect any entity at any point in time. Diff versions. Reconstruct history from the observation log.
- Structure-first. Schema-first extraction with deterministic retrieval. Optional similarity search when embeddings are configured.
Built for
Who's it for
One memory layer. Three worlds: infrastructure pipelines, agent systems, and the tools you use every day. Pick your lens.
AI infrastructure engineers
Two runs. Same inputs. Different state.
Agent system builders
Your agent resolves entities by inference. Every session, it guesses again.
AI-native operators
The agent infers. It doesn't guarantee. Here's what that costs you.
Interfaces
Three interfaces. One state invariant.
Every interface provides the same deterministic behavior regardless of how you access the agent state layer.
REST API
49 endpointsFull HTTP interface for application integration. Build dashboards, services, and automations on top of Neotoma state.
MCP Server
29 actionsModel Context Protocol for Claude Code, Claude, ChatGPT, Cursor, Codex, and OpenClaw. Agents store and retrieve state through structured tool calls.
CLI
43 commandsCommand-line for scripting and direct access. Inspect entities, replay timelines, and manage state from the terminal.
Resources
Learn more
Repository
Source code, README with installation and MCP setup, and the deterministic state layer architecture. Clone, contribute, or open issues.
Visit repo →
Documentation
Reference, integration guides, use cases, and architecture — organized by category.
Browse docs →
Deep dive
State integrity, deterministic evolution, state invariants, and why agent reliability depends on them. Architecture, pipeline, and guarantee reference.
Read architecture →
