@agentmemory/agentmemory 0.9.12 → 0.9.14

package/.env.example

@@ -0,0 +1,167 @@
+# =============================================================================
+# 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.
+#
+# Every line is OFF by default — `agentmemory` runs out of the box with no
+# LLM key, no embedding key, and no API auth. Set keys here only when you
+# want to enable the corresponding feature.
+#
+# Run `npx @agentmemory/agentmemory init` to copy this file into place
+# automatically. Run `npx @agentmemory/agentmemory doctor` to verify that
+# the daemon reads the env you expect.
+#
+# Defaults shown in comments. Listed in priority order — the first key
+# present wins on the LLM detection path (see src/config.ts::detectProvider).
+
+# -----------------------------------------------------------------------------
+# 1. LLM provider — pick ONE
+# -----------------------------------------------------------------------------
+#
+# Without a provider key, agentmemory runs in noop mode: observations are
+# indexed via zero-LLM synthetic compression, hybrid search still works,
+# but LLM-backed summarisation / reflection / consolidation are disabled.
+# The detection order is OPENAI_API_KEY → MINIMAX_API_KEY → ANTHROPIC_API_KEY
+# → GEMINI_API_KEY → OPENROUTER_API_KEY → noop.
+
+# OPENAI_API_KEY=sk-...                          # Used for OpenAI-compatible embeddings today. PR #307 will extend this to chat completions (DeepSeek, SiliconFlow, vLLM, LM Studio, Ollama via `/v1`).
+# OPENAI_BASE_URL=https://api.openai.com         # Override for OpenAI-compatible providers
+
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_MODEL=claude-sonnet-4-20250514       # 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-2.5-flash                  # Default Gemini model (auto-detected GA model)
+
+# OPENROUTER_API_KEY=sk-or-...
+# OPENROUTER_MODEL=anthropic/claude-sonnet-4-20250514
+
+# MINIMAX_API_KEY=...
+# MINIMAX_MODEL=MiniMax-M2.7
+
+# MAX_TOKENS=4096                                # Cap LLM completion tokens for compression / summarise calls
+
+# 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 (#149 follow-up) when invoked from inside Claude Code.
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# FALLBACK_PROVIDERS=anthropic,gemini            # Comma-separated chain tried after the primary provider returns an error (e.g. rate limit)
+
+# -----------------------------------------------------------------------------
+# 2. Embedding provider — auto-detected, override via EMBEDDING_PROVIDER
+# -----------------------------------------------------------------------------
+#
+# Without an embedding key, agentmemory runs in BM25-only mode for hybrid
+# search. Detection order: EMBEDDING_PROVIDER override → GEMINI_API_KEY →
+# OPENAI_API_KEY → VOYAGE_API_KEY → COHERE_API_KEY → OPENROUTER_API_KEY →
+# local (Xenova/all-MiniLM-L6-v2, 384-dim).
+
+# 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_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.
+# Without a secret, REST endpoints are open on loopback. Set this when
+# you expose the daemon beyond loopback or run behind a reverse proxy.
+
+# AGENTMEMORY_SECRET=your-secret-here
+
+# -----------------------------------------------------------------------------
+# 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
+# TOKEN_BUDGET=2000                              # Max tokens injected via mem::context per session
+# MAX_OBS_PER_SESSION=500                        # Per-session observation cap before consolidation kicks in
+
+# -----------------------------------------------------------------------------
+# 5. Behaviour flags
+# -----------------------------------------------------------------------------
+
+# AGENTMEMORY_AUTO_COMPRESS=true                 # Run LLM compression on every observation batch (requires a provider key). Default off — synthetic compression handles most cases.
+# AGENTMEMORY_INJECT_CONTEXT=true                # Inject recalled memories back into agent prompts (#143). Default off — hooks capture observations but do not modify conversation.
+# CONSOLIDATION_ENABLED=true                     # Run the 4-tier consolidation pipeline (memories → semantic → procedural). Default off — opt in once you've measured the LLM cost.
+# 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=8                  # Memories per graph-extraction batch
+# AGENTMEMORY_REFLECT=true                       # Periodically auto-synthesize lessons from memories
+# AGENTMEMORY_DROP_STALE_INDEX=true              # Drop on-disk BM25 / vector index on startup if dim guard fires (#248). Recovery toggle for stuck-state debugging.
+# AGENTMEMORY_IMAGE_EMBEDDINGS=true              # Enable image embeddings when an image provider is present (experimental).
+
+# -----------------------------------------------------------------------------
+# 6. CLI / runtime knobs
+# -----------------------------------------------------------------------------
+
+# AGENTMEMORY_TOOLS=all                          # core (7 tools, default) | all (51 tools) — surface exposed to MCP clients
+# AGENTMEMORY_SLOTS=memory                       # Comma-separated plugin slot names the CLI should claim
+# 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_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`
+# AGENTMEMORY_EXPORT_ROOT=~/agentmemory-backup   # Default destination for `agentmemory export`
+
+# 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 + stream_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 port (also affects viewer at +2)
+# III_STREAMS_PORT=3112                          # Streams API port
+# III_ENGINE_URL=ws://localhost:49134            # iii-engine WebSocket URL (used by the worker)
+
+# -----------------------------------------------------------------------------
+# 8. iii engine pin
+# -----------------------------------------------------------------------------
+#
+# agentmemory currently pins iii-engine to v0.11.2 — v0.11.6 introduces a
+# new sandbox-everything-via-`iii worker add` model that agentmemory
+# hasn't been refactored for yet. Override with AGENTMEMORY_III_VERSION
+# only after migrating to the sandbox model manually.
+
+# AGENTMEMORY_III_VERSION=0.11.2
+
+# -----------------------------------------------------------------------------
+# 9. Claude Code bridge (opt-in)
+# -----------------------------------------------------------------------------
+
+# CLAUDE_MEMORY_BRIDGE=true                      # Mirror compressed memories into Claude Code's CLAUDE.md
+# CLAUDE_PROJECT_PATH=/path/to/your/project      # Required when CLAUDE_MEMORY_BRIDGE=true
+# CLAUDE_MEMORY_LINE_BUDGET=200                  # Lines of memory CLAUDE.md should hold
+
+# -----------------------------------------------------------------------------
+# 10. Obsidian export (opt-in)
+# -----------------------------------------------------------------------------
+
+# OBSIDIAN_AUTO_EXPORT=true                      # Auto-export memories to an Obsidian vault on every consolidation

