Documentation
All Neotoma documentation organized by category. Start with getting started if you are new, or jump to the reference section for API, MCP, and CLI details.
Getting started
- EvaluateHave your agent read this page to decide whether Neotoma fits your workflow
- InstallInstall and initialize Neotoma locally
- What to store firstPick the first durable facts, commitments, and source-backed records to persist
- Backup and restoreProtect the SQLite database, source files, and reconstruction history
- Expose tunnelUse HTTPS tunnels when remote MCP clients cannot launch local stdio
- WalkthroughEnd-to-end example across operating, building, and debugging
Integrations
- ChatGPTDeterministic memory for ChatGPT conversations
- ClaudeStructured state alongside Claude platform memory
- Claude CodePersistent memory for Claude Code's local CLI agent
- CodexCross-task memory and CLI fallback
- CursorPersistent memory alongside Cursor context
- IronClawStructured MCP memory for IronClaw agents
- OpenClawUser-owned memory for OpenClaw agents
- OpenCodeLifecycle hooks and MCP memory for OpenCode
Reference
- InstallInstall and initialize Neotoma locally
- REST APIOpenAPI endpoints and parameters
- MCP serverModel Context Protocol actions
- CLICommands, flags, and REPL
- Memory guaranteesAll memory properties on one page
- Memory modelsPlatform, retrieval, file-based, and deterministic memory compared
- FoundationsPrivacy-first architecture and cross-platform design
- Agent instructionsMandatory behavioral rules for agents using Neotoma
- ArchitectureState flow, guarantees, and principles
- TerminologyGlossary of key concepts
- TroubleshootingCommon failure modes and practical fixes
- ChangelogRelease history and documentation updates
- All pages (Markdown)Every indexable route as Markdown (SEO summaries)
Primitive record types
- OverviewThe seven system-level building blocks behind every entity, snapshot, and audit trail
- EntitiesCanonical row for every person, company, or thing, deterministic ID, aliases, and merge tracking
- Entity snapshotsReducer output with per-field provenance back to observations and an optional embedding column
- SourcesContent-addressed raw storage with SHA-256 deduplication per user
- InterpretationsVersioned, audited extraction attempts with full interpretation_config provenance
- ObservationsGranular, immutable facts that the reducer composes into entity snapshots
- RelationshipsFirst-class typed graph edges that follow the same observation-snapshot pattern
- Timeline eventsSource-anchored temporal records derived deterministically from extracted dates
Schemas
- OverviewVersioned, config-driven definitions that give the immutable primitives their domain shape
- Schema registryThe table that holds every versioned schema_definition + reducer_config, global or per-user
- Merge policiesPer-field declarative rules, last_write, highest_priority, most_specific, merge_array
- Storage layersraw_text, properties, and raw_fragments, the three places extracted data can land
- Versioning & evolutionSemver, additive minor bumps, breaking major bumps, and the public schema snapshots dump
- Schema management (CLI)CLI workflows for listing, validating, evolving, and registering schemas at runtime
Where the tax shows up
Compare
- Build vs buyWhen to adopt a state-integrity layer instead of building around observability alone
- Neotoma vs platform memoryConvenience inside one AI product versus portable, auditable state across tools
- Neotoma vs Mem0Retrieval memory for prompt augmentation versus deterministic entity state
- Neotoma vs ZepKnowledge-graph retrieval versus versioned, schema-bound state
- Neotoma vs RAGRelevant chunk retrieval versus exact state reconstruction
- Neotoma vs file-based memoryMarkdown and JSON portability versus structured guarantees and provenance
- Neotoma vs database memoryCRUD rows versus append-only observations and deterministic reducers