neotoma / site_pages

# Neotoma

> The system of record for AI agents

## What it does

A record, not recall. Without one, an agent works from whatever it happens to recall: part of the last session, a note its tool saved, or nothing. With one, it reads what was stored, from which source, and what is current now, so the agents you connect can defer to one answer.

Neotoma is open source and local-first. It stores each fact as an observation (a stored observation names its source; a correction has none), resolves observations into entities, and computes a current snapshot for each entity with a reducer. A correction is recorded as a new observation, and the earlier observations stay readable for that entity. Each current field names the observation that set it.

## Key facts

- Open-source, MIT-licensed
- Installs via npm: `npm install -g neotoma`, then `neotoma init`
- Interfaces: MCP server, REST API, CLI, and a bundled web Inspector
- Platforms: macOS and Linux; Windows is untested
- Documented integrations: Cursor, Claude Code, Claude Desktop, ChatGPT, Codex, OpenClaw, IronClaw, Windsurf, Continue, VS Code, Letta (see the integrations matrix under Links)
- Local-first: data lives in a directory you control (embedded SQLite plus content-addressed files). No telemetry. The interactive CLI checks the npm registry for a newer version about once a day (off with `--no-update-check` or `NO_UPDATE_NOTIFIER=1`). The stdio MCP server checks when a session starts and about every 6 hours after (off with `NO_UPDATE_NOTIFIER=1`; `--no-update-check` applies to the CLI only). The request carries only the package name, and the registry sees ordinary connection metadata such as the address. Agents can also call the `npm_check_update` MCP tool, which can make the same registry request and is not turned off by `NO_UPDATE_NOTIFIER`.
- Written in TypeScript

## What it provides

- Snapshots: the current state of an entity is computed by a reducer from its observations
- Provenance: each current field names the observation that set it, and a stored observation names its source
- Corrections as observations: a correction adds a new observation and does not overwrite the earlier one
- Entity resolution: entity IDs are hashes derived from the identity fields of the entity type
- A committed, keyed structured store started on v0.26.0 that stops partway finishes its missing observations on a same-key retry; a store carrying an interpretation returns `ERR_STORE_WRITE_INCOMPLETE`, and keys left over from earlier versions behave differently over MCP and HTTP (see Known limitations)

## Limits

- A record is a workflow commitment: agents must write to it and read from it, and it needs a local service and deliberate writes
- Provenance shows the evidence trail, not that an agent read a source correctly
- Export writes current state; observation history is not part of the export
- A snapshot can be read as of a past time for one entity (`at` and `at_ingested` on `retrieve_entity_snapshot`); there is no as-of query across the whole record
- Organizations, workspaces, and multi-party authority are not built
- It is not a vector store or a chat log
- Known limitations, each with what you will observe and its tracking issue: https://github.com/markmhendrickson/neotoma/blob/main/docs/known_limitations.md

## Key concepts

- Entity: canonical representation of a person, company, task, or object with a deterministic ID
- Observation: a timestamped fact about an entity; a stored observation is linked to its source, a correction is not
- Snapshot: the current state of an entity, computed from its observations by a reducer
- Reducer: the function that turns an entity's observations into a snapshot
- Provenance: the link from each snapshot field to the observation that set it, and from a stored observation to its source

## How it compares

- Memory and retrieval tools (platform memory, Mem0, Zep) answer what an agent remembers. A record answers what is true now, what it was before, and on whose evidence. The two overlap, and a product can cover more than one.
- File-based notes (Markdown, JSON) hold content. Neotoma adds typed entities, a reducer that computes the current value, and field-level provenance.
- RAG retrieves documents to augment a prompt. Neotoma maintains entity state; it is not a document retrieval system.

## Links

- Website: https://neotoma.io
- Install guide: https://neotoma.io/install
- GitHub: https://github.com/markmhendrickson/neotoma
- Documentation: https://github.com/markmhendrickson/neotoma/tree/main/docs
- Architecture: https://github.com/markmhendrickson/neotoma/blob/main/docs/architecture/architecture.md
- Integrations: https://github.com/markmhendrickson/neotoma/blob/main/docs/integrations/matrix.md
- Releases: https://github.com/markmhendrickson/neotoma/releases
- npm: https://www.npmjs.com/package/neotoma