@agentmemory/agentmemory 0.9.29 → 0.9.30

package/.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,8 +21,24 @@
 # -----------------------------------------------------------------------------
 #
 # 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.
 
@@ -55,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)
@@ -64,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
 
@@ -76,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
 
@@ -89,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
@@ -98,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.
@@ -107,8 +132,8 @@
 # 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
@@ -121,8 +146,16 @@
 # 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
@@ -135,8 +168,20 @@
 # 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
 
@@ -154,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
@@ -178,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/AGENTS.md

@@ -4,36 +4,26 @@
 
 agentmemory is a persistent memory system for AI coding agents, built on iii-engine's three primitives (Worker/Function/Trigger). Everything goes through `registerFunction`/`registerTrigger`/`sdk.trigger()` — never bypass iii-engine with standalone SQLite or in-process alternatives.
 
-- **Engine**: iii-sdk (WebSocket to iii-engine on port 49134)
+- **Engine**: iii-sdk 0.22.1 with @iii-dev/helpers 0.22.1 (WebSocket to iii-engine 0.22.1 on port 49134; the client type is `IIIClient`, HTTP requests are `HttpRequest` from `@iii-dev/helpers/http`)
 - **State**: File-based SQLite via iii-engine's StateModule (`./data/state_store.db`)
 - **Build**: TypeScript → ESM via tsdown, output to `dist/`
 - **Test**: vitest (`npm test` excludes integration tests)
 
 ## Consistency Rules
 
-**When adding or removing MCP tools, you MUST update ALL of the following:**
+**Before every commit, run `npm run docs:sync` and commit what it changes.** It computes MCP tool counts (all, core, local fallback), REST endpoints, skills, hooks, tests, iii functions, source files, lines of code and KV scopes from the source, and rewrites them in README.md, the translated READMEs, AGENTS.md, INSTALL_FOR_AGENTS.md, plugin manifests, integration READMEs, the stat badges and the `src/index.ts` banner. The last synced values live in `scripts/docs-sync.state.json`; commit that file with the rest. `npm run docs:check` exits non-zero when anything is out of date. When the sync prints `check <fact> <old> left in <file>`, open that line: either fix it by hand or add its noun to the fact in `scripts/docs-sync.ts` so the next sync catches it. Never hand-edit these numbers or versions in the docs; change the source and sync.
+
+**When adding or removing MCP tools, update:**
 1. `src/mcp/tools-registry.ts` — tool definition + `getAllTools()` array
 2. `src/mcp/server.ts` — handler case in the `mcp::tools::call` switch
 3. `src/triggers/api.ts` — REST endpoint registration
-4. `src/index.ts` — function registration + endpoint count in the log line
+4. `src/index.ts` — function registration
 5. `test/mcp-standalone.test.ts` — tool count assertion
-6. `README.md` — tool counts (search for "MCP tools")
-7. `plugin/.claude-plugin/plugin.json` — tool count in description
-8. `plugin/plugin.json` and `plugin/.mcp.copilot.json` (when present) — tool count or MCP exposure
 
-**When adding REST endpoints, you MUST update:**
+**When adding REST endpoints, update:**
 1. `src/triggers/api.ts` — endpoint registration
-2. `src/index.ts` — endpoint count in the log line
-3. `README.md` — endpoint count (search for "REST endpoints" and "endpoints on port")
-
-**When bumping version, you MUST update ALL of the following:**
-1. `package.json` — version field
-2. `src/version.ts` — VERSION constant and type union
-3. `src/types.ts` — ExportData version union
-4. `src/functions/export-import.ts` — supportedVersions set
-5. `test/export-import.test.ts` — version assertion
-6. `plugin/.claude-plugin/plugin.json` — version field
-7. `plugin/plugin.json` (when present) — version field
+
+**When bumping version, change only `package.json`.** `npm run docs:sync` carries the new version into `src/version.ts`, the `src/types.ts` ExportData union, the `supportedVersions` set in `src/functions/export-import.ts`, every plugin and package manifest that shared the old version, the deploy templates, the AGENTS.md stats heading, and CHANGELOG.md (the Unreleased section becomes the new version with today's date, plus its compare link).
 
 **When adding new KV scopes:**
 1. `src/state/schema.ts` — add to the KV object
@@ -59,7 +49,9 @@ sdk.registerFunction(
 
 ### REST Endpoint Registration
 ```typescript
-sdk.registerFunction("api::your-endpoint", async (req: ApiRequest) => {
+import type { HttpRequest } from "@iii-dev/helpers/http";
+
+sdk.registerFunction("api::your-endpoint", async (req: HttpRequest) => {
   const denied = checkAuth(req, secret);
   if (denied) return denied;
   const body = req.body as Record<string, unknown>;
@@ -109,16 +101,17 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).
 
 ## Testing
 
-- All tests must pass before PR: `npm test` (1,596+ tests)
+- Before every commit run, in order: `npm run build`, `npm run skills:gen`, `npm run docs:sync`, `npm run skills:check`, `npm test` (2,500+ 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.29)
+## Current Stats (v0.9.30)
 
 - 54 MCP tools (8 visible by default, `AGENTMEMORY_TOOLS=all` for all)
-- 130 REST endpoints
+- 138 REST endpoints
 - 6 MCP resources, 3 MCP prompts
 - 12 hooks, 17 skills
-- 260+ iii functions
-- 1,596+ tests
+- 311+ iii functions
+- 2,500+ tests