markmhendrickson/neotoma

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

Why this exists

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.

What Neotoma does

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.

Architecture

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.

Three foundations

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.

State guarantees

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

Quick start

Evaluate first (recommended)

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. Use any tool, workspace, and chat context already available in this session to assess my real workflow. Avoid ad-hoc shell introspection just to profile me; if Neotoma is already installed, use `neotoma doctor --json` for status instead. 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.

Agent-driven install

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. Use `neotoma` commands for status and setup. If Neotoma is already installed, start with `neotoma doctor --json`; otherwise install it and run `neotoma setup --tool <my_tool> --yes`. Avoid ad-hoc shell introspection or arbitrary repo scripts. Then activate Neotoma 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 config

More options: Docker | CLI reference | Getting started

Example

neotoma store --json='[{"entity_type":"task","title":"Submit expense report","status":"open"}]'
neotoma entities list --type task
neotoma upload ./invoice.pdf

Results reflect versioned entity state with full provenance. Agents perform the same operations through MCP tool calls (store, retrieve_entities, retrieve_entity_by_identifier).

Interfaces

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.

Who this is for

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

Record types

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.

Current status

Version: v0.4.2 · Releases: 13 · License: MIT

What is guaranteed (even in preview)

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

What is not guaranteed yet

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

Security defaults

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 doctor for environment, database, and security checks. See Auth, Privacy, Compliance.

Development

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 watch

CLI:

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 globally

Testing: 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 test

Prerequisites: Node.js v18.x or v20.x (LTS), npm v9+. No .env required for local storage. See Getting started.

Using with AI tools (MCP)

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.

Using with AI tools (hooks)

Neotoma also integrates into harnesses that expose lifecycle hooks. Hooks and MCP compose: hooks are the reliability floor (guaranteed capture, retrieval injection, compaction awareness, persistence safety net) and MCP remains the quality ceiling (agent-driven structured writes).

Harness	Package	Guide
Claude Code	packages/claude-code-plugin	docs/integrations/hooks/claude_code.md
Cursor	packages/cursor-hooks	docs/integrations/hooks/cursor.md
OpenCode	packages/opencode-plugin	docs/integrations/hooks/opencode.md
Codex CLI	packages/codex-hooks	docs/integrations/hooks/codex_cli.md
Claude Agent SDK	packages/claude-agent-sdk-adapter	docs/integrations/hooks/claude_agent_sdk.md

Shared client libraries: @neotoma/client (TypeScript), neotoma-client (Python).

OpenClaw native plugin

Neotoma ships as a native OpenClaw plugin with kind: "memory", so it can fill the dedicated memory slot. All 30+ MCP tools are registered as agent tools.

openclaw plugins install clawhub:neotoma

Then assign it to the memory slot in your OpenClaw config:

{
  plugins: {
    slots: { memory: "neotoma" },
    entries: {
      neotoma: {
        enabled: true,
        config: {
          dataDir: "~/.local/share/neotoma",
          environment: "production"
        }
      }
    }
  }
}

Verify installation: openclaw plugins inspect neotoma shows Format: native, Kind: memory, and all registered tool contracts.

Common questions

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

Related posts

• 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

Documentation

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), SQLite salvage (neotoma storage recover-db, npm run recover:db, npm run recover:db:prod), Troubleshooting

Contributing

Neotoma is in active development. For questions or collaboration, open an issue or discussion. See CONTRIBUTING.md and SECURITY.md. License: MIT