Skip to main content
The AtomicMemory CLI exposes four command groups — setup, diagnose, agent, and memory — each targeting a distinct part of the memory workflow. Every command accepts the shared flags --provider, --api-url, --user, and --namespace to override config-file defaults per invocation. All commands also accept --agent to emit stable JSON envelopes suitable for script consumption.

​
Setup commands

The setup group configures your local AtomicMemory environment and integrates the CLI with the agent hosts you use.
1

Initialize config

atomicmemory init writes ~/.atomicmemory/config.json and is typically the first command you run after installation.
atomicmemory init --api-url http://127.0.0.1:17350 --user "$USER"
Pass --api-key-stdin to read your API key from stdin instead of a flag, keeping it out of shell history.
2

Inspect and edit config

atomicmemory config shows your current configuration (API keys are redacted by default). Use config set to update individual keys without re-running init.
# Print current config
atomicmemory config

# Update a single key
atomicmemory config set api-url https://memory.yourco.com
3

Install lifecycle hooks

atomicmemory hooks install emits lifecycle hook configuration for a supported agent host. Node.js is the recommended runtime and is bundled as atomicmemory hooks run. Python is an advanced option for teams that set ATOMICMEMORY_PYTHON_HOOK_BIN.
# Install hooks for Claude Code (Node runtime)
atomicmemory hooks install --host claude-code --runtime node

# Install hooks for Codex
atomicmemory hooks install --host codex --runtime node

# Advanced: Python runtime
atomicmemory hooks install --host codex --runtime python
The hooks install command emits config — it does not mutate your agent host’s own config files. Follow the printed instructions to apply the output.
4

Enable shell completion

atomicmemory completion outputs a shell completion script for the CLI. Source it in your shell config to enable tab-completion for commands, subcommands, and flags.
# Print the completion script for your shell
atomicmemory completion

# Example: add to your shell config permanently
atomicmemory completion >> ~/.zshrc
source ~/.zshrc

​
Diagnose commands

The diagnose group helps you verify connectivity to your AtomicMemory Core instance and catch misconfiguration before it affects agent workflows.
Runs the full diagnostic suite: connection check, config validation, scope resolution, and provider health. Start here whenever something isn’t working.
atomicmemory doctor
Prints a concise summary of the current connection state — useful for a quick pulse check without the full diagnostic output.
atomicmemory status
Validates your config file against the published schema and reports any missing required fields or type errors.
atomicmemory validate

​
Memory commands

The memory group covers the full lifecycle of individual memories: adding, ingesting, searching, packaging, listing, retrieving by ID, deleting, and importing.

​
Adding a memory

Use add to write a single memory directly, without going through the ingest pipeline: 
atomicmemory add "I prefer dark mode and TypeScript."

​
Ingesting a conversation turn

Use ingest to process a structured conversation turn (e.g. a JSON file produced by an agent host). The ingest pipeline extracts discrete memories from the turn: 
# Ingest from a file
atomicmemory ingest --file turn.json

# Ingest from stdin
cat turn.json | atomicmemory ingest

​
Searching memories

search performs semantic search over your scoped memories and returns ranked results: 
# Basic search
atomicmemory search "What are my editor preferences?"

# With result limit and explicit user scope
atomicmemory search "preferences" --limit 10 --user alice

​
Packaging context for an agent

package retrieves memories relevant to a query and assembles them into a context block that fits within a token budget — ideal for prepending to a system prompt: 
atomicmemory package "editor setup" --token-budget 1200

​
Listing memories

list enumerates memories in scope, with optional pagination: 
# List memories for the configured user
atomicmemory list

# List for a specific user with a limit
atomicmemory list --user alice --limit 20

​
Getting a specific memory

get retrieves the full details of a single memory by its ID: 
atomicmemory get <memory-id>

​
Deleting a memory

delete removes a memory by ID: 
atomicmemory delete <memory-id>

​
Importing from an export

import loads memories from a supported export format. Currently supports llmwiki exports: 
atomicmemory import --source llmwiki --file export.json

​
Agent commands

The agent group provides resources for embedding AtomicMemory awareness into agent prompts and for reporting version information.
Prints the AtomicMemory skill definition — a structured prompt fragment you can embed in an agent’s system prompt to teach it how to use memory tools effectively.
atomicmemory skill get core
Reports the installed CLI version.
atomicmemory version
Prints command reference in human-readable format. Pass --json for a machine-readable command tree.
atomicmemory help
atomicmemory help --json

​
Agent mode (--agent)

All commands accept a top-level --agent flag that switches output to stable JSON envelopes. Use this whenever the CLI is invoked by another program, a CI step, or an agent tool call. 
# JSON output suitable for agent or script consumption
atomicmemory --agent search "preferences"
Example success envelope: 
{
  "status": "success",
  "command": "search",
  "duration_ms": 42,
  "profile": "default",
  "scope": { "user": "alice" },
  "count": 3,
  "data": []
}
The JSON envelope shape is the stable public contract. Human-readable output may be reformatted between minor versions. Always use --agent in automation, CI, and when scripting against the CLI from other processes.
In --agent mode, errors are written to stdout (not stderr) and exit with a non-zero code. Make sure your error-handling logic reads stdout, not only stderr.