@agentmemory/agentmemory 0.9.31 → 0.9.32

package/.env.example

@@ -13,14 +13,19 @@
 # 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.
 
@@ -124,7 +127,7 @@
 # AGENTMEMORY_GRAPH_WEIGHT=0.2                   # Graph traversal bonus on smart-search ranking
 # AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false       # Report boot compaction as off (otherwise deferred; manual maintenance only)
 # 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.
 

package/AGENTS.md

@@ -101,17 +101,17 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).
 
 ## Testing
 
-- Before every commit run, in order: `npm run build`, `npm run skills:gen`, `npm run docs:sync`, `npm run skills:check`, `npm test` (4,000+ tests). Commit anything the generators changed. CI runs the same build, skills check and tests.
+- Before every commit run, in order: `npm run build`, `npm run skills:gen`, `npm run docs:sync`, `npm run skills:check`, `npm test` (4,400+ tests). Commit anything the generators changed. CI runs the same build, skills check and tests.
 - Before any npm publish: `npm run release:gate` must pass. It installs the packed tarballs into a clean home and runs capture, recovery, restart, export/import, MCP and status checks against the installed CLI (see CONTRIBUTING.md, Release process)
 - Mock pattern: `vi.mock("iii-sdk")` with mock `sdk.trigger`, `kv.get/set/list`
 - Test files go in `test/` with `.test.ts` extension
 - Follow existing patterns in `test/crystallize.test.ts` for function tests
 
-## Current Stats (v0.9.31)
+## Current Stats (v0.9.32)
 
 - 54 MCP tools visible by default; `AGENTMEMORY_TOOLS=core` selects 8 essentials
-- 146 REST endpoints
+- 147 REST endpoints
 - 6 MCP resources, 3 MCP prompts
 - 12 hooks, 17 skills
 - 322+ iii functions
-- 4,000+ tests
+- 4,400+ tests