Coppermind

Memory runtime for AI agents.

Most users should install coppermind.

Install once. Keep memory local by default. Add cloud features only when you want them.

Quick Start

npm install -g coppermind
coppermind setup
coppermind daemon start
coppermind doctor --check
coppermind mcp codex install
coppermind codex hooks install
coppermind mcp claude install
coppermind mcp antigravity install

That is the default product path. The managed client installers also install the Coppermind memory skill/instruction surface into the client-specific location:

• Codex: ~/.codex/skills/coppermind-memory-saver/SKILL.md
• Claude Code: ~/.claude/agents/coppermind-memory-saver.md
• Antigravity: inferred community path ~/.gemini/antigravity/skills/coppermind-memory-saver/SKILL.md

What is this?

Coppermind is a local-first runtime for AI agents. It runs on your machine, manages local memory for you, and exposes the operational surface your integrations talk to.

If you are choosing between packages, see Which Package Should I Install?.

• Local-first runtime — memory works without a cloud prerequisite
• Runtime-managed local memory engine — SurrealDB embedded store hidden behind Coppermind
• Hermes patcher + MCP installers — official local-first integration surfaces today
• CLI-first — coppermind setup, coppermind run, coppermind doctor

Requirements

• Node.js >= 20
• macOS or Linux

Setup

coppermind setup

This creates ~/.coppermind/ with default runtime configuration.

On supported platforms, setup also silently provisions Coppermind's managed local SurrealDB store under ~/.coppermind/surreal/. You do not need to install or operate SurrealDB yourself.

The generated config.yaml now includes explicit defaults:

sync_enabled: false
local_ai_enabled: false
theme_mode: mistborn
theme_language: off

You can still edit the file directly, but the preferred user-facing controls are:

coppermind local-ai on
coppermind theme on

Optional local AI assist is separate from the baseline runtime path. It stays default-off, lazy-bootstraps only when explicitly enabled, and never blocks first-run local success. When enabled, Coppermind manages the pinned LiquidAI/LFM2.5-1.2B-Instruct bundle and keeps a persistent local inference worker warm in the background. Episode triage is handled by the ONNX triage classifier, with the LLM as fallback.

If you later upgrade from the local-first path to Pro or higher, you can bootstrap the optional dashboard with your existing authoritative local history:

coppermind dashboard import-local

That command copies local episodes into the managed dashboard plane. It does not replace the local runtime, and it is not ongoing hosted sync.

Running

# Start the runtime
coppermind daemon start

# Check and repair health
coppermind doctor
coppermind doctor --check
coppermind daemon health

# Stop the runtime
coppermind daemon stop

If the runtime stops coming up cleanly, start with coppermind doctor. It now performs bounded safe repairs and only fails closed when the issue is not safe to fix automatically, such as a foreign process owning the configured port. It also repairs the local SurrealDB plane when that backend is missing, stopped, or unhealthy. If the native service manifest exists but is not actually loaded, doctor refreshes and bootstraps it through Coppermind instead of requiring manual launchd steps. If legacy local memory parity drifts during SQLite-to-authoritative cutover, doctor backs up the affected authoritative rows, resets only that scoped set, and re-imports from the legacy export before re-verifying parity. If local AI assist is enabled, doctor also validates and repairs the local model bundle, the managed runtime bundle, and the persistent local-AI worker. Task-local fallback is reported separately from install/runtime health.

Coppermind's human-facing CLI output also supports a restrained themed presentation layer for interactive terminals:

• default theme visuals: mistborn
• default themed language intensity: off
• theme off returns to classic
• config-backed theme commands: coppermind theme on|off|status
• optional env overrides: COPPERMIND_THEME=classic|mist|mistborn
• optional themed language override: COPPERMIND_THEME_LANGUAGE=subtle|rich
• plain output override: COPPERMIND_PLAIN_OUTPUT=1

Example:

coppermind theme on
coppermind theme status
COPPERMIND_THEME=mistborn COPPERMIND_THEME_LANGUAGE=rich coppermind inspect

CLI Commands

