convez.ai
MCP Server
markmhendrickson

neotoma

markmhendrickson/neotoma

Ver no GitHub
BomPluginScore · de 0 a 100

Your agents forget. Neotoma makes them remember.

Instalação

$npx convez-ai markmhendrickson/neotoma

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
38
Forks
4
Acompanhando
0
Saúde
85%
Último commit
há 1 dia
Versão
v0.29.1
Issues abertas
738
Contribuidores
7

README

A tradução para o português deste README ainda está na fila.

Neotoma

Your agents forget. Neotoma makes them remember.

Versioned records — contacts, tasks, decisions, finances — that persist across Claude, Cursor, ChatGPT, Windsurf, VS Code, Continue, Letta, OpenClaw, IronClaw, 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.

The Inspector — Neotoma's visual control plane for browsing the entity graph, timeline, schema editor, and agent attribution — is bundled and served at /inspector by default when the server starts. No separate build or configuration required. Override with NEOTOMA_INSPECTOR_DISABLE, NEOTOMA_PUBLIC_INSPECTOR_URL, NEOTOMA_INSPECTOR_STATIC_DIR, or NEOTOMA_INSPECTOR_BASE_PATH (see .env.example).

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

Four foundations

FoundationWhat it means
Privacy-firstYour data stays local. Never used for training. Nothing is stored unless you approve it; no background scanning or implicit captures. Full export and deletion control.
DeterministicSame input always produces same output. Schema-first extraction, hash-based entity IDs, full provenance. No silent mutation.
Immutable and verifiableAppend-only observations; history cannot be rewritten. Hash-based entity IDs are tamper-evident. Full provenance chain from any state to its source.
Cross-platformOne memory graph across Claude, ChatGPT, Cursor, Windsurf, VS Code, Continue, Letta, OpenClaw, IronClaw, Codex, and CLI. MCP-based access. No platform lock-in. Works alongside native memory.

Full compatibility matrix: Integrations.

State guarantees

Most AI memory systems optimize storage or retrieval. Neotoma enforces state integrity. Full comparison with explanations →

PropertyPlatformRetrieval / RAGFilesDatabaseNeotoma
Deterministic state evolution✗✗✗✗✓
Versioned history✗✗⚠ manual✗✓
Replayable timeline✗✗✗✗✓
Auditable change log✗✗⚠ partial✗✓
Schema constraints✗✗✗⚠ partial✓
Silent mutation risk⚠ common⚠ common⚠ common⚠ commonprevented
Conflicting facts risk⚠ common⚠ common⚠ possible⚠ commonprevented
Reproducible state reconstruction✗✗✗✗✓
Human inspectability (diffs/lineage)⚠ partial⚠ partial⚠ partial⚠ partial✓
Zero-setup onboarding✓✗✗✗✗
Semantic similarity search✗✓✗✗✓
Direct human editability✗✗✓✗✗
Strong consistency✗✗✗✓✓
Transactional writes✗✗✗✓✓

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 and tell me whether Neotoma fits my workflow.

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 status --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 setup --tool <cursor|claude-code|codex> --yes
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).

Available skills

Skills are guided workflows that teach your AI agent to import, extract, and persist data into Neotoma memory. They ship with the npm package and are installed by neotoma setup.

SkillDescription
ensure-neotomaInstall Neotoma, configure MCP, verify connectivity. Prerequisite for all other skills.
remember-emailConfigure email MCP, import emails, extract contacts, tasks, events, transactions.
remember-conversationsImport ChatGPT/Claude/Slack exports, reconstruct decision timeline.
remember-meetingsIngest meeting transcripts, extract decisions and action items.
remember-financesImport bank statements, receipts, invoices. Extract structured transactions.
remember-contactsConsolidate contacts from email, calendar, chat, vCards, LinkedIn.
remember-calendarConfigure calendar MCP, import events and commitments.
remember-codebaseDeveloper repo integration — inventory, architecture decisions, MCP wiring.
store-dataGeneric: persist any structured data or file with provenance.
query-memoryGeneric: retrieve what your agent knows about anything.
recover-sqlite-databaseTroubleshooting: check integrity and recover corrupted Neotoma database.

Full skill documentation → | Skill strategy →

Interfaces

