neotoma

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

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. 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 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](https://neotoma.io/types

---

README truncated. View full README on GitHub.