@agentmemory/agentmemory 0.9.28 → 0.9.30

package/dist/.env.example

@@ -9,9 +9,9 @@
 # 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.
+# 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).
@@ -21,27 +21,45 @@
 # -----------------------------------------------------------------------------
 #
 # Without a provider key, agentmemory runs in noop mode: observations are
-# indexed via zero-LLM synthetic compression, hybrid search still works,
+# 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
 # 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_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_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-4-20250514       # Default Anthropic model
+# 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-2.5-flash                  # Default Gemini model (auto-detected GA model)
+# GEMINI_MODEL=gemini-3.7-flash                  # Default Gemini model (current stable Flash)
 
 # OPENROUTER_API_KEY=sk-or-...
-# OPENROUTER_MODEL=anthropic/claude-sonnet-4-20250514
+# OPENROUTER_MODEL=anthropic/claude-sonnet-5
 
 # MINIMAX_API_KEY=...
-# MINIMAX_MODEL=MiniMax-M2.7
+# MINIMAX_MODEL=MiniMax-M3
 
 # MAX_TOKENS=4096                                # Cap LLM completion tokens for compression / summarise calls
 
@@ -53,7 +71,7 @@
 
 # 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.
+# 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)
@@ -62,10 +80,14 @@
 # 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 →
+# 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 →
-# local (Xenova/all-MiniLM-L6-v2, 384-dim).
+# BM25-only. Local embeddings are an explicit opt-in, 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
 
@@ -74,6 +96,8 @@
 # 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
 
@@ -87,7 +111,9 @@
 # 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
+# AGENTMEMORY_SECRET=your-secret   # generated into ~/.agentmemory/secret on first start when unset
+# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
+# AGENTMEMORY_IMPORT_ROOT=~/projects
 
 # -----------------------------------------------------------------------------
 # 4. Search tuning
@@ -96,6 +122,7 @@
 # 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
 # TOKEN_BUDGET=2000                              # Max tokens injected via mem::context per session
 # MAX_OBS_PER_SESSION=500                        # Per-session observation cap before consolidation kicks in
 # 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.
@@ -105,29 +132,56 @@
 # 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.
+# 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.
 # 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
+
+# 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                       # 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_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.
+# 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=all                          # core (7 tools, default) | all (51 tools) — surface exposed to MCP clients
+# 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_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`
+# 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
+# ~/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_STATE_BACKEND=redis                # file (default) | redis — storage adapter for iii-state and iii-stream, see README "Storage backend"
+# 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
 
@@ -145,23 +199,39 @@
 # 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)
+# 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.
 
 # -----------------------------------------------------------------------------
 # 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 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
+
+# Engine usage telemetry (iii). Off unless you set it; true opts in.
+# III_TELEMETRY_ENABLED=false
+
+# -----------------------------------------------------------------------------
+# 9. Session sweep
+# -----------------------------------------------------------------------------
 
-# AGENTMEMORY_III_VERSION=0.11.2
+# 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
 
 # -----------------------------------------------------------------------------
-# 9. Claude Code bridge (opt-in)
+# 10. Claude Code bridge (opt-in)
 # -----------------------------------------------------------------------------
 
 # CLAUDE_MEMORY_BRIDGE=true                      # Mirror compressed memories into Claude Code's CLAUDE.md
@@ -169,7 +239,7 @@
 # CLAUDE_MEMORY_LINE_BUDGET=200                  # Lines of memory CLAUDE.md should hold
 
 # -----------------------------------------------------------------------------
-# 10. Obsidian export (opt-in)
+# 11. Obsidian export (opt-in)
 # -----------------------------------------------------------------------------
 
 # OBSIDIAN_AUTO_EXPORT=true                      # Auto-export memories to an Obsidian vault on every consolidation

package/dist/cli.d.mts.map

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