@agentmemory/agentmemory 0.9.12 → 0.9.13

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

@@ -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 |

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

package/dist/cli.mjs

@@ -110,6 +110,7 @@ Usage: agentmemory [command] [options]
 
 Commands:
   (default)          Start agentmemory worker
+  init               Copy bundled .env.example to ~/.agentmemory/.env if absent
   status             Show connection status, memory count, flags, and health
   doctor             Run diagnostic checks (server, flags, graph, providers)
   demo               Seed sample sessions and show recall in action
@@ -361,12 +362,12 @@ async function main() {
 	p.intro("agentmemory");
 	if (skipEngine) {
 		p.log.info("Skipping engine check (--no-engine)");
-		await import("./src-Cqsy23f_.mjs");
+		await import("./src-Ca9oX6Hq.mjs");
 		return;
 	}
 	if (await isEngineRunning()) {
 		p.log.success("iii-engine is running");
-		await import("./src-Cqsy23f_.mjs");
+		await import("./src-Ca9oX6Hq.mjs");
 		return;
 	}
 	if (!await startEngine()) {
@@ -410,7 +411,7 @@ async function main() {
 		process.exit(1);
 	}
 	s.stop("iii-engine is ready");
-	await import("./src-Cqsy23f_.mjs");
+	await import("./src-Ca9oX6Hq.mjs");
 }
 async function apiFetch(base, path, timeoutMs = 5e3) {
 	try {
@@ -732,6 +733,50 @@ async function runDemoSearch(base, query) {
 		topTitle: items[0]?.title ?? "(no results)"
 	};
 }
+function findEnvExample() {
+	const candidates = [
+		join(__dirname, "..", ".env.example"),
+		join(__dirname, ".env.example"),
+		join(process.cwd(), ".env.example")
+	];
+	for (const c of candidates) if (existsSync(c)) return c;
+	return null;
+}
+async function runInit() {
+	p.intro("agentmemory init");
+	const target = join(homedir(), ".agentmemory", ".env");
+	const template = findEnvExample();
+	if (!template) {
+		p.log.error("Could not locate .env.example in the package. Re-install with: npm i -g @agentmemory/agentmemory");
+		process.exit(1);
+	}
+	const dir = dirname(target);
+	const { mkdir, copyFile } = await import("node:fs/promises");
+	const { constants: fsConstants } = await import("node:fs");
+	try {
+		await mkdir(dir, { recursive: true });
+		await copyFile(template, target, fsConstants.COPYFILE_EXCL);
+	} catch (err) {
+		if (err?.code === "EEXIST") {
+			p.log.warn(`${target} already exists — leaving it untouched.`);
+			p.log.info(`Compare against the latest template: diff ${target} ${template}`);
+			p.outro("Nothing changed.");
+			return;
+		}
+		p.log.error(`Failed to copy template: ${err instanceof Error ? err.message : String(err)}`);
+		process.exit(1);
+	}
+	p.log.success(`Wrote ${target}`);
+	p.note([
+		"All keys are commented out by default. Uncomment the ones you want.",
+		"",
+		"Common next steps:",
+		"  1. Pick an LLM provider key (ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / etc.)",
+		"  2. Run `npx @agentmemory/agentmemory doctor` to verify the daemon sees them",
+		"  3. Run `npx @agentmemory/agentmemory` to start the worker"
+	].join("\n"), "Next steps");
+	p.outro(`Edit ${target} and you're set.`);
+}
 async function runDemo() {
 	const port = getRestPort();
 	const base = `http://localhost:${port}`;
@@ -872,7 +917,7 @@ async function runUpgrade() {
 	].join("\n"), "agentmemory upgrade");
 }
 async function runMcp() {
-	await import("./standalone-DNt6O3zG.mjs");
+	await import("./standalone-BpbiNqr9.mjs");
 }
 async function runImportJsonl() {
 	const VALUE_FLAGS = new Set(["--port", "--tools"]);
@@ -977,6 +1022,7 @@ async function runImportJsonl() {
 	}
 }
 ({
+	init: runInit,
 	status: runStatus,
 	doctor: runDoctor,
 	demo: runDemo,