Repository navigation
Expand file tree
/
Copy path.env.example
More file actions
259 lines (219 loc) · 19 KB
/
Copy path.env.example
File metadata and controls
259 lines (219 loc) · 19 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
# =============================================================================
# agentmemory configuration
# =============================================================================
#
# Copy this file to `~/.agentmemory/.env` (or to your project root if you
# prefer scoped config) and uncomment the lines you want to override.
#
# Optional providers and features are off by default — `agentmemory` runs
# without an LLM or embedding key. Local API authentication uses a generated
# secret unless you set AGENTMEMORY_SECRET explicitly.
#
# Run `npx -y @agentmemory/agentmemory@latest init` to copy this file into
# place automatically. Run `npx -y @agentmemory/agentmemory@latest doctor`
# to verify that the daemon reads the env you expect.
#
# Defaults shown in comments. No provider is ever picked from a key alone:
# agentmemory sends session content to an outside AI provider only after you
# name one with AGENTMEMORY_LLM_PROVIDER or EMBEDDING_PROVIDER, or opt into the
# Claude subscription fallback with AGENTMEMORY_ALLOW_AGENT_SDK=true.
# -----------------------------------------------------------------------------
# 1. LLM provider: off unless you choose one
# -----------------------------------------------------------------------------
#
# Without AGENTMEMORY_LLM_PROVIDER or AGENTMEMORY_ALLOW_AGENT_SDK=true, agentmemory
# runs in noop mode and sends no session content to an LLM, even when a provider
# key is in the environment.
# In noop mode: observations are
# indexed via zero-LLM synthetic compression and BM25 recall still works,
# but LLM-backed summarisation / reflection / consolidation are disabled.
# A provider key alone does not enable LLM-written observation compression;
# that path also requires AGENTMEMORY_AUTO_COMPRESS=true.
# AGENTMEMORY_CAPTURE_ALLOW= # Comma/space list of tool names or globs to capture; when set, only these are captured
# AGENTMEMORY_CAPTURE_DENY= # Extra tool names or globs to skip, added to the defaults (memory_*, toolsearch, listmcpresources, fetchmcpresource)
# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output stored per captured observation
# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for context injected by the PreCompact hook; 0 disables it
# AGENTMEMORY_CAPTURE_MAX_ATTEMPTS=5 # Attempts before a capture becomes a dead letter
# AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS=10000 # Retry sweep interval and backoff base
# AGENTMEMORY_CAPTURE_DEDUP_HOURS=168 # How long stored event ids block replays
# AGENTMEMORY_CAPTURE_EVENTS_MAX=100000 # Max stored event ids
# AGENTMEMORY_CAPTURE_INBOX_MAX=10000 # Max unprocessed events before 503
# AGENTMEMORY_CAPTURE_DEAD_MAX=1000 # Max dead letters kept
# AGENTMEMORY_CAPTURE_SPOOL=false # Turn off the hook offline spool
# AGENTMEMORY_CAPTURE_SPOOL_DIR= # Spool folder (default <data dir>/capture-spool)
# AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES=5242880 # Spool size limit
# AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS=168 # Spooled records older than this are dropped
# To turn on LLM summaries, set AGENTMEMORY_LLM_PROVIDER and that provider's key.
# AGENTMEMORY_LLM_PROVIDER=anthropic # anthropic | openai | gemini | openrouter | minimax
# OPENAI_API_KEY=sk-... # Used by AGENTMEMORY_LLM_PROVIDER=openai (OpenAI-compatible: DeepSeek, SiliconFlow, vLLM, LM Studio, Ollama via `/v1`) and by EMBEDDING_PROVIDER=openai
# OPENAI_BASE_URL=https://api.openai.com # Override for OpenAI-compatible providers
# OPENAI_MODEL=gpt-5.6-luna # Default OpenAI-compatible chat model
# ANTHROPIC_API_KEY=sk-ant-...
# ANTHROPIC_MODEL=claude-sonnet-5 # Default Anthropic model
# ANTHROPIC_BASE_URL=https://api.anthropic.com # Override for Anthropic-compatible proxies / Azure AI Foundry
# GEMINI_API_KEY=... # Either env name works; GEMINI_API_KEY takes precedence
# GOOGLE_API_KEY=... # Alias for GEMINI_API_KEY when set alone (emits a one-time stderr hint)
# GEMINI_MODEL=gemini-3.7-flash # Default Gemini model (current stable Flash)
# OPENROUTER_API_KEY=sk-or-...
# OPENROUTER_MODEL=anthropic/claude-sonnet-5
# MINIMAX_API_KEY=...
# MINIMAX_MODEL=MiniMax-M3
# MAX_TOKENS=4096 # Cap LLM completion tokens for compression / summarise calls
# Outbound LLM / embedding timeout — shared across every raw-fetch provider
# (Gemini, OpenRouter, MiniMax, OpenAI LLM, and OpenAI/Cohere/Voyage/OpenRouter
# embedding). The OpenAI LLM path also honours the OpenAI-scoped
# OPENAI_TIMEOUT_MS alias for back-compat with v0.9.17 (precedence).
# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk
# child sessions). Off by default — the agent-sdk fallback can trigger
# Stop-hook recursion when invoked from inside Claude Code.
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# FALLBACK_PROVIDERS=anthropic,gemini # Comma-separated chain tried after the chosen AGENTMEMORY_LLM_PROVIDER returns an error (e.g. rate limit); ignored when zero-LLM is active
# -----------------------------------------------------------------------------
# 2. Embedding provider: off unless you set EMBEDDING_PROVIDER
# -----------------------------------------------------------------------------
#
# Without an embedding provider, vector embeddings are disabled. `mem::search`
# uses BM25; `mem::smart-search` can also fuse structural graph matches when
# graph data exists. Cloud embeddings send memory text to that provider and run
# only when EMBEDDING_PROVIDER names it; a key alone never turns them on.
# Local embeddings are an explicit opt-in too, not the keyless default.
# `EMBEDDING_PROVIDER=local` uses Xenova/all-MiniLM-L6-v2 (384-dim) on-device;
# the first embedding request downloads the model and needs network access.
# EMBEDDING_PROVIDER=local # local | openai | voyage | cohere | gemini | openrouter
# VOYAGE_API_KEY=pa-... # Optimised for code embeddings
# COHERE_API_KEY=... # General-purpose embeddings
# Reuses OPENAI_API_KEY / OPENAI_BASE_URL above when EMBEDDING_PROVIDER=openai.
# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small # Embedding model when EMBEDDING_PROVIDER=openai
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
# OPENROUTER_EMBEDDING_MODEL=openai/text-embedding-3-small # When EMBEDDING_PROVIDER=openrouter
# -----------------------------------------------------------------------------
# 3. Auth & security
# -----------------------------------------------------------------------------
#
# Bearer-token auth for the REST API + viewer + all integration plugins.
# The CLI generates a secret when unset and local clients retrieve it from
# the data directory. Set this explicitly for remote clients/deployments.
# AGENTMEMORY_SECRET=your-secret # generated into the selected data directory on first start when unset
# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
# AGENTMEMORY_IMPORT_ROOT=~/projects
# -----------------------------------------------------------------------------
# 4. Search tuning
# -----------------------------------------------------------------------------
# BM25_WEIGHT=0.4 # Hybrid search weight for BM25 leg
# VECTOR_WEIGHT=0.6 # Hybrid search weight for vector leg
# AGENTMEMORY_GRAPH_WEIGHT=0.2 # Graph traversal bonus on smart-search ranking
# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false # Report boot compaction as off (otherwise deferred; manual maintenance only)
# AGENTMEMORY_GRAPH_IMPORT_MAX_NODES=5000 # Node limit for POST /graph/import-graphify; nodes over it are dropped and reported
# AGENTMEMORY_GRAPH_IMPORT_MAX_EDGES=20000 # Edge limit for POST /graph/import-graphify; edges over it are dropped and reported
# TOKEN_BUDGET=2000 # Max tokens injected via mem::context per session
# MAX_OBS_PER_SESSION=500 # Hard per-session cap: later observations of that session are refused; only capture-worker refusals are parked as dead letters (0 = no cap)
# SUMMARIZE_CHUNK_SIZE=400 # When mem::summarize sees a session larger than this, it chunks observations and map-reduces (chunk-summarize → reduce-merge) to stay within the LLM's context window. Default 400 ≈ 50k tokens per chunk at ~110 tok/obs. Native sessions are capped by MAX_OBS_PER_SESSION; chunking primarily matters for bulk-imported jsonl sessions, which bypass that cap.
# SUMMARIZE_CHUNK_CONCURRENCY=6 # Parallel chunk LLM calls during chunked summarize. Default 6 fits ~100-chunk sessions under iii's 180s function-invocation timeout at typical ~8s/call. High-throughput providers (Novita, DeepInfra, DeepSeek) commonly allow 100+ concurrent — bump this for very large imported sessions.
# AGENTMEMORY_SUMMARY_TIMEOUT_MS=120000 # Total time budget in whole milliseconds for one mem::summarize run, shared by every chunk call. Default 120000 (2 min). Raise it for slow or local LLMs (Ollama, LM Studio, vLLM) on large chunked sessions that fail with summary_timeout. Session-end and recovery summaries wait this budget plus 60 s; POST /agentmemory/summarize is still cut off by the 180 s HTTP worker timeout, but the summary keeps running and is saved.
# -----------------------------------------------------------------------------
# 5. Behaviour flags
# -----------------------------------------------------------------------------
# AGENTMEMORY_AUTO_COMPRESS=true # Run LLM-written compression on every observation batch. Requires BOTH this flag and a configured provider; a provider alone leaves synthetic compression active.
# AGENTMEMORY_INJECT_CONTEXT=true # Opt in to Claude-style hook context injection. Pi/OMP use 1 in their launch environment for file enrichment; native prompt recall is independent.
# AGENTMEMORY_ENRICH_TIMEOUT_MS=2000 # PreToolUse hook wait (default 2000 ms). Set this in the hook process environment; setting it only in this server env file does not change the hook timeout.
# CONSOLIDATION_ENABLED=false # Disable the consolidation pipeline. Otherwise enabled when an LLM provider is configured, unless AGENTMEMORY_PROVIDER=noop.
# CONSOLIDATION_DECAY_DAYS=30 # Age (days) after which non-reinforced memories decay during consolidation
# GRAPH_EXTRACTION_ENABLED=true # Extract concept-graph edges on remember; powers the graph-traversal recall path
# GRAPH_EXTRACTION_BATCH_SIZE=10 # Memories per graph-extraction batch
# Local reasoning models only: set to 1 to ask the model to skip its
# hidden thinking pass during graph extraction. Extraction runs several
# times faster; relation quality can drop slightly. Leave unset to let
# the model think (default).
# AGENTMEMORY_LLM_NOTHINK=1
# AGENTMEMORY_REFLECT=true # Enable slot reflection; requires AGENTMEMORY_SLOTS=true
# AGENTMEMORY_DROP_STALE_INDEX=true # Drop on-disk BM25 / vector index on startup if dim guard fires. Recovery toggle for stuck-state debugging.
# AGENTMEMORY_IMAGE_EMBEDDINGS=true # Enable image embeddings when an image provider is present (experimental).
# AGENTMEMORY_AUDIT_RETENTION_MONTHS=6 # Drop whole audit-log month scopes older than N months on a daily sweep. Default 0 = keep audit history forever.
# AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES=33554432 # Largest legacy mem:audit scope file the one-time migration will read locally. Default 32 MiB; bigger or unreadable stores are left frozen.
# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # Set to 1 or true to audit index migration and cleanup writes (debugging only)
# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves; shutdown and deletes still save immediately.
# AGENTMEMORY_VECTOR_BUCKET_SIZE=500 # Vectors held per storage bucket before a new bucket opens; a save only rewrites buckets it changed.
# AGENTMEMORY_VECTOR_BACKFILL_MAX=500 # Batch size for re-embedding vectors missing since the last save (continues across restarts); also caps the whole-store opt-in per boot.
# AGENTMEMORY_VECTOR_BACKFILL=all # Required to backfill an entire store's vectors at once (no prior vector save, or a stale legacy manifest); unset means that case waits for an explicit opt-in.
# -----------------------------------------------------------------------------
# 6. CLI / runtime knobs
# -----------------------------------------------------------------------------
# AGENTMEMORY_TOOLS=core # all (54 tools, default) | core (8 tools): surface exposed to MCP clients
# AGENTMEMORY_SLOTS=true # Enable structured memory slots (default off)
# AGENTMEMORY_DEBUG=1 # Trace MCP shim probe + standalone fallback decisions to stderr
# AGENTMEMORY_FORCE_PROXY=1 # Skip the MCP shim livez probe and trust AGENTMEMORY_URL (for sandboxed MCP clients that can't reach localhost)
# AGENTMEMORY_PROBE_TIMEOUT_MS=2000 # MCP shim livez probe timeout
# AGENTMEMORY_CALL_TIMEOUT_MS=190000 # MCP shim and plugin bridge timeout for each proxied REST call, read from the MCP host environment or this file. Default 190000, a little above the 180 s worker invocation limit, so long calls such as memory_consolidate and memory_reflect end on the server first
# AGENTMEMORY_READY_TIMEOUT_MS=300000 # CLI worker readiness deadline, including state loading (5 minutes)
# AGENTMEMORY_ENGINE_READY_TIMEOUT_MS=120000 # CLI engine readiness deadline (2 minutes)
# Startup deadlines accept whole milliseconds from 1 to 3600000. Shell
# environment overrides this file. Engine and worker waits have separate
# budgets; increase them only for a slow store.
# AGENTMEMORY_ENGINE_MANAGES_WORKER=true # Custom engine-managed worker wrapper; unset detects direct worker commands
# AGENTMEMORY_URL=http://localhost:3111 # REST base URL — honored by status, doctor, MCP shim
# AGENTMEMORY_VIEWER_URL=http://localhost:3113 # Override the viewer URL printed by `agentmemory status`
# Persistent iii state; same override as `--data-dir`. Instance 0 reuses
# an existing ./data/state_store.db before platform defaults: macOS
# ~/Library/Application Support/agentmemory; Linux $XDG_DATA_HOME/agentmemory
# or ~/.local/share/agentmemory; Windows %APPDATA%\agentmemory.
# AGENTMEMORY_DATA_DIR=/absolute/path
# AGENTMEMORY_ENV_FILE=/absolute/path/to/.env # Config file override (default ~/.agentmemory/.env)
# AGENTMEMORY_EXPORT_ROOT=~/agentmemory-backup # Root directory for Obsidian vault exports
# AGENTMEMORY_STATE_BACKEND=redis # file (default) | redis — see docs/reliability/state-storage.md
# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required when AGENTMEMORY_STATE_BACKEND=redis
# STANDALONE_MCP=1 # MCP shim only — bypass the worker and run @agentmemory/mcp in-process
# STANDALONE_PERSIST_PATH=~/.agentmemory/local.db # Path used by the standalone MCP shim's local fallback store
# Snapshot exporter — periodic snapshots of state_store.
# SNAPSHOT_ENABLED=true
# SNAPSHOT_DIR=~/.agentmemory/snapshots
# SNAPSHOT_INTERVAL=3600 # Seconds between snapshots
# Team sharing — when set, memories are scoped to (TEAM_ID, USER_ID) tuples.
# TEAM_MODE=shared
# TEAM_ID=acme
# USER_ID=rohit
# -----------------------------------------------------------------------------
# 7. Ports
# -----------------------------------------------------------------------------
# III_REST_PORT=3111 # REST API + MCP HTTP anchor
# III_VIEWER_PORT=3113 # Viewer bind port; defaults to REST + 2
# III_ENGINE_PORT=49134 # Engine bind port; defaults to REST + 46023
# III_ENGINE_URL=ws://localhost:49134 # Explicit/remote worker WebSocket URL; takes precedence over derived engine port
# Derivation applies only while the corresponding explicit port/URL is unset.
# `--instance 1` selects REST/viewer/engine ports 3211/3213/49234 and an instance-1 data subdir.
# -----------------------------------------------------------------------------
# 8. iii engine pin
# -----------------------------------------------------------------------------
#
# agentmemory pins iii-engine and its iii-sdk dependencies to v0.25.1.
# The CLI downloads the engine into ~/.agentmemory/bin, including the Windows ZIP.
# AGENTMEMORY_III_VERSION=0.25.1 # Override only when deliberately matching a different engine
# AGENTMEMORY_LOCAL_DISPATCH=true # iii 0.25 runs calls to the worker's own functions in-process; set false for full engine traces
# Engine usage telemetry (iii). Off unless you set it; true opts in.
# III_TELEMETRY_ENABLED=false
# -----------------------------------------------------------------------------
# 9. Session sweep
# -----------------------------------------------------------------------------
# Hourly backstop that marks stale active sessions as abandoned.
# AGENTMEMORY_SESSION_SWEEP_ENABLED=false # Disable the hourly sweep
# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24 # Inactivity hours before a session is abandoned
# AGENTMEMORY_FINALIZE_IDLE_MS=120000 # Idle time after a per-turn Stop before the session is completed and summarized (0 = on every Stop)
# -----------------------------------------------------------------------------
# 10. Claude Code bridge (opt-in)
# -----------------------------------------------------------------------------
# CLAUDE_MEMORY_BRIDGE=true # Export project memories into Claude Code's MEMORY.md
# CLAUDE_PROJECT_PATH=/path/to/your/project # Required when CLAUDE_MEMORY_BRIDGE=true
# CLAUDE_MEMORY_LINE_BUDGET=200 # Maximum lines in the generated MEMORY.md
# The bridge creates MEMORY.md only when absent. Every existing file is
# preserved, including old generated exports and files edited by Claude Code.
# An identical export is a no-op; different content returns an error. To
# regenerate, deliberately move the existing file to a backup location first
# (or remove it if no longer needed), then run memory_claude_bridge_sync again.
# Only memories scoped to this project are exported; unscoped memories are
# excluded. Reading MEMORY.md remains available regardless of who wrote it.
# -----------------------------------------------------------------------------
# 11. Obsidian export (opt-in)
# -----------------------------------------------------------------------------
# OBSIDIAN_AUTO_EXPORT=true # Auto-export memories to an Obsidian vault on every consolidation