Install options

5-minute integrationFully reversible

Want the full agent-driven sequence? Start with evaluation, then let the agent install if needed, activate Neotoma with your data, and configure the tool you are in.

Start with evaluation →

Agent-assisted install

If you want to skip the initial evaluation page and proceed directly from install, paste this prompt into Claude, Codex, Cursor, or a similar agent. The prompt stays intentionally short; this page documents the full install-first sequence it should follow.

Agent prompt

Paste this into an assistant to run the install-first Neotoma flow.

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 page expands the prompt. The copied prompt omits detail for readability; the full install-first flow here includes:

Confirming the user wants the install-first path and identifying the current tool.
Installing only if needed, then verifying state with neotoma doctor --json.
Choosing the first data to store and the onboarding mode.
Running activation, then configuring the current tool for ongoing use.

Expanded install-first sequence

Use this path only when the user already wants to proceed with Neotoma and does not need the broader fit-assessment flow on /evaluate.

Confirm the install-first path - verify that the user wants to proceed now, identify their current tool, and note any major tool constraints that affect setup quality.
Install only if needed - check whether Neotoma is already installed. If not, branch by tool: for OpenClaw, prefer openclaw plugins install clawhub:neotoma; for other local tools, run npm install -g neotoma. Then collapse the rest of setup into two calls: neotoma doctor --json to inspect consolidated state and neotoma setup --tool <tool> --yes to apply init + MCP + CLI instructions + permission files idempotently. If Neotoma is already installed, just run neotoma doctor --json to verify.
Do not improvise shell introspection. Do not run python3 -c, grep -r, ls, cat, jq, find, which, or node -e to introspect Neotoma, and do not run arbitrary npm run scripts from the user's repositories. If a permission prompt appears for anything other than neotoma * or npm install -g neotoma, stop and ask the user to widen the allowlist (see the Permissions pre-flight block above) rather than substituting another command.
Set the first data target - determine what data should be stored first and, if needed, ask the user which onboarding mode they want: quick win, guided, or power user.
Run activation - execute discover -> propose -> preview -> ingest -> reconstruct -> query -> correct: discover candidates, preview them, ingest confirmed sources, reconstruct a timeline, then query and correct.
Configure the current tool - after first value is visible, set up the strongest ongoing Neotoma workflow for the tool in use. For OpenClaw, keep the native plugin path as the default and use manual MCP wiring only as fallback. If that tool is too constrained, say so explicitly and recommend a better-supported primary environment.

If your agent requires command allowlists, use the pre-flight snippets before running the prompt.

Permissions pre-flight (copy once, before running the agent prompt below)

Paste this snippet into the right file for your agent harness so the rest of onboarding only needs two approvals: neotoma * and one npm install -g neotoma. Without this, directory-scoped harnesses will prompt for every individual command.

Using OpenClaw? Skip this — the native plugin handles consent. Just run openclaw plugins install clawhub:neotoma and approve the plugin permission prompt once.

JSON merge into Claude Code's permissions file.

Target: .claude/settings.local.json (project) — or ~/.claude/settings.json (user)

// Paste into .claude/settings.local.json (project) or ~/.claude/settings.json (user).
// Merge with any existing "permissions.allow" list.
{
  "permissions": {
    "allow": [
      "Bash(neotoma:*)",
      "Bash(npm install -g neotoma:*)"
    ]
  }
}

Canonical written reference: install.md. If the user wants the broader qualification flow first, send them to /evaluate.

More options: Manual install · Docker · CLI reference

What changes on your system

npm install -g neotoma adds a CLI binary. neotoma init creates a config directory, a local SQLite database, and an env file. Optional prompts during init can add MCP config entries and CLI instruction files; you choose at each step. Nothing runs in the background unless you start it. No telemetry, no phone-home.

Created	Path	Scope	`neotoma reset`
Global npm package	neotoma (global node_modules)	Global	npm uninstall -g neotoma
Config directory	~/.config/neotoma/	User	Backed up, then removed
Environment file	~/.config/neotoma/.env or <project>/.env	User / Project	Backed up, then removed
SQLite databases	<data-dir>/neotoma.db, neotoma.prod.db	Local	Backed up, then removed
Data directories	<data-dir>/sources/, <data-dir>/logs/	Local	Backed up, then removed
MCP config entries (optional)	.cursor/mcp.json, claude.json, etc.	User / Project	Entries stripped from configs
CLI instruction rules (optional)	.cursor/rules/, .claude/rules/	User / Project	Backed up, then removed

