<!--
  Full-page Markdown export (rendered HTML → GFM).
  Source: https://neotoma.io/install
  Generated: 2026-05-04T09:49:27.861Z
-->
# 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 →](/evaluate)

## 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:

1.  Confirming the user wants the install-first path and identifying the current tool.
2.  Installing only if needed, then verifying state with `neotoma doctor --json`.
3.  Choosing the first data to store and the onboarding mode.
4.  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](/evaluate).

1.  **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.
2.  **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.
3.  **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.
4.  **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.
5.  **Run activation** - execute [detect context -> discover -> propose -> preview -> ingest -> reconstruct -> query -> correct](https://github.com/markmhendrickson/neotoma/blob/main/install.md): discover candidates, preview them, ingest confirmed sources, reconstruct a timeline, then query and correct.
6.  **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.

Claude CodeCursorCodex

JSON merge into Claude Code's permissions file.

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

Copy

```
// 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](https://github.com/markmhendrickson/neotoma/blob/main/install.md). If the user wants the broader qualification flow first, send them to [/evaluate](/evaluate).

More options: [Manual install](/install/manual) · [Docker](/install/docker) · [CLI reference](/cli)

* * *

## 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 remotely](/connect) or try the [public sandbox](/sandbox).

-   [
    
    Claude CodePersistent memory for Claude Code's local CLI agent
    
    
    
    
    
    
    
    ](/neotoma-with-claude-code)
-   [
    
    ClaudeStructured state alongside Claude platform memory
    
    
    
    
    
    
    
    ](/neotoma-with-claude)
-   [
    
    ChatGPTDeterministic memory for ChatGPT conversations
    
    
    
    
    
    
    
    ](/neotoma-with-chatgpt)
-   [
    
    CodexCross-task memory and CLI fallback
    
    
    
    
    
    
    
    ](/neotoma-with-codex)
-   [
    
    OpenCodeLifecycle hooks and MCP memory for OpenCode
    
    
    
    
    
    
    
    ](/neotoma-with-opencode)
-   [
    
    CursorPersistent memory alongside Cursor context
    
    
    
    
    
    
    
    ](/neotoma-with-cursor)
-   [
    
    OpenClawUser-owned memory for OpenClaw agents
    
    
    
    
    
    
    
    ](/neotoma-with-openclaw)
-   [
    
    IronClawStructured MCP memory for IronClaw agents
    
    
    
    
    
    
    
    ](/neotoma-with-ironclaw)

◆

## Manual install and Docker

[Manual install

npm install, post-install verification, start the API server, and connect MCP.

](/install/manual)[Docker install

Run Neotoma in Docker with docker-compose or standalone containers.

](/install/docker)

[CLI reference →](/cli)[Full README →](https://github.com/markmhendrickson/neotoma?tab=readme-ov-file#install)