Neotoma with Claude Code

Claude Code is Anthropic's local CLI agent for development tasks. It runs in your terminal with direct filesystem access. Neotoma adds persistent structured memory that survives across sessions and tools via MCP or CLI fallback.

Looking for Claude's web, mobile, or desktop apps? See Neotoma with Claude.

What Claude Code provides

Local terminal agent with direct filesystem and shell access
Session memory plus auto memory that records corrections and preferences across sessions
MCP server support via .mcp.json at your project root (stdio, SSE, and HTTP transports)
CLAUDE.md project context files for persistent instructions at project, user, or org scope

What Claude Code doesn't handle

Memory that persists across sessions after terminal closes; auto memory stores preferences but not structured entity data
Structured entity resolution or typed data storage
Cross-tool access; session context is local to Claude Code

Deterministic guarantees Neotoma provides

Persistent memory graph accessible across all Claude Code sessions
Deterministic state: same observations always produce the same entity snapshots
Full provenance trail for every stored fact
CLI fallback for direct terminal access when MCP is not configured
Cross-tool continuity: memory shared with Claude, Cursor, Codex, and ChatGPT

Using them together

Keep auto memory and CLAUDE.md on. Auto memory saves build commands, debugging insights, and code style preferences to ~/.claude/projects/<project>/memory/. The first 200 lines of MEMORY.md load into every session. It's machine-local and per-project, so it handles what it's good at; Neotoma handles what it cannot. Both are active simultaneously with no conflict.

Concern	Claude Code	Neotoma
Coding preferences & corrections	Auto memory	-
Project instructions	CLAUDE.md	-
Build commands & debugging notes	Auto memory (MEMORY.md)	-
Structured entities (people, tasks, decisions)	-	Store via MCP
Cross-tool state	-	Shared memory graph
Audit trail & provenance	-	Observation history

Neotoma hooks plugin (optional)

The Neotoma Claude Code plugin runs alongside the MCP server. MCP stays the quality ceiling for agent-driven structured writes; the plugin is the reliability floor: it captures every session, user prompt, tool call, compaction event, and assistant reply, even if the agent forgets to call a tool. It also injects recent Neotoma context on every prompt via additionalContext, so recall works without the agent having to plan for it.

The plugin shares idempotency keys with MCP, so the same logical turn lands on one entity with layered observations, not duplicates.

Getting started

Copy this prompt into Claude Code to have it read the evaluation page, inspect your tool, workspace, and configuration context, then judge whether Neotoma fits your real workflow and what to persist first.

Evaluation prompt

Reads the page, then evaluates fit against your real workflow.

Read https://neotoma.io/evaluate. Use any tool, workspace, and chat context already available in this session to assess my real workflow. Avoid ad-hoc shell introspection just to profile me; if Neotoma is already installed, use `neotoma doctor --json` for status instead. Then tell me whether Neotoma fits my workflow, what data would be highest value to persist first, and what I should do next.

If you are ready to proceed, paste this prompt into Claude Code. The agent handles evaluation, installation if needed, activation, and local MCP configuration.

Code snippet

Copy the exact snippet shown below.

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

This is a local integration. Neotoma runs on the same machine via stdio. No API server or remote access is required. The agent writes to .mcp.json at your project root.

After MCP config is written: exit and restart Claude Code (/exit then claude) so it loads the new MCP server. Claude Code reads .mcp.json at startup.

When MCP is not available, agents can use the neotoma CLI directly from the terminal as a fallback.

After activation, offer additional remote access points only if the user wants Neotoma available outside Claude Code as well.

Claude Code documentation

MCP in Claude Code (connecting external tools via .mcp.json)
Memory in Claude Code (CLAUDE.md files and auto memory)
Auto memory (how Claude learns preferences and patterns across sessions)
Settings (project and user-level configuration)

Before and after: Claude Code with Neotoma

“Continue where we left off yesterday.”

Without Neotoma

Resuming based on thread from two weeks ago.

With Neotoma

Resuming yesterday’s thread on the migration plan. 3 open tasks remaining.

“What did I commit to with Sarah last week?”

Without Neotoma

No commitments found.

With Neotoma

You committed to sending the architecture doc by Friday. Sarah’s email updated Mar 28.

“How much did we spend on cloud hosting last month?”

Without Neotoma

No hosting expenses found.

With Neotoma

$847 across AWS and Vercel, up 12% from February.

After you connect

Once Neotoma is running, try these starter commands in Claude Code to see cross-session memory in action:

Store a contact

“Remember that Sarah Chen's email is sarah@newstartup.io — she's the CTO at NewStartup.”

Store a task

“I need to send the architecture doc to Sarah by Friday.”

Recall across sessions

“What do I know about Sarah? What did I commit to doing for her?”

Start with evaluation, see the install guide for more options, MCP reference for MCP setup, CLI reference for terminal usage, and agent instructions for behavioral details.