What changes on your system

Installation, initialization, and host connection can affect different machines and configuration files.

Source: docs/topics/install/system-changes.md · Read Markdown · 08598d0

Choose the effect you intend

Installing the npm package adds a global CLI binary on the machine where you run it. neotoma init creates local configuration and development and production database profiles. A host setup, native plugin, or SDK adapter may then change that host's configuration or capture later events. Those are separate choices: merely connecting an authenticated remote client does not initialize a local Neotoma record.

Before running a command, choose the connection guide for your host. It distinguishes local stdio, authenticated remote MCP, native plugin, manual configuration, SDK adapter, and registry paths. Review the command and its permissions before running it; a completed setup command does not prove the host can read the intended instance or that optional capture works.

Files and permissions for a local installation

npm install -g neotoma@0.26.0 adds the CLI binary. neotoma init creates a config directory, two local SQLite databases (development and production profiles), and an environment file. By default, init also adds a Neotoma entry to Cursor's MCP configuration. Run neotoma init --interactive to choose each step.

The following inventory describes the local paths and effects exposed by the documented install and Claude Code setup flow. Other hosts use their own guide and can affect different host files. The paths and reset behavior are not a promise that a remote client writes to its own machine.

Created or changed	Path	Scope	`neotoma reset` behavior
Global npm package	Global `node_modules`	Global	`npm uninstall -g neotoma` runs only when reset is called from inside a Neotoma repository.
Config directory	`~/.config/neotoma/`	User	Backed up, then removed.
Environment file	`~/.config/neotoma/.env` or `<project>/.env`	User or project	Backed up, then removed.
SQLite databases, development and production profiles	`<data-dir>/neotoma.db`, `<data-dir>/neotoma.prod.db`	Local	Backed up, then removed.
Data directories for both profiles	`<data-dir>/sources/`, `<data-dir>/logs/` (development); `<data-dir>/sources_prod/`, `<data-dir>/logs_prod/` (production)	Local	Backed up, then removed unless `NEOTOMA_DATA_DIR` protects the configured directory.
Event logs for both profiles	`<data-dir>/logs/events.log` (development), `<data-dir>/logs/events.prod.log` (production) by default; `NEOTOMA_EVENT_LOG_PATH` or `NEOTOMA_EVENT_LOG_DIR` can override the location	Local	Check the resolved path before reset or backup; a protected data directory is not removed.
MCP entries `neotoma-dev` and `neotoma`, with separate databases; init adds one Cursor entry by default	`~/.cursor/mcp.json`, `.mcp.json`, `claude.json`, or selected host configuration	User or project	User-level Neotoma entries are stripped; project .mcp.json entries can remain when reset runs outside a Neotoma repository.
CLI instruction files for Claude Code, Cursor, and Codex	`.cursor/rules/`, `.claude/rules/`, and the Codex equivalent	Project	Can remain when reset runs outside a Neotoma repository; remove manually.
Claude Code plugin with five hooks, when `claude` is on `PATH`	The Claude plugin location	User	Not listed among what reset removes.
Twelve Claude Code skills, when `~/.claude` exists	`~/.claude/skills/`	User	Not listed among what reset removes.
Claude Code allow rules `Bash(neotoma:)` and `Bash(npm install -g neotoma:)`	`.claude/settings.local.json` by default; `~/.claude/settings.json` with `--scope both`	Project or user	Not listed among what reset removes.
Cursor command allowlist `neotoma *` and global npm install	`.cursor/allowlist.json`	Project	Not listed among what reset removes. `neotoma *` permits any Neotoma subcommand, including reset.
Codex command approval `neotoma *` and global npm install	`~/.codex/config.toml`	User	Not listed among what reset removes. `neotoma *` permits any Neotoma subcommand, including reset.

The Claude Code setup example neotoma setup --tool claude-code --yes writes two MCP entries and CLI instruction files for Claude Code, Cursor, and Codex in the project. Its permission step writes the two Claude Code allow rules shown above; Cursor and Codex permission rules are written by their respective selected setup targets. The Claude Bash(neotoma:*) rule can permit any Neotoma command without another host prompt, including destructive commands such as neotoma reset; the Cursor and Codex neotoma * rules have the same broad subcommand reach. Reset itself can proceed without interactive confirmation: outside the production environment, that is its default unless --interactive requests a prompt; a prompt also depends on terminal and output mode. --skip-permissions writes no allow rules. Setup also installs user-level skills when ~/.claude exists and, when claude is on PATH, runs the Claude Code plugin marketplace and install commands. Without claude on PATH, it can exit with code 1 after writing the other changes. Inspect the resulting files and host permissions rather than treating the exit code as a complete effect report.

Capture and network behavior

MCP connection lets the host make agent-driven calls. Hooks, plugins, and SDK adapters are separate capture paths: after activation, they may record later supported events automatically. Check their own configuration and captured-event readback; a successful MCP retrieval does not prove capture, and plugin registration does not prove MCP access.

There is no product telemetry in this documented flow. The interactive CLI checks the npm registry for a newer version about once a day; --no-update-check or NO_UPDATE_NOTIFIER=1 disables that check. The stdio MCP server checks when a session starts and about every six hours afterward; NO_UPDATE_NOTIFIER=1 disables that check, while the CLI flag does not. An agent can separately call npm_check_update, which makes the same registry request and is not disabled by NO_UPDATE_NOTIFIER. The request carries the package name; the registry also sees ordinary connection metadata such as the network address.

Reset and verify

neotoma reset backs up local state to a timestamped directory before removing it. It runs npm uninstall -g neotoma only when run from inside a Neotoma repository; elsewhere it skips the global uninstall. If .env sets NEOTOMA_DATA_DIR, that directory is protected and not removed. Plugin, skill, and allow-rule rows above are not listed among reset removals; inspect and remove them separately if that is your intention.

After local setup, inspect the affected host configuration and run a read-only retrieval of a known entity on the intended instance and profile. An empty successful query proves transport, not that you reached the expected record. Before any data import or permission expansion, review the selected source, scope, and effect. Return to Install options or the relevant connection guide to choose the next step.