How Coppermind Works

Coppermind is one product with one logical memory contract. The user-facing operations stay stable:

• ingest
• search
• inspect
• stats
• delete

What changes is where the data is stored and which optional cloud features are turned on.

The default story

The default story is local-first:

1. install coppermind
2. run coppermind setup
3. start the daemon
4. connect your client
5. verify with coppermind doctor

That path does not require an account, API key, dashboard session, or manual database setup.

The three operating modes

Local

This is the normal starting point for most users.

• the Coppermind daemon supervises the runtime
• Coppermind manages the local memory backend for you
• the local runtime is authoritative
• coppermind doctor is the repair surface

Hosted sync

This is the optional managed cloud layer.

• account identity lives here
• API keys live here
• billing and plan controls live here
• dashboard views live here

Hosted sync is for users who want managed cloud convenience on top of the local-first product path.

BYODB

This is the advanced paid path where Coppermind routes memory operations to infrastructure you control.

Choose this mode only when you already know you want your own storage in the loop.

The three integration surfaces

Managed client integrations

These are the easiest paths for supported clients.

Examples:

• coppermind mcp codex install
• coppermind mcp claude install
• coppermind patch hermes

MCP

MCP makes the memory operations explicit. A client talks to Coppermind through a local or cloud MCP server and exposes tools such as:

• memory_search
• memory_ingest
• memory_get
• memory_stats
• memory_delete

SDK

The SDK is the lowest-level public integration surface. Use it when you are writing your own application code against Coppermind.

What runs locally

The local runtime includes:

• the coppermind CLI
• the Coppermind daemon
• the local MCP server
• the managed local memory backend

That backend is now episode-first:

• Coppermind always preserves the raw episode
• only promoted rows enter the truth layer
• current truth and historical truth are grouped by canonical identity

The important boundary is simple:

• users and clients talk to Coppermind
• Coppermind owns the backend details

What the cloud layer does

The optional cloud layer handles:

• accounts
• API keys
• billing
• hosted sync
• dashboard controls
• BYODB attach

It is not required for first success.

Auth and memory scope

In cloud-connected paths, two ideas stay separate:

• the API key owner defines the tenant boundary
• the logical userId defines the memory scope inside that tenant

In pure local mode, cloud auth is not part of the path.

Local AI assist

Local AI assist is optional and default-off.

If you enable it, it acts as an advisory helper for memory quality tasks such as triage, compression, and background contradiction review. It does not become the source of truth for the stored memory state.

The most important product rule

Backend details should stay hidden on day one.

New users should not need to understand:

• the local database implementation
• manual backend provisioning
• infrastructure terms such as BYODB

They should be able to install Coppermind, connect a client, and use memory.

Where to go next

• Quick Start
• Choose Your Client
• Local, Hosted Sync, and BYODB