Configuration

agentmemory runs keyless by default: no LLM key, no embedding key, no API auth. Copy .env.example to ~/.agentmemory/.env (agentmemory init does this) and uncomment only what you need. agentmemory doctor verifies which flags the daemon actually reads.

LLM provider

Pick one. Detection order: OPENAI_API_KEY, MINIMAX_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, then noop.

No key is required to run. Without one, observations are indexed via zero-LLM synthetic compression and hybrid search still works; LLM summarization, reflection, consolidation, graph extraction, and crystallization stay off until a provider key is set.

Variable	Effect
`OPENAI_API_KEY`	Activates the OpenAI-compatible LLM provider (DeepSeek, LiteLLM, vLLM, LM Studio, Ollama via `/v1`) and OpenAI embeddings
`OPENAI_BASE_URL`	Override for OpenAI-compatible providers (default `https://api.openai.com`)
`OPENAI_MODEL`	Default OpenAI-compatible chat model (`gpt-5.6-luna`)
`OPENAI_API_KEY_FOR_LLM=false`	Skip OpenAI auto-detection for LLM; the key stays active for embeddings
`ANTHROPIC_API_KEY`	Anthropic provider
`ANTHROPIC_MODEL`	Default Anthropic model (`claude-sonnet-5`)
`ANTHROPIC_BASE_URL`	Override for Anthropic-compatible proxies
`GEMINI_API_KEY`	Gemini provider; takes precedence over `GOOGLE_API_KEY`
`GOOGLE_API_KEY`	Alias for `GEMINI_API_KEY` when set alone
`GEMINI_MODEL`	Default Gemini model (`gemini-3.7-flash`)
`OPENROUTER_API_KEY`	OpenRouter provider
`OPENROUTER_MODEL`	Default OpenRouter model (`anthropic/claude-sonnet-5`)
`MINIMAX_API_KEY`	MiniMax provider
`MINIMAX_MODEL`	Default MiniMax model (`MiniMax-M3`)
`MAX_TOKENS`	Cap LLM completion tokens for compression and summarize calls (4096)
`AGENTMEMORY_LLM_TIMEOUT_MS`	Outbound LLM and embedding timeout shared by every raw-fetch provider (60000)
`AGENTMEMORY_ALLOW_AGENT_SDK=true`	Opt into the Claude-subscription fallback via agent-sdk child sessions; off by default
`FALLBACK_PROVIDERS`	Comma-separated chain tried after the primary provider errors

Embedding provider

Detection order: EMBEDDING_PROVIDER override, GEMINI_API_KEY, OPENAI_API_KEY, VOYAGE_API_KEY, COHERE_API_KEY, OPENROUTER_API_KEY, then local (Xenova/all-MiniLM-L6-v2, 384-dim). Without any key, hybrid search runs BM25-only.

Variable	Effect
`EMBEDDING_PROVIDER`	`local`, `openai`, `voyage`, `cohere`, `gemini`, or `openrouter`
`VOYAGE_API_KEY`	Voyage embeddings, optimized for code
`COHERE_API_KEY`	Cohere embeddings
`OPENAI_EMBEDDING_MODEL`	Embedding model when provider is openai (`text-embedding-3-small`)
`OPENAI_EMBEDDING_DIMENSIONS`	Required when the model is not in the known-models table (1536)
`OPENROUTER_EMBEDDING_MODEL`	Embedding model when provider is openrouter

Auth

Variable	Effect
`AGENTMEMORY_SECRET`	Bearer token required on the REST API, viewer, and all integration plugins. Without it, endpoints are open on loopback

Set AGENTMEMORY_SECRET before exposing the daemon beyond loopback. Mesh sync refuses to run without it, and the wired MCP entries pass it through to agents via ${AGENTMEMORY_SECRET:-}, so one export covers every connected client.

Search tuning

Variable	Effect
`BM25_WEIGHT`	Hybrid search weight for the BM25 leg (0.4)
`VECTOR_WEIGHT`	Hybrid search weight for the vector leg (0.6)
`AGENTMEMORY_GRAPH_WEIGHT`	Graph traversal bonus on smart-search ranking (0.2)
`TOKEN_BUDGET`	Max tokens injected via `mem::context` per session (2000)
`MAX_OBS_PER_SESSION`	Per-session observation cap before consolidation kicks in (500)
`SUMMARIZE_CHUNK_SIZE`	Sessions larger than this are chunked and map-reduced during summarize (400)
`SUMMARIZE_CHUNK_CONCURRENCY`	Parallel chunk LLM calls during chunked summarize (6)

Behavior flags

