memory_search, memory_ingest, memory_package, and memory_list as first-class tools; a set of lifecycle hook scripts that automatically capture decisions, compaction summaries, and task completions without any manual prompting; and a skill file (SKILL.md) that teaches Claude exactly when and how to call the memory tools. All captured records survive session boundaries and are immediately searchable in future sessions.
Prerequisites
The lifecycle hook scripts are written in Bash and depend onjq for safe JSON parsing and curl for prompt-time memory retrieval. Install both before running the plugin installer.
- macOS
- Debian / Ubuntu
Configuration
The MCP server and all hook scripts read their settings from shell environment variables. No variables are required when running against a local AtomicMemory core — the plugin ships with sensible defaults for local development.Set environment variables only when you need to override a default, for example to connect to a hosted or team AtomicMemory service.
Local-mode defaults
| Variable | Default |
|---|---|
ATOMICMEMORY_API_URL | http://127.0.0.1:17350 |
ATOMICMEMORY_API_KEY | local-dev-key |
ATOMICMEMORY_PROVIDER | atomicmemory |
ATOMICMEMORY_SCOPE_USER | Derived from OS user |
ATOMICMEMORY_CAPTURE_LEVEL | balanced |
Overriding for a hosted service
ATOMICMEMORY_SCOPE_USER explicitly when multiple operators share a machine or when you need a stable cross-machine identity. If you omit it, the MCP server derives a value from the host OS user automatically.
Optional scope variables
You can further narrow where memories are stored and retrieved by setting any of these optional variables:| Variable | Purpose |
|---|---|
ATOMICMEMORY_SCOPE_NAMESPACE | Per-project isolation boundary (e.g. a repo name) |
ATOMICMEMORY_SCOPE_AGENT | Identifies the agent role within a scope |
ATOMICMEMORY_SCOPE_THREAD | Isolates a specific conversation thread |
Local extraction with Claude Code auth
For personal or local use, AtomicMemory core can use Claude Code’s own local authentication for semantic extraction instead of a separate Anthropic API key:Install
Register the local marketplace
From the root of the cloned AtomicMemory repository, register the repo as a local plugin marketplace. You only need to do this once.
Install the plugin
Install the AtomicMemory plugin into Claude Code:The plugin fetches
@atomicmemory/mcp-server from npm via npx on first use — no local build is required.Restart Claude Code
Fully restart Claude Code after installation. Existing sessions can retain old hook registrations in memory even after the on-disk cache is updated.
Verify the installation
Confirm the plugin is active by checking three things:
claude plugin listshowsclaude-code@atomicmemoryas enabled.- A fresh Claude Code session can see
memory_search,memory_ingest,memory_package, andmemory_listas available tools. - The
PreCompacthook exits cleanly when triggered — it should produce no output.
Lifecycle hooks
The plugin registers hooks for every significant Claude Code lifecycle event. Each hook fires automatically — you do not need to prompt Claude or call any tools manually.| Hook | Trigger |
|---|---|
SessionStart | Beginning of a Claude Code session — injects a bootstrap prompt so Claude calls memory_search early |
UserPromptSubmit | Before each user prompt — searches memory via HTTP and injects matching memories as context |
PreCompact | Before context window compaction — no-op by design; PostCompact handles capture |
PostCompact | After compaction — stores Claude Code’s generated compact_summary as a cleaned memory record |
Stop | Agent stop — stores the cleaned last assistant response for meaningful turns |
StopFailure | Agent failure — debug telemetry only; no memory write |
SessionEnd | End of session — cleans local dedupe and last-write markers |
TaskCompleted | Task completion — stores a cleaned task subject and optional description as a memory record |
PreToolUse (Write|Edit) | Before file write or edit tool calls — blocks writes to MEMORY.md and similar memory-file paths, redirecting the agent to use memory_ingest instead |
Hook runtime
By default the plugin uses its versioned Bash hook scripts. For manual hook configurations, the AtomicMemory CLI can generate host-specific snippets with a choice of runtime:atomicmemory CLI binary is available inside the hook environment — Claude Code hook environments are often spawned with a thinner PATH than your interactive shell:
@atomicmemory/cli globally or invoke it through a wrapper that adds the resolved bin to PATH.
Advanced capture controls
You can fine-tune memory capture volume with additional environment variables. All of these are optional and fail closed if set to invalid values.Capture control variables
Capture control variables
| Variable | Purpose | Default |
|---|---|---|
ATOMICMEMORY_PROMPT_SEARCH_ENABLED | Set to false to disable per-prompt retrieval | true |
ATOMICMEMORY_PROMPT_SEARCH_MIN_CHARS | Minimum prompt length to trigger a search | 20 |
ATOMICMEMORY_PROMPT_SEARCH_LIMIT | Number of results returned during prompt search | 5 |
ATOMICMEMORY_STOP_MIN_ASSISTANT_CHARS | Minimum assistant response length for Stop capture | 200 |
ATOMICMEMORY_STOP_MAX_SUMMARY_CHARS | Maximum assistant response excerpt stored by Stop | 600 |
ATOMICMEMORY_COMPACT_MAX_SUMMARY_CHARS | Maximum PostCompact summary excerpt | 2400 |
ATOMICMEMORY_TASK_MIN_TOOL_CALLS | TaskCompleted threshold under minimal capture level | 5 |
ATOMICMEMORY_TASK_MAX_DESCRIPTION_CHARS | Maximum task description excerpt stored by TaskCompleted | 600 |
ATOMICMEMORY_SEMANTIC_PROMPTS_ENABLED | Set to false to disable Stop prompts that extract semantic learnings | true |
ATOMICMEMORY_STOP_MIN_ASSISTANT_CHARS default of 200 was tuned for Claude Code’s typical multi-paragraph assistant responses. If your workflow produces consistently shorter responses you still want captured, lower this value. Codex users sharing the bundled Node hook runtime should consult the Codex plugin page for host-specific guidance.