package/README.md

@@ -77,17 +77,32 @@ agentmemory works with any agent that supports hooks, MCP, or REST API. All agen
 <td align="center" width="12.5%">
 <a href="https://claude.com/product/claude-code"><img src="https://matthiasroder.com/content/images/2026/01/Claude.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
 <strong>Claude Code</strong><br/>
-<sub>12 hooks + MCP + skills</sub>
+<sub>native plugin + 12 hooks + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
+<strong>Codex CLI</strong><br/>
+<sub>native plugin + 6 hooks + MCP</sub>
 </td>
 <td align="center" width="12.5%">
 <a href="integrations/openclaw/"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /></a><br/>
 <strong>OpenClaw</strong><br/>
-<sub>MCP + <a href="integrations/openclaw/">plugin</a></sub>
+<sub>native plugin + MCP</sub>
 </td>
 <td align="center" width="12.5%">
 <a href="integrations/hermes/"><img src="https://github.com/NousResearch.png?size=120" alt="Hermes" width="48" height="48" /></a><br/>
 <strong>Hermes</strong><br/>
-<sub>MCP + <a href="integrations/hermes/">plugin</a></sub>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="integrations/pi/"><img src="assets/agents/pi.svg" alt="pi" width="48" height="48" /></a><br/>
+<strong>pi</strong><br/>
+<sub>native plugin + MCP</sub>
+</td>
+<td align="center" width="12.5%">
+<a href="https://github.com/tinyhumansai/openhuman"><img src="https://raw.githubusercontent.com/tinyhumansai/openhuman/main/app/src-tauri/icons/128x128.png" alt="OpenHuman" width="48" height="48" /></a><br/>
+<strong>OpenHuman</strong><br/>
+<sub>native Memory trait backend</sub>
 </td>
 <td align="center" width="12.5%">
 <a href="https://cursor.com"><img src="https://www.freelogovectors.net/wp-content/uploads/2025/06/cursor-logo-freelogovectors.net_.png" alt="Cursor" width="48" height="48" /></a><br/>
