Quick Start

Coppermind is a local-first memory layer for AI coding agents. The default path is:

1. install coppermind
2. prepare local state
3. start the runtime
4. verify with coppermind doctor
5. connect your client

You do not need an account, API key, dashboard session, or manual SurrealDB setup for first local success.

Before you start

You need:

• Node.js 20 or newer
• one supported client such as Codex, Claude Code, Cursor, Hermes, or another MCP-capable client

If you are unsure which package or client path you want, read Which Package Should I Install? or Choose Your Client first.

1. Install Coppermind

npm install -g coppermind

This installs the Coppermind CLI and local runtime supervisor.

2. Prepare local state

coppermind setup

coppermind setup prepares the local Coppermind runtime and silently provisions the managed local memory engine on supported platforms.

You still do not need to install or run SurrealDB yourself.

3. Start the runtime

coppermind daemon start

This starts the local Coppermind daemon that backs CLI commands, client integrations, and the local MCP server.

4. Verify the install

coppermind doctor
coppermind daemon health

coppermind doctor is the main repair surface. If something drifted during setup or upgrade, this is the command that should bring the local runtime back to a healthy state.

Healthy output means:

• the daemon is reachable
• the local memory backend is healthy
• Coppermind is ready for a client integration

5. Connect your client

Choose the guide that matches your setup:

• Codex Setup
• Claude Code Setup
• Cursor and Other MCP Clients
• Hermes Setup

For Codex, for example:

coppermind mcp codex install

What happens after install

Once setup is healthy, the normal flow is:

npm install -g coppermind
coppermind setup
coppermind daemon start
coppermind doctor
coppermind mcp codex install

Expected result:

• the runtime is healthy
• the client is registered
• memory tools or hooks show up where that client expects them

Optional local AI assist

Local AI assist is separate from the default install path and stays default-off.

If you want it later:

coppermind local-ai on

It is advisory only. It does not replace the normal memory runtime or become the source of truth for your stored memory.

Cloud features are optional

Login, API keys, hosted sync, dashboard controls, and BYODB attach all live behind the optional cloud layer.

If you only want the default local runtime, you can stop after local setup and client install.

If something fails

Start here, in order:

1. coppermind doctor
2. coppermind doctor --check
3. coppermind daemon health
4. Troubleshooting and Support

If you see an update notice while debugging, upgrade first with:

coppermind update