@agentmemory/agentmemory 0.9.30 → 0.9.32

package/dist/.env.example

@@ -5,22 +5,27 @@
 # 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.
+# 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. Listed in priority order — the first key
-# present wins on the LLM detection path (see src/config.ts::detectProvider).
+# 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 — pick ONE
+# 1. LLM provider: off unless you choose one
 # -----------------------------------------------------------------------------
 #
-# Without a provider key, agentmemory runs in noop mode: observations are
+# 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;
@@ -39,13 +44,12 @@
 # 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
-# The detection order is OPENAI_API_KEY → MINIMAX_API_KEY → ANTHROPIC_API_KEY
-# → GEMINI_API_KEY → OPENROUTER_API_KEY → noop.
+# 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-...                          # Activates both the OpenAI-compatible LLM provider (DeepSeek, SiliconFlow, vLLM, LM Studio, Ollama via `/v1`) and OpenAI embeddings. Set OPENAI_API_KEY_FOR_LLM=false to scope it to embeddings only.
+# 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
-# OPENAI_API_KEY_FOR_LLM=false                   # Skip OpenAI auto-detection for LLM; key stays active for embeddings
 
 # ANTHROPIC_API_KEY=sk-ant-...
 # ANTHROPIC_MODEL=claude-sonnet-5                # Default Anthropic model
@@ -74,18 +78,17 @@
 # Stop-hook recursion 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)
+# 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 — auto-detected, override via EMBEDDING_PROVIDER
+# 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. Remote
-# provider detection order: EMBEDDING_PROVIDER override → GEMINI_API_KEY →
-# OPENAI_API_KEY → VOYAGE_API_KEY → COHERE_API_KEY → OPENROUTER_API_KEY →
-# BM25-only. Local embeddings are an explicit opt-in, not the keyless default.
+# 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.
 
@@ -108,10 +111,10 @@
 # -----------------------------------------------------------------------------
 #
 # 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.
+# 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 ~/.agentmemory/secret on first start when unset
+# 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
 
@@ -122,9 +125,9 @@
 # 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       # Skip the one-time background trim of oversized graph provenance at startup
+# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false       # Report boot compaction as off (otherwise deferred; manual maintenance only)
 # TOKEN_BUDGET=2000                              # Max tokens injected via mem::context per session
-# MAX_OBS_PER_SESSION=500                        # Per-session observation cap before consolidation kicks in
+# 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.
 
@@ -133,11 +136,11 @@
 # -----------------------------------------------------------------------------
 
 # 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                # Inject recalled memories back into agent prompts. 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.
+# 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.
+# 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=8                  # Memories per graph-extraction batch
+# 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
@@ -145,7 +148,7 @@
 # the model think (default).
 # AGENTMEMORY_LLM_NOTHINK=1
 
-# AGENTMEMORY_REFLECT=true                       # Periodically auto-synthesize lessons from memories
+# 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.
@@ -155,37 +158,39 @@
 # 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.
-# AGENTMEMORY_VIEWER_STREAM_MAX=500              # Max items kept in the persisted "viewer" live-stream group; older entries are pruned in batches. Floored at 200 (the viewer's reload window); negative values fall back to the default
 
 # -----------------------------------------------------------------------------
 # 6. CLI / runtime knobs
 # -----------------------------------------------------------------------------
 
 # AGENTMEMORY_TOOLS=core                         # all (54 tools, default) | core (8 tools): surface exposed to MCP clients
-# AGENTMEMORY_SLOTS=memory                       # Comma-separated plugin slot names the CLI should claim
+# 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_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`, used by native and
-# Docker starts. Explicit flag/env wins. Otherwise instance 0 reuses an
-# existing ./data/state_store.db or ./data/iii-config.yaml before defaults: macOS
+# 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_III_CONFIG=/path/to/iii-config.yaml  # Engine config the CLI starts from; the bundled default binds 127.0.0.1
-# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000    # How often the engine writes state to disk; a crash loses at most this much
-# AGENTMEMORY_USE_DOCKER=1                      # Prefer bundled Docker even when a compatible native iii binary exists
-# AGENTMEMORY_EXPORT_ROOT=~/agentmemory-backup   # Default destination for `agentmemory export`
+# 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 — storage adapter for iii-state and iii-stream, see README "Storage backend"
+# 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 + stream_store.
+# Snapshot exporter — periodic snapshots of state_store.
 # SNAPSHOT_ENABLED=true
 # SNAPSHOT_DIR=~/.agentmemory/snapshots
 # SNAPSHOT_INTERVAL=3600                         # Seconds between snapshots
@@ -200,24 +205,20 @@
 # -----------------------------------------------------------------------------
 
 # III_REST_PORT=3111                             # REST API + MCP HTTP anchor
-# III_STREAM_PORT=3112                           # Preferred streams override; defaults to REST + 1
-# III_STREAMS_PORT=3112                          # Legacy alias for III_STREAM_PORT
 # 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 3211/3212/3213/49234 and an instance-1 data subdir.
+# `--instance 1` selects REST/viewer/engine ports 3211/3213/49234 and an instance-1 data subdir.
 
 # -----------------------------------------------------------------------------
 # 8. iii engine pin
 # -----------------------------------------------------------------------------
 #
-# agentmemory pins iii-engine to the same release as its iii-sdk dependency
-# (v0.22.1). The worker speaks the wire protocol of that engine, so the two move
-# together in agentmemory releases. Override with AGENTMEMORY_III_VERSION only
-# if you run your own engine and know it matches.
-
-# AGENTMEMORY_III_VERSION=0.22.1
+# agentmemory pins iii-engine and its iii-sdk dependencies to v0.25.0.
+# The CLI downloads the engine into ~/.agentmemory/bin on macOS/Linux.
+# Native Windows requires installing the matching iii.exe manually.
+# AGENTMEMORY_III_VERSION=0.25.0                # Override only when deliberately matching a different engine
 
 # Engine usage telemetry (iii). Off unless you set it; true opts in.
 # III_TELEMETRY_ENABLED=false
@@ -229,14 +230,22 @@
 # 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                      # Mirror compressed memories into Claude Code's CLAUDE.md
+# 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                  # Lines of memory CLAUDE.md should hold
+# 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)

package/dist/cli.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";iBAsYsB,kBAAA,CAAA,GAAsB,OAAA"}
+{"version":3,"file":"cli.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";iBAkZsB,kBAAA,CAAA,GAAsB,OAAA"}