@@ -99,23 +114,18 @@ agentmemory works with any agent that supports hooks, MCP, or REST API. All agen
 <strong>Gemini CLI</strong><br/>
 <sub>MCP server</sub>
 </td>
+</tr>
+<tr>
 <td align="center" width="12.5%">
 <a href="https://github.com/opencode-ai/opencode"><img src="https://github.com/opencode-ai.png?size=120" alt="OpenCode" width="48" height="48" /></a><br/>
 <strong>OpenCode</strong><br/>
 <sub>MCP server</sub>
 </td>
 <td align="center" width="12.5%">
-<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
-<strong>Codex CLI</strong><br/>
-<sub>6 hooks + MCP + skills</sub>
-</td>
-<td align="center" width="12.5%">
 <a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
 <strong>Cline</strong><br/>
 <sub>MCP server</sub>
 </td>
-</tr>
-<tr>
 <td align="center" width="12.5%">
 <a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
 <strong>Goose</strong><br/>
@@ -146,16 +156,6 @@ agentmemory works with any agent that supports hooks, MCP, or REST API. All agen
 <strong>Roo Code</strong><br/>
 <sub>MCP server</sub>
 </td>
-<td align="center" width="12.5%">
-<a href="https://github.com/anthropics/claude-agent-sdk-typescript"><img src="https://github.com/anthropics.png?size=120" alt="Claude SDK" width="48" height="48" /></a><br/>
-<strong>Claude SDK</strong><br/>
-<sub>AgentSDKProvider</sub>
-</td>
-<td align="center" width="12.5%">
-<img src="https://img.shields.io/badge/104-endpoints-1f6feb?style=flat-square" alt="REST API" width="48" /><br/>
-<strong>Any agent</strong><br/>
-<sub>REST API</sub>
-</td>
 </tr>
 </table>
 
@@ -368,7 +368,7 @@ codex plugin install agentmemory
 
 The Codex plugin ships from the same `plugin/` directory as the Claude Code plugin. It registers:
 
-- `@agentmemory/mcp` as an MCP server (all 51 tools when `AGENTMEMORY_TOOLS=all`)
+- `@agentmemory/mcp` as an MCP server (proxies all 51 tools when `AGENTMEMORY_URL` points at a running agentmemory server; falls back to 7 tools locally when no server is reachable)
 - 6 lifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
 - 4 skills: `/recall`, `/remember`, `/session-history`, `/forget`
 
