What to store
Neotoma stores any structured fact that benefits from deterministic state evolution, versioning, and provenance. The deciding question is not “is this personal data?” but does this fact benefit from being versioned, auditable, and reproducible?
If an agent or user would later need to recall a fact, verify when it changed, trace why a decision was made, or reconstruct state at a point in time: it belongs in Neotoma.
Agents store for you
You do not need to decide what to store or call any APIs yourself. When Neotoma runs with an agent in Cursor, Claude, ChatGPT, or any MCP-compatible client, the agent proactively extracts and stores entities from every conversation turn: people mentioned, tasks committed to, decisions made, and facts stated.
The agent follows store recipes that define how to persist conversations, extract entities from attachments, link related records, and preserve provenance without manual intervention. It applies the decision heuristic below on your behalf: if a fact has recall, audit, or relationship value, the agent stores it automatically.
You can always store data manually via the CLI, REST API, or MCP tools, correct what was stored, or tell your agent to stop storing specific categories. The default is proactive storage with human oversight, not the other way around.
Any entity type, any shape
Neotoma does not require you to define a schema before storing data. Store any entity with a descriptive entity_type and whatever fields the data implies. The schema registry infers and evolves schemas automatically as new fields appear.
Common types like contact, task, transaction, and event ship with sensible defaults, but you can create any type by storing an entity with a new entity_type. Fields added later trigger additive schema evolution, minor version bumps that never break existing data.
Unknown fields are preserved in a raw_fragments layer so nothing is silently dropped. As schemas mature, those fragments are promoted into the validated schema automatically. See schemas overview, merge policies, and storage layers for the full picture.
Tier 1 - High-value facts
Store these proactively from the first session.
| Category | Examples |
|---|---|
| People and relationships | Contacts, companies, organizations, role connections |
| Commitments and tasks | Obligations, action items, deadlines, promises made |
| Events and decisions | Meetings, milestones, choices with rationale |
| Financial facts | Transactions, invoices, receipts, contracts, payments owed |
Tier 2 - Contextual facts
Store when encountered in conversation, documents, or external tools.
| Category | Examples |
|---|---|
| Preferences and standards | User preferences, conventions, style guides, stated constraints |
| Project context | Codebase entities, architectural decisions, release metadata, config |
| Documents and artifacts | Uploaded files with extracted structure, reports, specifications |
Tier 3 - Derived context
Store when the derived record carries future recall, audit, or relationship value.
| Category | Examples |
|---|---|
| Conversations | Agent interactions with provenance (persisted per-turn) |
| Session state | Active environment, running tools, current working context |
| External data | Records pulled from email, calendar, web, APIs, other MCPs |
Before-and-after examples
Contacts from a conversation
Before: You mention “Clayton from Acme” in a chat. Next session, the agent has no idea who Clayton is.
After: Agent stores a contact entity with name, company, and a REFERS_TO link to the conversation. Next session, Clayton’s full context is retrieved instantly.
Task from a commitment
Before: “I need to follow up with Sarah by Friday.” The commitment exists only in that session.
After: Agent stores a task entity with title, due date, and REFERS_TO Sarah’s contact. Task persists across sessions and tools.
Decision with rationale
Before: You decide on PostgreSQL over MySQL. Three weeks later, no one remembers why.
After: Agent stores a decision_note with rationale and context. The reasoning is versioned and traceable.
Decision heuristic
When deciding whether to store something, apply this test. If any answer is yes, store it.
- Recallability: Would an agent or user need this fact again in a future session?
- Auditability: Would someone need to know when this was recorded or how it changed?
- Reproducibility: Would reconstructing past state require this fact?
- Relationship value: Does this connect to other entities (people, tasks, events)?
What NOT to store
| Category | Examples |
|---|---|
| Ephemeral output | No future recall value; no benefit from versioning |
| Duplicate records | Already in Neotoma; check before storing |
| Inferred or predicted data | Neotoma stores facts, not guesses |
| Unapproved data | Explicit user control required |
| Credentials and secrets | Belong in secret managers, not state layers |
Ready to start? Install Neotoma, then follow the walkthrough to see storage in action. See backup and restore to protect your data.