neotoma reset backs up every item to a timestamped directory before removing it, then runs npm uninstall -g neotoma. If your .env sets NEOTOMA_DATA_DIR, that directory is protected and not removed.

Direct integration docs

Connecting an agent to a hosted Neotoma instead of installing locally? Hosted Neotoma instances expose harness-specific connect snippets at their own root URL (with the host pre-filled) - see Connect a remote Neotoma or try the public sandbox.

Manual install

If you prefer to run the commands yourself:

Manual install

Run these commands yourself on the host machine.

# 1. Install globally (required for agent harnesses — avoids per-repo PATH prompts)
npm install -g neotoma

# 2. Inspect state in one call (no shell introspection needed)
neotoma doctor --json

# 3. Run the full idempotent setup for the current harness
neotoma setup --tool claude-code --yes   # or: --tool cursor | --tool codex | --tool openclaw

After installation

Once installation is complete, activation follows. If evaluation already identified the first data to store, carry that forward. Otherwise determine it now, then run discover -> propose -> preview -> ingest -> reconstruct -> query -> correct. After first value is visible, configure the current tool for robust ongoing usage.

Troubleshooting: which neotoma fails after install? Your shell manager (mise, nvm, fnm) is probably not active in the agent's non-interactive shell. Run neotoma doctor --json and read .neotoma.path_fix_hint for the exact activation line. Common fixes to add to ~/.zshenv or ~/.zshrc:

mise:  eval "$(mise activate zsh)"
nvm:   source "$NVM_DIR/nvm.sh"   # in ~/.zshenv for non-interactive shells
fnm:   eval "$(fnm env)"

Preference selection - if evaluation already established the priority data types and onboarding mode, carry them forward. Otherwise choose which data types matter most (project files, chat transcripts, meeting notes, financial docs, code context, custom paths) and pick a mode: quick win, guided, or power user.
Discovery - continue from any candidate data already identified during evaluation. If that work has not happened yet, the agent scans shallowly based on your preferences, groups results into domains (not file counts), and checks for chat transcript exports and platform memory.
Propose and confirm - for each domain the agent explains why it was selected, what entities it likely contains, and what timeline value it could unlock. You confirm per-folder or per-file before anything is stored.
Ingest and reconstruct - confirmed files are ingested and the agent reconstructs the strongest timeline with provenance - every event traced to a specific source file.
Query and correct - the agent surfaces a follow-up query against the reconstructed timeline and offers next actions, then asks whether the timeline is accurate and supports corrections (wrong merge, wrong date, source exclusion).

Try it now

Once Neotoma is running, try these prompts in any connected tool to see it working:

Store a contact

“Remember that Sarah Chen's email is sarah@newstartup.io. She started there in March.”

Then in a different session or tool: “What's Sarah Chen's email?”

Track a commitment

“I told Nick I'd send the architecture doc by Friday.”

Later: “What did I commit to this week?”

Test a correction

“Actually, Sarah's email changed to sarah@acme.co.”

Then: “What's Sarah's email? Show me the history.” Both old and new are preserved with timestamps.

Start the API server

The API server provides the HTTP interface that MCP and the CLI communicate through.

Start API

Bring up the local API so MCP and CLI can connect.

# Run API server (development)
neotoma api start --env dev

# Run API server (production)
neotoma api start --env production

Connect MCP

Add Neotoma to your MCP client configuration (Cursor, Claude, or Codex):

MCP config

Add this client config to connect Neotoma over stdio.

{
  "mcpServers": {
    "neotoma-dev": {
      "command": "/absolute/path/to/neotoma/scripts/run_neotoma_mcp_stdio.sh"
    },
    "neotoma": {
      "command": "/absolute/path/to/neotoma/scripts/run_neotoma_mcp_stdio_prod.sh"
    }
  }
}

After adding MCP config: restart your AI tool (Claude Code, Cursor, Claude Desktop, etc.) so it picks up the new server. MCP servers are loaded at startup.

Docker

If you want your assistant to handle Docker setup, use a prompt like this:

Docker prompt

Use this when you want an assistant to handle the Docker path.

Follow the instructions at:
https://github.com/markmhendrickson/neotoma/blob/main/docs/developer/agent_docker_instructions.md

CLI reference →Full README →