@@ -457,6 +457,30 @@ The agentmemory entry is the **same MCP server block** across every host that us
 
 **Sandboxed MCP clients** (Flatpak / Snap / restrictive containers) that can't reach the host's `localhost`: also set `"AGENTMEMORY_FORCE_PROXY": "1"` in the `env` block, and point `AGENTMEMORY_URL` at a route the sandbox can actually reach (e.g. your LAN IP). See [#234](https://github.com/rohitg00/agentmemory/issues/234) for the diagnostic walkthrough.
 
+### Programmatic access (Python / Rust / Node)
+
+agentmemory registers its core operations as iii functions (`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`). Any language with an iii SDK can call them directly over `ws://localhost:49134` — no separate REST client per language.
+
+```bash
+pip install iii-sdk         # Python
+cargo add iii-sdk           # Rust
+npm  install iii-sdk        # Node
+```
+
+```python
+from iii import register_worker
+
+iii = register_worker("ws://localhost:49134")
+iii.connect()
+
+iii.trigger({
+    "function_id": "mem::smart-search",
+    "payload": {"project": "demo", "query": "how do tokens refresh"},
+})
+```
+
+Worked example: [`examples/python/`](examples/python/) (quickstart + observation/recall flow). REST on `:3111` remains available for hosts without an iii runtime.
+
 ### From source
 
 ```bash
@@ -529,6 +553,44 @@ npx -y @agentmemory/mcp
 
 ---
 
+<h2 id="deploy">Deploy</h2>
+
+One-click templates for managed hosts. Each one ships a self-contained
+Dockerfile that pulls `@agentmemory/agentmemory` from npm and copies
+the iii engine binary in from the official `iiidev/iii` Docker Hub
+image — no pre-built agentmemory image required. Persistent storage
+mounts at `/data`; the first-boot entrypoint overwrites the
+npm-bundled iii config (which binds `127.0.0.1`) with a deploy-tuned
+one that binds `0.0.0.0` and uses absolute `/data` paths, generates
+the HMAC secret, then drops privileges from `root` to `node` via
+`gosu` before exec'ing the agentmemory CLI.
+
+<p>
+  <a href="https://fly.io/launch?repo=https://github.com/rohitg00/agentmemory&path=deploy/fly"><img src="https://img.shields.io/badge/Deploy%20to-fly.io-8b5cf6?style=for-the-badge&logo=fly.io&logoColor=white" alt="Deploy to fly.io" /></a>
+  <a href="https://railway.com/new/template?template=https%3A%2F%2Fgithub.com%2Frohitg00%2Fagentmemory&rootDirectory=deploy%2Frailway"><img src="https://img.shields.io/badge/Deploy%20to-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white" alt="Deploy to Railway" /></a>
+</p>
+
+Render's one-click deploy button requires `render.yaml` at the repository root, which we deliberately keep clean. Use the Render Blueprint flow documented in [`deploy/render/`](./deploy/render/README.md) to point at the in-repo blueprint manually.
+
+Full setup details (HMAC capture, viewer SSH tunnel, rotation, backup,
+cost floors) live in [`deploy/`](./deploy/README.md):
+
+- [`deploy/fly`](./deploy/fly/README.md) — single machine with
+  `auto_stop_machines = "stop"`; cheapest idle.
+- [`deploy/railway`](./deploy/railway/README.md) — Hobby plan flat fee,
+  volume in the dashboard.
+- [`deploy/render`](./deploy/render/README.md) — Blueprint flow,
+  automatic disk snapshots on paid plans.
+- [`deploy/coolify`](./deploy/coolify/README.md) — self-hosted on your
+  own VPS via [Coolify](https://coolify.io/self-hosted); same Docker
+  Compose stack, you own the host and the data.
+
+Only port `3111` is published. The viewer on `3113` stays bound to
+loopback inside the container — every template's README documents the
+SSH-tunnel pattern for reaching it.
+
+---
+
 <h2 id="why-agentmemory"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-why.svg"><img src="assets/tags/section-why.svg" alt="Why agentmemory" height="32" /></picture></h2>
 
 Every coding agent forgets everything when the session ends. You waste the first 5 minutes of every session re-explaining your stack. agentmemory runs in the background and eliminates that entirely.
@@ -644,6 +706,8 @@ Triple-stream retrieval combining three signals:
 
 Fused with Reciprocal Rank Fusion (RRF, k=60) and session-diversified (max 3 results per session).
 
+BM25 tokenizes Greek, Cyrillic, Hebrew, Arabic, and accented Latin out of the box. For Chinese / Japanese / Korean memories, install the optional segmenters (`npm install @node-rs/jieba tiny-segmenter`) to split CJK runs into word-level tokens; without them, agentmemory soft-falls to whole-run tokenization and prints a one-time hint on stderr.
+
 ### Embedding providers
 
 agentmemory auto-detects your provider. For best results, install local embeddings (free):
@@ -655,7 +719,7 @@ npm install @xenova/transformers
 | Provider | Model | Cost | Notes |
 |---|---|---|---|
 | **Local (recommended)** | `all-MiniLM-L6-v2` | Free | Offline, +8pp recall over BM25-only |
-| Gemini | `text-embedding-004` | Free tier | 1500 RPM |
+| Gemini | `gemini-embedding-001` | Free tier | 100+ languages, 768/1536/3072 dims (MRL), 2048-token input. Replaces `text-embedding-004` ([deprecated, shutdown Jan 14, 2026](https://ai.google.dev/gemini-api/docs/deprecations)) |
 | OpenAI | `text-embedding-3-small` | $0.02/1M | Highest quality |
 | Voyage AI | `voyage-code-3` | Paid | Optimized for code |
 | Cohere | `embed-english-v3.0` | Free trial | General purpose |
@@ -667,6 +731,8 @@ npm install @xenova/transformers
 
 51 tools, 6 resources, 3 prompts, and 4 skills — the most comprehensive MCP memory toolkit for any agent.
 
+> **MCP shim vs full server:** the published `@agentmemory/mcp` package is a thin shim. It exposes the full 51-tool surface **only when it can reach a running agentmemory server** via `AGENTMEMORY_URL` (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`). The `AGENTMEMORY_TOOLS=core|all` env var is a *server-side* flag — setting it in the shim's `env` block has no effect. If you see only 7 tools in Cursor / OpenCode / Gemini CLI, start `npx @agentmemory/agentmemory` (or the Docker stack) and set `AGENTMEMORY_URL=http://localhost:3111`.
+
 ### 50 Tools
 
 <details>

