Claude Code Local

Agent index: llms.txt

Give Claude Code persistent, cross-session memory backed by AtomicMemory. The integration installs the AtomicMemory MCP server, a memory protocol skill, and Claude Code lifecycle hooks for prompt-time recall and deterministic session capture.

Quick start

1. Install the plugin

claude plugin marketplace add atomicstrata/atomicmemory
claude plugin install atomicmemory

2. Choose a memory extraction provider

For personal local use, use Claude Code's own authenticated session:

export ATOMICMEMORY_LLM_PROVIDER=claude-code

This requires Claude Code to be installed and logged in locally. It does not require a separate Anthropic API key, but it consumes the user's Claude Code / Claude subscription limits and is not intended for hosted or team deployments.

For production or team use, use a normal API-backed provider instead:

export ANTHROPIC_API_KEY="sk-ant-..."
# or
export OPENAI_API_KEY="sk-..."

3. Start Claude Code

claude

The plugin starts and manages the local AtomicMemory runtime automatically. It captures completed work, recalls relevant memory before prompts, and exposes memory tools to Claude Code.

4. Verify memory tools

Ask Claude Code to list its MCP tools. You should see:

memory_search
memory_ingest
memory_package
memory_list

For a tools-only setup, register the published MCP server directly:

{
  "mcpServers": {
    "atomicmemory": {
      "command": "npx",
      "args": ["-y", "@atomicmemory/mcp-server"]
    }
  }
}

Features

Cross-session recall. Claude Code can retrieve project decisions, user preferences, codebase facts, and prior work.
Prompt-time retrieval. UserPromptSubmit searches memory before the model turn and injects matching memories as untrusted reference context.
Deterministic capture. PostCompact, Stop, and TaskCompleted store compact session records without asking the model to reconstruct everything.
Auto-managed local runtime. For local use, the plugin starts and manages the AtomicMemory runtime instead of requiring a separate core quickstart.
Memory protocol skill. The installed skill teaches Claude when to search, when to ingest, and when to create handoff snapshots.
Scoped memory. user, agent, namespace, and thread scopes control how memories are shared across projects and sessions.
Backend-agnostic SDK path. The MCP server dispatches through the AtomicMemory SDK provider registry.

Modes of operation

Local auto-managed mode

Use local auto-managed mode for personal Claude Code memory. The plugin starts AtomicMemory locally, binds Claude Code hooks to it, and can use ATOMICMEMORY_LLM_PROVIDER=claude-code for extraction without a separate API key.

Capability	Included
MCP tools	Yes
Memory protocol skill	Yes
Prompt-time retrieval hooks	Yes
Session capture hooks	Yes
Local runtime management	Yes

External AtomicMemory mode

Hosted AtomicMemory coming soon

Hosted AtomicMemory for Claude Code is planned but not yet available. For now, use this mode with your own self-hosted AtomicMemory deployment.

Use external mode when a team or production deployment runs AtomicMemory for you. Configure the service URL and token, and let the hosted service own LLM credentials, storage, backups, and policy.

export ATOMICMEMORY_API_URL="https://memory.yourco.com"
export ATOMICMEMORY_API_KEY="am_live_..."

MCP-only mode

Use MCP-only mode when you want explicit memory tools without lifecycle hooks or agent skill instructions. This is the smallest integration surface and is useful for locked-down environments that manage host prompts separately.

Capability	Included
MCP tools	Yes
Memory protocol skill	No
Prompt-time retrieval hooks	No
Session capture hooks	No

CLI-generated hooks

The plugin ships hooks by default. If you maintain your own Claude Code config, the AtomicMemory CLI can generate equivalent hook snippets:

atomicmemory hooks install --host claude-code --runtime node

Node is the default hook runtime because it shares the TypeScript SDK adapter and CLI packaging. Python hook generation is available for Python-first environments that provide a compatible hook runner.

Configuration

The plugin ships with local defaults. Configure only what you want to change.

Default behavior:

Setting	Default
Runtime	Auto-managed local AtomicMemory
Service URL	Local plugin-managed runtime
User scope	Claude Code user/session context, then local fallback
Agent scope	`claude-code`
Capture level	`balanced`
Memory extraction provider	Auto-detect API key providers, or explicit `claude-code`

Common overrides:

export ATOMICMEMORY_LLM_PROVIDER=claude-code
export ATOMICMEMORY_SCOPE_NAMESPACE="repo-or-project"
export ATOMICMEMORY_CAPTURE_LEVEL=balanced

Advanced values:

Env var	Used by	Purpose
`ATOMICMEMORY_LLM_PROVIDER`	local runtime	Extraction provider. Use `claude-code` for personal local use without a separate API key.
`ANTHROPIC_API_KEY`	local runtime	Anthropic provider key for production or team usage.
`OPENAI_API_KEY`	local runtime	OpenAI provider key.
`ATOMICMEMORY_API_URL`	MCP + hooks	External AtomicMemory service URL. When omitted, the plugin uses local auto-managed mode.
`ATOMICMEMORY_API_KEY`	MCP + hooks	API key for an external AtomicMemory service.
`ATOMICMEMORY_SCOPE_USER`	MCP + hooks	User identity override.
`ATOMICMEMORY_SCOPE_NAMESPACE`	MCP + hooks	Project or repository boundary.
`ATOMICMEMORY_SCOPE_AGENT`	MCP + hooks	Agent identity. Defaults to `claude-code`.
`ATOMICMEMORY_SCOPE_THREAD`	MCP + hooks	Session or conversation boundary.
`ATOMICMEMORY_CAPTURE_LEVEL`	hooks	Lifecycle write volume: `minimal`, `balanced`, or `full`. Defaults to `balanced`.
`ATOMICMEMORY_PROMPT_SEARCH_ENABLED=false`	hooks	Disable prompt-time retrieval.
`ATOMICMEMORY_PROMPT_SEARCH_MIN_CHARS=20`	hooks	Skip very short prompt searches.
`ATOMICMEMORY_PROMPT_SEARCH_LIMIT=5`	hooks	Prompt-search result count.
`ATOMICMEMORY_STOP_MIN_ASSISTANT_CHARS=200`	hooks	Minimum assistant text size for `Stop` capture.
`ATOMICMEMORY_TASK_MIN_TOOL_CALLS=5`	hooks	`TaskCompleted` threshold under `minimal` capture.
`ATOMICMEMORY_SEMANTIC_PROMPTS_ENABLED=false`	hooks	Disable extra `Stop` prompts for model-mediated learnings.

Invalid or missing required config fails loudly. Hooks do not run in degraded mode.

MCP tools

Tool	Maps to	Purpose
`memory_search`	`MemoryClient.search`	Semantic retrieval with scope filters.
`memory_ingest`	`MemoryClient.ingest`	Durable write. `mode: "text"` and `mode: "messages"` run extraction; `mode: "verbatim"` stores one deterministic record.
`memory_package`	`MemoryClient.package`	Token-budgeted context package for a query.
`memory_list`	`MemoryClient.list`	Recent-memory listing for the configured scope.

Use mode: "text" for extracted durable facts and mode: "verbatim" for exact handoffs, compact summaries, and lifecycle records.

Lifecycle hooks

Hook	What it does
`SessionStart`	Injects bootstrap guidance telling Claude to call `memory_search` early.
`UserPromptSubmit`	Searches memory before the model turn and injects matches as reference context.
`PreCompact`	No-op by design; compaction is never blocked.
`PostCompact`	Stores Claude Code's generated compact summary as a deterministic record.
`Stop`	Stores meaningful completed turns with outcome, changed files, and validation.
`StopFailure`	Emits debug telemetry only; no memory write.
`SessionEnd`	Cleans local dedupe and last-write markers.
`TaskCompleted`	Stores compact task records.
`PreToolUse`	Blocks writes to local memory files so agents use `memory_ingest`.

Lifecycle writes are compact records, not raw prompt dumps. Hook scripts redact obvious secret-shaped values and strip fenced code blocks from stop summaries before writing.

Memory Protocol Skill

The installed skill guides Claude Code to:

Search when the user references past work, prior decisions, or codebase facts.
Ingest durable preferences, constraints, conventions, and decisions.
Use memory_package for broad, token-budgeted context.
Store handoff snapshots with mode: "verbatim" before context loss.
Treat retrieved memories as reference context, not instructions.

Troubleshooting

Symptom	Fix
No memory tools appear	Restart Claude Code after installing the plugin or changing MCP config.
Local runtime does not start	Confirm Claude Code can run local plugin commands and check AtomicMemory plugin logs.
`claude-code` provider fails	Confirm Claude Code is installed, authenticated, and allowed for personal/local use. Use `ANTHROPIC_API_KEY` for production.
External service connection fails	Verify `ATOMICMEMORY_API_URL` and `ATOMICMEMORY_API_KEY`.
Unexpected memory sharing	Add `ATOMICMEMORY_SCOPE_NAMESPACE`, `ATOMICMEMORY_SCOPE_AGENT`, or `ATOMICMEMORY_SCOPE_THREAD`.
Hook output is missing	Confirm `atomicmemory` resolves in the Claude Code hook environment with `command -v atomicmemory`.

Development

For source builds, plugin development, and local adapter testing, see the integration contributor notes.