<!-- Full-page Markdown export (rendered HTML → GFM). Source: https://neotoma.io/bn/neotoma-with-claude-code Generated: 2026-04-26T19:09:52.560Z --> # 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](/neotoma-with-claude). ## What Claude Code provides - →Local terminal agent with direct filesystem and shell access - →Session memory plus [auto memory](https://code.claude.com/docs/en/memory#auto-memory) that records corrections and preferences across sessions - →[MCP server support](https://code.claude.com/docs/en/mcp) via `.mcp.json` at your project root (stdio, SSE, and HTTP transports) - →[CLAUDE.md](https://code.claude.com/docs/en/memory#claudemd-files) 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](https://code.claude.com/docs/en/memory#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](https://github.com/markmhendrickson/neotoma/tree/main/packages/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](/evaluate), 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. Copy ``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.``Copy prompt 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](https://code.claude.com/docs/en/mcp) (connecting external tools via .mcp.json) - →[Memory in Claude Code](https://code.claude.com/docs/en/memory) (CLAUDE.md files and auto memory) - →[Auto memory](https://code.claude.com/docs/en/memory#auto-memory) (how Claude learns preferences and patterns across sessions) - →[Settings](https://code.claude.com/docs/en/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](/evaluate), see the [install guide](/install) for more options, [MCP reference](/mcp) for MCP setup, [CLI reference](/cli) for terminal usage, and [agent instructions](/agent-instructions) for behavioral details.