package/dist/.env.example

@@ -0,0 +1,167 @@
+# =============================================================================
+# 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.
+#
+# Every line is OFF by default — `agentmemory` runs out of the box with no
+# LLM key, no embedding key, and no API auth. Set keys here only when you
+# want to enable the corresponding feature.
+#
+# Run `npx @agentmemory/agentmemory init` to copy this file into place
+# automatically. Run `npx @agentmemory/agentmemory doctor` to verify that
+# the daemon reads the env you expect.
+#
+# Defaults shown in comments. Listed in priority order — the first key
+# present wins on the LLM detection path (see src/config.ts::detectProvider).
+
+# -----------------------------------------------------------------------------
+# 1. LLM provider — pick ONE
+# -----------------------------------------------------------------------------
+#
+# Without a provider key, agentmemory runs in noop mode: observations are
+# indexed via zero-LLM synthetic compression, hybrid search still works,
+# but LLM-backed summarisation / reflection / consolidation are disabled.
+# The detection order is OPENAI_API_KEY → MINIMAX_API_KEY → ANTHROPIC_API_KEY
+# → GEMINI_API_KEY → OPENROUTER_API_KEY → noop.
+
+# OPENAI_API_KEY=sk-...                          # Used for OpenAI-compatible embeddings today. PR #307 will extend this to chat completions (DeepSeek, SiliconFlow, vLLM, LM Studio, Ollama via `/v1`).
+# OPENAI_BASE_URL=https://api.openai.com         # Override for OpenAI-compatible providers
+
+# ANTHROPIC_API_KEY=sk-ant-...
+# ANTHROPIC_MODEL=claude-sonnet-4-20250514       # 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-2.5-flash                  # Default Gemini model (auto-detected GA model)
+
+# OPENROUTER_API_KEY=sk-or-...
+# OPENROUTER_MODEL=anthropic/claude-sonnet-4-20250514
+
+# MINIMAX_API_KEY=...
+# MINIMAX_MODEL=MiniMax-M2.7
+
+# MAX_TOKENS=4096                                # Cap LLM completion tokens for compression / summarise calls
+
+# 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 (#149 follow-up) when invoked from inside Claude Code.
+# AGENTMEMORY_ALLOW_AGENT_SDK=true
+
+# FALLBACK_PROVIDERS=anthropic,gemini            # Comma-separated chain tried after the primary provider returns an error (e.g. rate limit)
+
+# -----------------------------------------------------------------------------
+# 2. Embedding provider — auto-detected, override via EMBEDDING_PROVIDER
+# -----------------------------------------------------------------------------
+#
+# Without an embedding key, agentmemory runs in BM25-only mode for hybrid
+# search. Detection order: EMBEDDING_PROVIDER override → GEMINI_API_KEY →
+# OPENAI_API_KEY → VOYAGE_API_KEY → COHERE_API_KEY → OPENROUTER_API_KEY →
+# local (Xenova/all-MiniLM-L6-v2, 384-dim).
+
+# 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_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.
+# Without a secret, REST endpoints are open on loopback. Set this when
+# you expose the daemon beyond loopback or run behind a reverse proxy.
+
+# AGENTMEMORY_SECRET=your-secret-here
+
+# -----------------------------------------------------------------------------
+# 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
+# TOKEN_BUDGET=2000                              # Max tokens injected via mem::context per session
+# MAX_OBS_PER_SESSION=500                        # Per-session observation cap before consolidation kicks in
+
+# -----------------------------------------------------------------------------
+# 5. Behaviour flags
+# -----------------------------------------------------------------------------
+
+# AGENTMEMORY_AUTO_COMPRESS=true                 # Run LLM compression on every observation batch (requires a provider key). Default off — synthetic compression handles most cases.
+# AGENTMEMORY_INJECT_CONTEXT=true                # Inject recalled memories back into agent prompts (#143). Default off — hooks capture observations but do not modify conversation.
+# CONSOLIDATION_ENABLED=true                     # Run the 4-tier consolidation pipeline (memories → semantic → procedural). Default off — opt in once you've measured the LLM cost.
+# 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=8                  # Memories per graph-extraction batch
+# AGENTMEMORY_REFLECT=true                       # Periodically auto-synthesize lessons from memories
+# AGENTMEMORY_DROP_STALE_INDEX=true              # Drop on-disk BM25 / vector index on startup if dim guard fires (#248). Recovery toggle for stuck-state debugging.
+# AGENTMEMORY_IMAGE_EMBEDDINGS=true              # Enable image embeddings when an image provider is present (experimental).
+
+# -----------------------------------------------------------------------------
+# 6. CLI / runtime knobs
+# -----------------------------------------------------------------------------
+
+# AGENTMEMORY_TOOLS=all                          # core (7 tools, default) | all (51 tools) — surface exposed to MCP clients
+# AGENTMEMORY_SLOTS=memory                       # Comma-separated plugin slot names the CLI should claim
+# 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_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`
+# AGENTMEMORY_EXPORT_ROOT=~/agentmemory-backup   # Default destination for `agentmemory export`
+
+# 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 + stream_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 port (also affects viewer at +2)
+# III_STREAMS_PORT=3112                          # Streams API port
+# III_ENGINE_URL=ws://localhost:49134            # iii-engine WebSocket URL (used by the worker)
+
+# -----------------------------------------------------------------------------
+# 8. iii engine pin
+# -----------------------------------------------------------------------------
+#
+# agentmemory currently pins iii-engine to v0.11.2 — v0.11.6 introduces a
+# new sandbox-everything-via-`iii worker add` model that agentmemory
+# hasn't been refactored for yet. Override with AGENTMEMORY_III_VERSION
+# only after migrating to the sandbox model manually.
+
+# AGENTMEMORY_III_VERSION=0.11.2
+
+# -----------------------------------------------------------------------------
+# 9. Claude Code bridge (opt-in)
+# -----------------------------------------------------------------------------
+
+# CLAUDE_MEMORY_BRIDGE=true                      # Mirror compressed memories into Claude Code's CLAUDE.md
+# CLAUDE_PROJECT_PATH=/path/to/your/project      # Required when CLAUDE_MEMORY_BRIDGE=true
+# CLAUDE_MEMORY_LINE_BUDGET=200                  # Lines of memory CLAUDE.md should hold
+
+# -----------------------------------------------------------------------------
+# 10. Obsidian export (opt-in)
+# -----------------------------------------------------------------------------
+
+# OBSIDIAN_AUTO_EXPORT=true                      # Auto-export memories to an Obsidian vault on every consolidation