| Command | Description | |---------|-------------| | coppermind setup | Prepare local runtime state | | coppermind update | Safely update a global npm install when possible | | coppermind update --check | Check for a newer published npm version | | coppermind doctor | Diagnose and apply bounded local runtime repairs | | coppermind doctor --check | Read-only runtime diagnostics | | coppermind mcp serve | Start Local Coppermind MCP over stdio | | coppermind mcp codex install | Write the managed Codex block for Local Coppermind MCP | | coppermind mcp claude install | Write the managed Claude Code block for Local Coppermind MCP | | coppermind mcp antigravity install | Write the managed Antigravity block for Local Coppermind MCP | | coppermind codex hooks install | Install managed Codex hooks for automatic capture | | coppermind codex hooks status | Show Codex hooks state and current Codex MCP state | | coppermind codex hooks remove | Remove only the managed Codex hooks entries | | coppermind dashboard import-local | Copy authoritative local history into the managed dashboard plane after upgrade | | coppermind api-key set <cm_live_xxx> | Save a Coppermind cloud API key for premium commands | | coppermind api-key clear | Remove the saved Coppermind cloud API key | | coppermind api-key status | Show where the Coppermind cloud API key is configured | | coppermind local-ai on | Enable advisory local AI assist and run bounded validation | | coppermind local-ai off | Disable advisory local AI assist without deleting bundles | | coppermind local-ai status | Show configured local AI state and current runtime snapshot | | coppermind theme on | Persist the Mistborn theme with rich language | | coppermind theme off | Persist the classic theme with literal copy | | coppermind theme status | Show configured theme plus env overrides | | coppermind search <query> | Search the local recall-oriented memory view | | coppermind stats | Show local memory counts and token usage | | coppermind inspect | Show the local recall-oriented inspect view | | coppermind run <command...> | Launch an agent with Coppermind's runtime defaults | | coppermind patch hermes | Install the Hermes integration | | coppermind daemon start | Start the runtime in foreground mode | | coppermind daemon stop | Stop the running runtime | | coppermind daemon status | Show runtime process status | | coppermind daemon health | Print /health snapshot as JSON | | coppermind daemon doctor | Detailed health + lifecycle report | | coppermind daemon service restart | Execute the platform-native restart flow |

Managed MCP installers write config and skill files for those clients. They do not install the third-party client binary itself, and they are still safe to run before the client is present.

Codex hooks are a separate optional layer for automatic capture. They do not replace MCP:

• coppermind mcp codex install = retrieval and explicit memory control through MCP
• coppermind codex hooks install = automatic capture from supported Codex lifecycle events

Optional Cloud Features

Cloud features are optional. Add a Coppermind API key only when you want account-bound behavior such as:

• hosted sync
• dashboard and billing features
• managed cloud controls
• BYODB attachment

The paid path today is:

1. Sign in to the Coppermind dashboard.
2. Upgrade in Billing if you need Pro or higher cloud features.
3. Create a key in API Keys.
4. Save it locally with:

coppermind api-key set <cm_live_xxx>

That key is a cloud credential, not a baseline runtime requirement.

Users who start local-first and later upgrade do not need to start over in the dashboard. coppermind dashboard import-local is the first upgrade bridge for that path. It uploads authoritative local episode history in batches to the managed dashboard plane so explorer and dashboard metrics can reflect existing history.

Coppermind checks npm for updates at most once per day on human-facing CLI commands and prints a short upgrade notice when the installed package is behind the latest published version.

Use coppermind update to apply the newest published version when your install can be updated in place:

coppermind update

If Coppermind cannot safely detect a normal global npm install, it falls back to printing the exact manual upgrade command instead of guessing. The usual fallback is npm install -g coppermind@latest.

Optional Local AI Assist

Local AI assist is implemented but remains default-off.

• pinned model: LiquidAI/LFM2.5-1.2B-Instruct
• bootstrap: lazy on coppermind daemon start or coppermind doctor
• runtime shape: Coppermind-managed persistent local worker
• role: advisory only
• primary triage path: ONNX triage classifier; LLM as fallback
• active model-backed tasks: candidate_compression
• shadow-only task: contradiction_suspicion
• deterministic-only task: doctor_explanation
• failure mode: task-local deterministic fallback; bundle and worker health remain distinct

Preferred controls:

coppermind local-ai on
coppermind local-ai off
coppermind local-ai status

You do not need a Hugging Face CLI, llama.cpp, llama-cli, or cloud API key for this path. Coppermind downloads the pinned model bundle and the managed local runtime itself if local AI assist is enabled.

Coppermind also manages the local inference runtime bundle itself on supported platforms. If bootstrap or worker startup fails, doctor surfaces bundle/runtime repair. If one advisory task times out or returns invalid JSON, Coppermind records task-local fallback and continues using deterministic processing without poisoning the whole local-AI install state.

Runtime Reliability

Coppermind now tracks local runtime ownership in ~/.coppermind/runtime.json and uses that record, the PID file, the health probe, and port ownership checks to classify the runtime state.

Important guarantees:

• Coppermind will repair stale PID and ownership metadata for you
• native service install and restart commands execute real user-scope platform actions where supported
• Coppermind will not kill a foreign process just because it owns the configured port
• coppermind daemon status and coppermind doctor --json expose the ownership mode, service state, last repair action, and next recommended action

MCP Modes

• coppermind mcp serve = Local Coppermind MCP
• npx -y @coppermind/mcp = Published Cloud MCP (Advanced)

Use the local path by default. Use the published package only when you explicitly want the direct cloud-connected route.

Docs

Full documentation at docs.coppermindapi.com