Three interfaces. One state invariant. Every interface provides the same deterministic behavior regardless of how you access the state layer.

InterfaceDescription
REST APIFull HTTP interface for application integration. Entities, relationships, observations, schema, timeline, and version history.
MCP ServerModel Context Protocol for Claude, ChatGPT, Cursor, Windsurf, VS Code, Continue, Letta, OpenClaw, IronClaw, Codex, and more. Agents store and retrieve state through structured tool calls.
CLICommand-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, Windsurf, VS Code, Letta, OpenClaw, IronClaw, 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:

ModeWhat you're doingThe tax you pay without NeotomaWhat you get back
OperatingRunning AI tools across sessions and contextsRe-prompting, context re-establishment, manual cross-tool syncAttention, continuity, trust in your tools
BuildingShipping agents and pipelinesPrompt workarounds, dedup hacks, memory regression fixesProduct velocity, shipping confidence
DebuggingTracing state drift and reproducing failuresWriting 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:

TypeWhat it storesExamples
ContactsPeople, companies, roles, relationshipscontact, company, account
TasksObligations, deadlines, habits, goalstask, habit, goal
TransactionsPayments, receipts, invoices, ledger entriestransaction, invoice, receipt
ContractsAgreements, clauses, amendmentscontract, clause, amendment
DecisionsChoices, rationale, audit trailsdecision, assessment, review
EventsMeetings, milestones, outcomesevent, 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.9.1 · Releases: 26 · 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 at-rest encryption: AES-256-GCM column encryption of the sensitive content/metadata columns when enabled with a key file or mnemonic (some tables, e.g. the event log and embeddings, are not yet column-encrypted — pair with an encrypted volume for full coverage). See architecture § 7.2.
  • 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:mcp:dev-shim  # stable stdio shim for MCP source iteration
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.

Full compatibility matrix: Integrations · neotoma.io/integrations

HostModesInstallSetup guide
CursorMCP + hooksneotoma setup --tool cursor --yesneotoma-with-cursor
Claude CodeMCP + hooksneotoma setup --tool claude-code --yesneotoma-with-claude-code
Claude DesktopMCP (local + remote)neotoma setup --tool claude-desktop --yesneotoma-with-claude
Claude Agent SDKhooksadapter installhooks/claude_agent_sdk.md
ChatGPTMCP App + Custom GPT ActionsManual HTTPS + OAuthneotoma-with-chatgpt
Codex CLIMCP + hooksneotoma setup --tool codex --yesneotoma-with-codex
OpenClawNative plugin + MCPneotoma setup --tool openclaw --yesneotoma-with-openclaw
IronClawMCPneotoma setup --tool ironclaw --yesneotoma-with-ironclaw
OpenCodehooksplugin installhooks/opencode.md
WindsurfMCPneotoma setup --tool windsurf --yesneotoma-with-windsurf
ContinueMCPneotoma setup --tool continue --yesneotoma-with-continue
VS Code (Copilot Chat)MCPneotoma setup --tool vscode --yesneotoma-with-vscode
LettaMCP (streamable HTTP, SSE, stdio)Manual SDK setupneotoma-with-letta

Shared client libraries: @neotoma/client (TypeScript), neotoma-client (Python). Not yet supported: LangGraph, CrewAI — see Integrations roadmap.

For local source iteration, use the stable dev shim (scripts/run_neotoma_mcp_stdio_dev_shim.sh) or signed shim (scripts/run_neotoma_mcp_signed_stdio_dev_shim.sh) instead of pointing installed MCP clients at a tsx watch stdio process. neotoma mcp config defaults to b for low-friction local stdio setup; use a for signed + AAuth HTTP /mcp proxy entries when the Neotoma API is running, c for direct stdio, or d when both MCP entries should target prod.

Agent behavior contract: Store first, retrieve before storing, extract entities from user input, create tasks for commitments, and attach bounded host context such as repository name/root scope when available. 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.

Hooks composition

Hooks integrate with harnesses that expose lifecycle events. 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). Per-harness hooks packages: claude-code-plugin, cursor-hooks, opencode-plugin, codex-hooks, claude-agent-sdk-adapter. Per-harness setup guides in docs/integrations/hooks/.

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

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

Ver o original no GitHub

Relacionados