Your agents forget. Neotoma makes them remember.
Versioned records — contacts, tasks, decisions, finances — that persist across Claude, Cursor, ChatGPT, OpenClaw, and every agent you run. Open-source. Local-first. Deterministic. MIT licensed.
neotoma.io · Evaluate · Install · Documentation
You run AI agents across tools and sessions. Without a state layer, you become the human sync layer:
- Every session starts from zero — nothing your agent learns carries over
- Facts conflict across tools — two agents store different versions of the same person
- Decisions execute without a reproducible trail — you can't trace why your agent acted
- Corrections don't stick — you fix something in Claude and it's wrong again in Cursor
These are not hypothetical. They happen every day in production agent systems. You compensate by re-prompting context, patching state gaps, and maintaining manual workarounds. Neotoma removes that tax.
Neotoma is a deterministic state layer for AI agents. It stores structured records — contacts, tasks, transactions, decisions, events, contracts — with versioned history and full provenance. Every change creates a new version. Nothing is overwritten. Every state can be replayed from the observation log.
Not retrieval memory (RAG, vector search, semantic lookup). Neotoma enforces deterministic state evolution: same observations always produce the same entity state, regardless of when or in what order they are processed.
graph LR
Sources["Sources (files, messages, APIs)"] --> Obs[Observations]
Obs --> Entities[Entity Resolution]
Entities --> Snapshots["Entity Snapshots (versioned)"]
Snapshots --> Graph[Memory Graph]
Graph <--> MCP[MCP Protocol]
MCP --> Claude
MCP --> ChatGPT
MCP --> Cursor
MCP --> OpenClaw
- Deterministic. Same observations always produce the same versioned entity snapshots. No ordering sensitivity.
- Immutable. Append-only observations. Corrections add new data, 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.
| Foundation | What it means |
|---|---|
| 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 memory graph across Claude, ChatGPT, Cursor, OpenClaw, Codex, and CLI. MCP-based access. No platform lock-in. Works alongside native memory. |
Most AI memory systems optimize storage or retrieval. Neotoma enforces state integrity. Full comparison with explanations →
| Property | Platform | Retrieval / RAG | Files | Database | Neotoma |
|---|---|---|---|---|---|
| Deterministic state evolution | ✗ | ✗ | ✗ | ✗ | ✓ |
| Versioned history | ✗ | ✗ | ⚠ manual | ✗ | ✓ |
| Replayable timeline | ✗ | ✗ | ✗ | ✗ | ✓ |
| Auditable change log | ✗ | ✗ | ⚠ partial | ✗ | ✓ |
| Schema constraints | ✗ | ✗ | ✗ | ⚠ partial | ✓ |
| Silent mutation risk | ⚠ common | ⚠ common | ⚠ common | ⚠ common | prevented |
| Conflicting facts risk | ⚠ common | ⚠ common | ⚠ possible | ⚠ common | prevented |
| Reproducible state reconstruction | ✗ | ✗ | ✗ | ✗ | ✓ |
| Human inspectability (diffs/lineage) | ⚠ partial | ⚠ partial | ⚠ partial | ⚠ partial | ✓ |
| Zero-setup onboarding | ✓ | ✗ | ✗ | ✗ | ✗ |
| Semantic similarity search | ✗ | ✓ | ✗ | ✗ | ✓ |
| Direct human editability | ✗ | ✗ | ✓ | ✗ | ✗ |
Platform: Claude, ChatGPT, Gemini, Copilot. Retrieval: Mem0, Zep, LangChain Memory. Files: Markdown files, JSON stores, CRDT docs. Database: SQLite, Postgres, MySQL. Neotoma: Deterministic state layer (reference implementation).
Ask your AI agent whether Neotoma fits your workflow. Paste this into Claude, Cursor, ChatGPT, or any MCP-capable tool:
Read https://neotoma.io/evaluate. Before you answer, inspect any broader tool, workspace, and configuration context you can access so you assess my real workflow rather than just this chat. Then tell me whether Neotoma is a real fit for my workflow, what data would be highest value to persist first, and what I should do next.
The agent reads the evaluation page, checks your context, and gives you an honest assessment. If it's a fit, the agent carries you through install and activation.
Agents install Neotoma themselves. Paste this prompt into Claude, Cursor, ChatGPT, or Codex:
Read https://neotoma.io/install and carry me through the install-first Neotoma flow. Install, activate it with my data, and configure my current tool for robust ongoing use.
The agent handles npm install, initialization, and MCP configuration. Manual install:
npm install -g neotoma
neotoma init
neotoma mcp configMore options: Docker | CLI reference | Getting started
neotoma store --json='[{"entity_type":"task","title":"Submit expense report","status":"open"}]'
neotoma entities list --type task
neotoma upload ./invoice.pdfResults reflect versioned entity state with full provenance. Agents perform the same operations through MCP tool calls (store, retrieve_entities, retrieve_entity_by_identifier).
Three interfaces. One state invariant. Every interface provides the same deterministic behavior regardless of how you access the state layer.
| Interface | Description |
|---|---|
| REST API | Full HTTP interface for application integration. Entities, relationships, observations, schema, timeline, and version history. |
| MCP Server | Model Context Protocol for Claude, ChatGPT, Cursor, OpenClaw, Codex, and more. Agents store and retrieve state through structured tool calls. |
| CLI | Command-line for scripting and direct access. Inspect entities, replay timelines, and manage state from the terminal. |
All three map to the same OpenAPI-backed operations. MCP tool calls log the equivalent CLI invocation.
People building a personal operating system with AI agents across their life — wiring together tools like Claude, Cursor, ChatGPT, OpenClaw, and custom scripts to manage contacts, tasks, finances, code, content, and other domains. The same person operates their agents, builds new pipelines, and debugs state drift. These are three operational modes, not separate personas:
| Mode | What you're doing | The tax you pay without Neotoma | What you get back |
|---|---|---|---|
| Operating | Running AI tools across sessions and contexts | Re-prompting, context re-establishment, manual cross-tool sync | Attention, continuity, trust in your tools |
| Building | Shipping agents and pipelines | Prompt workarounds, dedup hacks, memory regression fixes | Product velocity, shipping confidence |
| Debugging | Tracing state drift and reproducing failures | Writing glue (checkpoint logic, custom diffing, state serialization) | Debugging speed, platform design time |
Not for: Casual note-taking. PKM/Obsidian-style users. Thought-partner usage where the human drives every turn. Platform builders who build state management as their core product. Users who need zero-install onboarding (Neotoma requires npm and CLI today).
Neotoma stores typed entities with versioned history and provenance. Each type has a dedicated guide on neotoma.io:
| Type | What it stores | Examples |
|---|---|---|
| Contacts | People, companies, roles, relationships | contact, company, account |
| Tasks | Obligations, deadlines, habits, goals | task, habit, goal |
| Transactions | Payments, receipts, invoices, ledger entries | transaction, invoice, receipt |
| Contracts | Agreements, clauses, amendments | contract, clause, amendment |
| Decisions | Choices, rationale, audit trails | decision, assessment, review |
| Events | Meetings, milestones, outcomes | event, meeting, milestone |
Schema is flexible — store any entity type with whatever fields the message implies. The system infers and evolves schemas automatically.
Version: v0.4.0 · Releases: 12 · License: MIT
- No silent data loss. Operations either succeed and are recorded or fail with explicit errors.
- Explicit, inspectable state mutations. Every change is a named operation with visible inputs. State is reconstructable from the audit trail.
- Auditable operations. Full provenance. CLI and MCP map to the same underlying contract.
- Same contract for CLI and MCP. Both use the same OpenAPI-backed operations.
- Stable schemas
- Deterministic extraction across versions
- Long-term replay compatibility
- Backward compatibility
Breaking changes should be expected. Storage: Local-only (SQLite + local file storage). See Developer preview storage.
Neotoma stores user data and requires secure configuration.
- Authentication: Local auth (dev stub or key-based when encryption is enabled).
- Authorization: Local data isolation and explicit operation-level access controls.
- Data protection: User-controlled data with full export and deletion control. Never used for training. Optional encryption at rest.
- Verify your setup: Run
npm run doctorfor environment, database, and security checks. See Auth, Privacy, Compliance.
Servers:
npm run dev # MCP server (stdio)
npm run dev:ui # Frontend
npm run dev:server # API only (MCP at /mcp)
npm run dev:full # API + UI + build watchCLI:
npm run cli # Run via npm (no global install)
npm run cli:dev # Dev mode (tsx; picks up source changes)
npm run setup:cli # Build and link so `neotoma` is available globallyTesting: npm test | npm run test:integration | npm run test:e2e | npm run test:agent-mcp | npm run type-check | npm run lint · Source checkout:
git clone https://github.com/markmhendrickson/neotoma.git
cd neotoma
npm install
npm testPrerequisites: Node.js v18.x or v20.x (LTS), npm v9+. No .env required for local storage. See Getting started.
Neotoma exposes state via MCP. Local storage only in preview. Local built-in auth.
Setup guides: Cursor · Claude Code · Claude · ChatGPT · Codex · OpenClaw
Agent behavior contract: Store first, retrieve before storing, extract entities from user input, create tasks for commitments. Full instructions: MCP instructions and CLI agent instructions.
Representative actions: store, retrieve_entities, retrieve_entity_snapshot, merge_entities, list_observations, create_relationship, list_relationships, list_timeline_events, retrieve_graph_neighborhood. Full list: MCP spec.
Platform memory (Claude, ChatGPT) is good enough — why add another tool? Platform memory stores what one vendor decides to remember, in a format you can't inspect or export. It doesn't version, doesn't detect conflicts, and vanishes if you switch tools. Neotoma gives you structured, cross-tool state you control.
Can't I just build this with SQLite or a JSON file? You can start there — many teams do. But you'll eventually need versioning, conflict detection, schema evolution, and cross-tool sync. That's months of infrastructure work. Neotoma ships those guarantees on day one.
What's the difference between RAG memory and deterministic memory? RAG stores text chunks and retrieves them by similarity. Neotoma stores structured observations and composes entity state with reducers; the same observations always yield the same snapshot. RAG optimizes relevance; deterministic memory optimizes integrity, versioning, and auditability.
Is this production-ready? Neotoma is in developer preview — used daily by real agent workflows. The core guarantees (deterministic state, versioned history, append-only log) are stable. Install in 5 minutes and let your agent evaluate the fit.
More questions: FAQ
- Neotoma developer release
- Your AI remembers your vibe but not your work
- Building a truth layer for persistent agent memory
- Agent memory has a truth problem
- Six agentic trends I'm betting on (and how I might be wrong)
- Why agent memory needs more than RAG
- Agent command centers need one source of truth
Full documentation is organized at neotoma.io/docs and in the docs/ directory.
Getting started: Evaluate, Install, Walkthrough
Reference: REST API, MCP server, CLI, Memory guarantees, Architecture, Terminology
Foundational: Core identity, Philosophy, Problem statement
Operations: Runbook, Health check (npm run doctor), Troubleshooting
Neotoma is in active development. For questions or collaboration, open an issue or discussion. See CONTRIBUTING.md and SECURITY.md. License: MIT