Variable	Effect
`AGENTMEMORY_AUTO_COMPRESS=true`	LLM-compress every observation batch; requires a provider key
`AGENTMEMORY_INJECT_CONTEXT=true`	Inject recalled memories back into agent prompts; default off
`CONSOLIDATION_ENABLED=true`	Run the 4-tier consolidation pipeline (memories, semantic, procedural)
`CONSOLIDATION_DECAY_DAYS`	Age in days after which non-reinforced memories decay during consolidation (30)
`GRAPH_EXTRACTION_ENABLED=true`	Gate the LLM pass that layers typed relations on top of the graph. The keyless structural pass (files and concepts become nodes, co-occurrence within an observation becomes a `related_to` edge) always runs at session end regardless of this flag
`GRAPH_EXTRACTION_BATCH_SIZE`	Memories per graph-extraction batch (8)
`AGENTMEMORY_LLM_NOTHINK=1`	Ask local reasoning models to skip their hidden thinking pass during graph extraction; faster, slight quality tradeoff
`AGENTMEMORY_REFLECT=true`	Periodically auto-synthesize lessons from memories
`AGENTMEMORY_DROP_STALE_INDEX=true`	Drop the on-disk BM25 and vector index on startup if the dimension guard fires
`AGENTMEMORY_IMAGE_EMBEDDINGS=true`	Enable image embeddings when an image provider is present (experimental)

CLI and runtime knobs

Variable	Effect
`AGENTMEMORY_TOOLS`	`all` (54 tools, default) or `core` (8 essentials) exposed to MCP clients
`AGENTMEMORY_SLOTS`	Comma-separated plugin slot names the CLI claims
`AGENTMEMORY_DEBUG=1`	Trace MCP shim probe and standalone fallback decisions to stderr
`AGENTMEMORY_FORCE_PROXY=1`	Skip the MCP shim livez probe and trust `AGENTMEMORY_URL`
`AGENTMEMORY_PROBE_TIMEOUT_MS`	MCP shim livez probe timeout (2000)
`AGENTMEMORY_URL`	REST base URL honored by status, doctor, and the MCP shim (`http://localhost:3111`)
`AGENTMEMORY_DATA_DIR`	Relocate the state directory when `--data-dir` is not passed
`AGENTMEMORY_VIEWER_URL`	Override the viewer URL printed by `agentmemory status`
`AGENTMEMORY_EXPORT_ROOT`	Default destination for `agentmemory export`
`STANDALONE_MCP=1`	MCP shim only: bypass the worker and run `@agentmemory/mcp` in-process
`STANDALONE_PERSIST_PATH`	Path for the standalone shim’s local fallback store (`~/.agentmemory/local.db`)
`SNAPSHOT_ENABLED=true`	Periodic snapshots of state and stream stores
`SNAPSHOT_DIR`	Snapshot destination (`~/.agentmemory/snapshots`)
`SNAPSHOT_INTERVAL`	Seconds between snapshots (3600)
`TEAM_MODE=shared`	Scope memories to (`TEAM_ID`, `USER_ID`) tuples
`TEAM_ID`	Team identifier for shared scoping
`USER_ID`	User identifier for shared scoping

Ports and engine

Variable	Effect
`III_REST_PORT`	REST API port (3111); the viewer follows at +2
`III_STREAMS_PORT`	Streams API port (3112)
`III_ENGINE_URL`	iii-engine WebSocket URL used by the worker (`ws://localhost:49134`)
`AGENTMEMORY_III_VERSION`	Override the pinned iii-engine version (0.11.2)

The engine version is pinned at 0.11.2 and startup refuses to adopt any other engine on the port; upgrade pulls only the pinned iiidev/iii:0.11.2 image, never a newer engine. Only override AGENTMEMORY_III_VERSION if you know the target version is wire-compatible.

Bridges

Variable	Effect
`CLAUDE_MEMORY_BRIDGE=true`	Mirror compressed memories into Claude Code’s memory file
`CLAUDE_PROJECT_PATH`	Required when the bridge is on; selects which project’s memory file to sync
`CLAUDE_MEMORY_LINE_BUDGET`	Lines of memory the bridge file may hold (200)
`OBSIDIAN_AUTO_EXPORT=true`	Auto-export memories to an Obsidian vault on every consolidation

Get started

Concepts

Connect

Integrations

Workflows

LLM provider

Embedding provider

Auth

Search tuning

Behavior flags

CLI and runtime knobs

Ports and engine

Bridges

​LLM provider

​Embedding provider

​Auth

​Search tuning

​Behavior flags

​CLI and runtime knobs

​Ports and engine

​Bridges

LLM provider

Embedding provider

Auth

Search tuning

Behavior flags

CLI and runtime knobs

Ports and engine

Bridges