> ## Documentation Index
> Fetch the complete documentation index at: https://agent-memory.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration
> Every agentmemory environment flag for LLM providers, embeddings, auth, search tuning, ports, and bridges, read from ~/.agentmemory/.env.
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 |