myagentmemory 0.4.17 → 0.5.2

package/README.md

@@ -1,45 +1,54 @@
 # AgentMemory
 
-**Memory that survives the agent.** AgentMemory is a local, user-owned state layer for [Claude Code](https://claude.ai/code), [OpenAI Codex](https://github.com/openai/codex), [Cursor](https://cursor.com), and Agent (Cursor CLI). Keep scratch work, daily evidence, topic notes, and durable decisions as plain Markdown, then retrieve what matters with optional [qmd](https://github.com/tobi/qmd) search.
+**Your agent forgets everything. AgentMemory doesn't.**
+
+Every new session with [Claude Code](https://claude.ai/code), [Codex](https://github.com/openai/codex), or [Cursor](https://cursor.com) starts cold — the decisions you made yesterday are gone, and you explain them again. AgentMemory gives your agents a persistent, local, plain-Markdown memory that survives across sessions and models.
+
+```bash
+npm install -g myagentmemory
+agent-memory setup     # one-shot: memory dir, skills, hooks, MCP, local Pro preview
+```
+
+Then open your agent and ask *"what do you remember about me?"* — that's the wow.
 
 [![npm version](https://img.shields.io/npm/v/myagentmemory?color=cb3837&logo=npm)](https://www.npmjs.com/package/myagentmemory)
 [![npm downloads](https://img.shields.io/npm/dm/myagentmemory?color=cb3837&logo=npm)](https://www.npmjs.com/package/myagentmemory)
 [![license](https://img.shields.io/npm/l/myagentmemory)](LICENSE)
 [![website](https://img.shields.io/badge/website-jayzeng.github.io%2Fagentmemory-0d9b7a)](https://jayzeng.github.io/agentmemory/)
 
-[Website and quickstart](https://jayzeng.github.io/agentmemory/) · [Field report: lessons from 1,000+ coding-agent sessions](https://www.jayzeng.com/writing/agentmemory-field-report/) · [Install](#installation) · [CLI commands](#cli-commands) · [How it works](#how-it-works)
+[Website and quickstart](https://jayzeng.github.io/agentmemory/) · [Field report: 1,000+ coding-agent sessions](https://www.jayzeng.com/writing/agentmemory-field-report/) · [Install](#installation) · [CLI commands](#cli-commands) · [How it works](#how-it-works)
 
-> **Field report:** “A session records what the agent did. Memory is a judgment about what the next agent should know.” Read [What 1000+ coding agent sessions taught me about LLM memory](https://www.jayzeng.com/writing/agentmemory-field-report/).
+## Why AgentMemory
 
-## Why AgentMemory?
+- AgentMemory injects your decisions, scratchpad, and daily log at session start — no copy-paste, no re-explaining.
+- Repeated corrections become durable memory you can inspect and undo (Pro).
+- Every memory is a plain Markdown file you own. Memory content, session content, queries, and repository paths stay on this machine.
 
-Coding-agent sessions preserve activity. They do not decide which facts, decisions, and follow-ups should remain useful tomorrow. AgentMemory gives that accumulated state explicit lifetimes, a user-controlled home, and a path back into future work.
+AgentMemory does not provide a Python SDK, does not provide a vector database, and does not provide a knowledge graph. It is a local Markdown store with a CLI, agent skills, and optional full-text and semantic search via [qmd](https://github.com/tobi/qmd). See [product boundary](docs/product-boundary.md) for full scope.
 
-- **Different lifetimes and scopes** — route short-lived follow-ups, chronological evidence, continuing topics, and durable decisions to the right destination.
-- **Curated continuity** — retain judgments that should affect future work instead of warehousing every transcript and abandoned path.
-- **Plain Markdown, local-first** — read, edit, diff, back up, or delete every memory. No database, cloud service, or lock-in.
-- **Optional retrieval** — skills load base context at session start and search related memories explicitly when a task needs them; qmd adds keyword, semantic, and hybrid search.
-- **Shared across agents** — Claude Code, Codex, Cursor, and Agent can use the same store even as models and harnesses change.
-- **Correctable state** — provenance, temporal status, secret screening, supersession, and forgetting help keep retained memory aligned with reality.
+> **Field report:** "A session records what the agent did. Memory is a judgment about what the next agent should know." Read [What 1,000+ coding agent sessions taught me about LLM memory](https://www.jayzeng.com/writing/agentmemory-field-report/).
 
-> **Naming:** `agentmemory` is the GitHub repo (and Homebrew tap), `myagentmemory` is the npm package, and `agent-memory` is the installed CLI binary. Also known as *coding agent memory* or *AI coding memory*.
+> **Naming:** `agentmemory` is the GitHub repo (and Homebrew tap), `myagentmemory` is the npm package, and `agent-memory` is the installed CLI binary. Free and MIT-licensed. See [product boundary](docs/product-boundary.md) for what it isn't.
 
-### Product boundary
+### AgentMemory Pro preview
 
-AgentMemory is free, open-source software under the MIT License. The core is a local Markdown store with a CLI, optional qmd search, and agent skills, and it remains fully usable without an account or commercial plugin. It does not automatically import every vendor transcript or silently decide what becomes durable. It is not a Python SDK, vector database, or knowledge graph. The Markdown files remain the source of truth.
+**Core remembers what you save. Pro learns from what you do.** Core remains free, MIT-licensed, and useful forever. Pro adds three things:
 
-### AgentMemory Pro preview
+- **Remember past sessions** — ask *"what did we decide about auth?"* across Claude Code, Codex, and Cursor.
+- **Learn from your patterns** — turn repeated corrections into memory you can inspect and undo.
+- **Private by default** — memory and session content index locally. Pro installation uses a pseudonymous installation identifier and bounded compatibility metadata, never your memory or session content.
 
-**Core remembers what you save. Pro learns from what you do.** Core remains free, MIT-licensed, and useful forever. Pro is a separately distributed commercial bundle that recalls prior coding sessions, finds repeated corrections, and shows what it learned and why in a private local Memory Dashboard.
+Preview what Pro would find in your existing sessions *before* installing anything:
 
 ```bash
-agent-memory pro install
+agent-memory pro preview        # local-only scan, previews up to 50 sessions/day
+agent-memory pro install        # free preview, no account required
 agent-memory recall "what did we decide about authentication?"
 agent-memory learn
 agent-memory dashboard
 ```
 
-The preview requires no account, email, or payment method. It includes 10 useful recalls and one learning scan per local day; local indexing and the Memory Dashboard remain available. Coding history, memories, queries, repository paths, and raw session identifiers stay on the device. Installation sends only a random installation identifier plus bounded compatibility metadata to obtain the signed release. Paying will remove limits; it will not unlock access to the user's own local data. Low-level `agent-memory plugin` commands remain available for administration and scripting. See [how local privacy, signing, installation, and capability enforcement work](docs/official-plugin-bootstrap.md).
+Pre-install preview: up to 50 local sessions per day. Free installed preview: 20 recalls + 5 learning scans per local day. Memory, session, query, and repository content stay on your machine; installation sends only a pseudonymous identifier and bounded compatibility metadata. Full detail on [privacy, signing, and installation](docs/official-plugin-bootstrap.md).
 
 ## Installation
 
@@ -58,11 +67,8 @@ npm install -g myagentmemory
 bun run build:cli
 # => produces dist/agent-memory
 
-# Initialize memory directory
-agent-memory init
-
-# Install skill files for Claude Code, Codex, Cursor, and Agent
-agent-memory install-skills
+# One-shot setup: memory dir, qmd collection, skills, hooks, MCP registration, local Pro preview
+agent-memory setup
 
 # Uninstall skill files
 agent-memory uninstall-skills
@@ -70,6 +76,8 @@ agent-memory uninstall-skills
 
 The npm package installs a platform-neutral Node.js executable. The optional Homebrew and `build:cli` paths use a native binary built for the current platform.
 
+`agent-memory setup` is the recommended entry point — it is idempotent, so re-running it after an upgrade or a partial install is always safe. Pass `--skip-skills`, `--skip-hooks`, `--skip-plugin`, or `--skip-mcp` to opt out of individual steps, or `--yes --json` for scripted/CI installs. If you want the older step-by-step interactive wizard instead, `agent-memory init` still works.
+
 `install-skills` writes a SKILL.md into each agent's config directory:
 - `~/.claude/skills/agent-memory/SKILL.md` — Claude Code skill
 - `~/.codex/skills/agent-memory/SKILL.md` — Codex skill
@@ -86,7 +94,7 @@ If you're on Pi and prefer a native extension, use `pi-memory` (https://github.c
 
 ### Optional: Enable search with qmd
 
-When qmd is installed, the collection is automatically set up via `agent-memory init`.
+When qmd is installed, the collection is automatically set up via `agent-memory setup` (or `init`).
 
 Note: `memory_search` **semantic**/**deep** modes require vector embeddings. If you see a warning like "need embeddings", run `qmd embed` once and retry.
 
@@ -144,27 +152,39 @@ The memory directory defaults to `~/.agent-memory/`. Override with `AGENT_MEMORY
 
 ## CLI Commands
 
+Run `agent-memory help` for the full generated list, or `agent-memory <command> --help` for a command's flags and examples.
+
 | Command | Purpose |
 |---------|---------|
-| `agent-memory context [--query <text>] [--no-search]` | Build context and optionally include qmd matches for a query |
-| `agent-memory write --target <long_term\|daily\|topic> --content <text> [--mode append\|overwrite] [--source-uri <uri>] [--topic <name>] [--date YYYY-MM-DD]` | Write to memory files with optional provenance |
+| `agent-memory setup [--yes] [--skip-skills] [--skip-hooks] [--skip-plugin] [--skip-mcp]` | One-shot idempotent installer: memory dir + skills + hooks + local Pro preview + MCP registration |
+| `agent-memory context [--query <text>] [--no-search] [--layer stable\|dynamic\|full]` | Build context and optionally include qmd matches for a query |
+| `agent-memory save "<text>"` | Shortcut: append a daily memory entry |
+| `agent-memory note "<text>"` | Shortcut: add a scratchpad checklist item |
+| `agent-memory write "<text>" --target <long_term\|daily\|topic> [--mode append\|overwrite] [--source-uri <uri>] [--topic <name>] [--date YYYY-MM-DD]` | Write to memory files with optional provenance |
 | `agent-memory read --target <long_term\|scratchpad\|daily\|list\|topic\|topics> [--date YYYY-MM-DD] [--topic <name>]` | Read memory files |
 | `agent-memory scratchpad <add\|done\|undo\|clear_done\|list> [--text <text>]` | Manage checklist |
-| `agent-memory search --query <text> [--mode keyword\|semantic\|deep] [--limit N]` | Search via qmd |
-| `agent-memory install-skills` | Install bundled SKILL.md files into local agent directories |
+| `agent-memory search --query <text> [--mode keyword\|semantic\|deep] [--limit N]` | Search indexed memory via qmd |
+| `agent-memory distil [--dry-run]` | Rebuild a compact MEMORY.md index from logs and topics |
+| `agent-memory sync` | Update the qmd index and semantic embeddings |
+| `agent-memory install-skills [--uninstall]` | Install bundled SKILL.md files into local agent directories |
 | `agent-memory uninstall-skills` | Uninstall bundled SKILL.md files from local agent directories |
 | `agent-memory completion [bash\|zsh\|fish\|powershell] [--stdout]` | Install or print shell completion |
-| `agent-memory install-hooks [--yes] [--only <agents>]` | Install managed session-start memory hooks |
+| `agent-memory install-hooks [--yes] [--all] [--only <agents>] [--mode stable\|per-turn]` | Install managed context and memory-write reminder hooks |
 | `agent-memory uninstall-hooks [--only <agents>]` | Remove only hooks managed by AgentMemory |
-| `agent-memory init` | Create dirs, detect qmd, setup collection |
-| `agent-memory status` | Show config, qmd status, file counts |
-| `agent-memory pro <install\|status\|upgrade\|manage>` | Install and manage the no-account AgentMemory Pro preview |
+| `agent-memory init [--yes] [--skip-skills] [--skip-hooks]` | Legacy interactive wizard; `setup` runs this as its first step |
+| `agent-memory status [--probe]` | Show config, qmd status, file counts, embedding health |
+| `agent-memory doctor` | One-shot health check across memory, qmd, skills, hooks, and Pro |
+| `agent-memory tutorial` | Guided 3-minute walkthrough in a throwaway sandbox |
+| `agent-memory pro <install\|preview\|status\|upgrade\|manage>` | Install and manage the no-account AgentMemory Pro preview |
 | `agent-memory recall <query>` | Recall decisions and context from prior coding sessions with Pro |
-| `agent-memory learn` | Find repeated corrections worth remembering with Pro |
-| `agent-memory dashboard` | Open the private local Memory Dashboard |
+| `agent-memory learn [--preview]` | Find repeated corrections worth remembering with Pro |
+| `agent-memory dashboard [--no-browser]` | Open the private local Memory Dashboard |
 | `agent-memory plugin <list\|status\|install\|update\|uninstall\|manage>` | Discover and manage optional signed first-party plugins |
+| `agent-memory serve --mcp [--register]` | Run as a Model Context Protocol (MCP) server over stdio |
+| `agent-memory upgrade [--check] [--cli\|--plugin] [--yes]` | Check for and install newer CLI/Pro releases |
+| `agent-memory version` | Print the installed version |
 
-Global flags: `--dir <path>` (override directory), `--json` (machine output)
+Global flags: `--dir <path>` (override directory), `--json` (machine output), `--help`, `--version`
 
 ### memory_search modes
 
@@ -215,13 +235,15 @@ The context builder emits the following sections in priority order. Installed sk
 
 Total output, including headings and truncation notices, is hard-capped at 16,000 characters. Explicitly untrusted, expired, superseded, revoked, or retired blocks are excluded; legacy secret-like values are redacted before injection. When qmd is unavailable, the relevant-memory step is skipped and the rest still works.
 
-Claude Code loads base context through the skill's shell injection. Codex, Cursor, and Agent run the same base command at session start. The bundled skills use explicit search when a task relates to prior work; they make no host-level guarantee of automatic retrieval.
+Supported detected hosts can receive managed automatic context hooks after `agent-memory install-hooks`; Claude Code also receives a periodic memory-write reminder. Bundled skills remain the portable fallback and use explicit search when a task relates to prior work.
+
+`context --layer` can request a subset instead of the full six-section build: `stable` (scratchpad + topics + MEMORY.md — durable facts unlikely to change with the current prompt), `dynamic` (today's log + qmd search + yesterday's log — turn-scoped, prompt-dependent), or `full` (default, all six sections). This backs the hook system's two install modes (`install-hooks --mode stable|per-turn` / `AGENT_MEMORY_HOOK_MODE`): `per-turn` (the default) installs a SessionStart hook that loads the `stable` layer once plus a UserPromptSubmit hook that reloads the `dynamic` layer every turn; `stable` mode installs SessionStart only, loading the `full` context once per session.
 
 ### Selective injection
 
-When qmd is available and `context --query` is supplied, the CLI sanitizes the query, limits it to 200 characters, and includes the top three keyword results with the standard context. Programmatic integrations should spawn the CLI with an argument array so query text is not evaluated by a shell.
+When qmd is available and `context --query` is supplied, the CLI sanitizes the query, limits it to 200 characters, and runs one fused `qmd` query (BM25 + vector, reciprocal-rank-fused server-side) against the current prompt, including the top three hits with the standard context. Programmatic integrations should spawn the CLI with an argument array so query text is not evaluated by a shell.
 
-The search has a 3-second timeout and fails silently. If qmd is down or the query returns nothing, injection falls back to the standard behavior.
+The search has an 8-second timeout and fails silently. If qmd is down or the query returns nothing, injection falls back to the standard behavior.
 
 ### Provenance, temporal state, and secret screening
 
@@ -245,7 +267,7 @@ These are content conventions, not enforced metadata. qmd's full-text indexing m
 
 - **Persistence**: Memory files are plain markdown on disk — readable, editable, and git-friendly.
 - **Tool response previews**: Write/scratchpad tools return size-capped previews instead of full file contents.
-- **qmd auto-setup**: Via `agent-memory init`, the collection and path contexts are created automatically.
+- **qmd auto-setup**: Via `agent-memory setup` (or `init`), the collection and path contexts are created automatically.
 - **qmd re-indexing**: After every write, a debounced `qmd update` runs in the background (fire-and-forget, non-blocking) unless disabled via `AGENT_MEMORY_QMD_UPDATE`.
 - **qmd embeddings**: Semantic/deep search needs vector embeddings. If you see "need embeddings" warnings, run `qmd embed` once and retry.
 - **Graceful degradation**: If qmd is not installed, core tools work fine. `memory_search` returns install instructions.
@@ -256,7 +278,10 @@ These are content conventions, not enforced metadata. qmd's full-text indexing m
 |----------|--------|---------|-------------|
 | `AGENT_MEMORY_DIR` | path | `~/.agent-memory` | Memory directory |
 | `AGENT_MEMORY_QMD_UPDATE` | `background`, `manual`, `off` | `background` | Controls automatic `qmd update` after writes |
+| `AGENT_MEMORY_QMD_EMBED` | `background`, `manual`, `off` | `background` | Controls automatic embedding generation after `init`/`setup` |
 | `AGENT_MEMORY_PLUGIN_DIR` | path | `~/.agent-memory/system/plugins` | Machine-local official plugin installation root; independent of `AGENT_MEMORY_DIR` |
+| `AGENT_MEMORY_HOOK_MODE` | `stable`, `per-turn` | `per-turn` | SessionStart-only vs. SessionStart + UserPromptSubmit hook installation |
+| `AGENT_MEMORY_SKILLS_ROOT` | path | auto-detected | Override where `install-skills`/`setup` look for the bundled `skills/` directory |
 
 ## Running tests
 
@@ -309,38 +334,10 @@ Publication is tag-driven through `.github/workflows/publish-npm.yml`. Configure
 
 AgentMemory contains portions adapted from [pi-mem](https://github.com/jo-inc/pi-mem), used under its MIT License; the upstream copyright notice is preserved in [LICENSE](LICENSE). Semantic search is powered by [qmd](https://github.com/tobi/qmd).
 
-## Changelog
-
-### 0.4.12
+## Copyright and commercial licensing
 
-- **Removed pi extension**: Removed `index.ts` and all pi-specific code (`@mariozechner/pi-ai`, `@mariozechner/pi-coding-agent`, `@sinclair/typebox` peer dependencies).
-- **Standalone tool functions**: Extracted `memoryWrite()`, `memoryRead()`, `scratchpadAction()`, `memorySearch()` into `src/core.ts` as standalone functions usable without any framework.
-- **Renamed package**: `pi-memory` → `myagentmemory` (npm); the CLI binary is `agent-memory`.
-- **Renamed env var**: `PI_MEMORY_QMD_UPDATE` → `AGENT_MEMORY_QMD_UPDATE` (old name still works as fallback).
-- **Default memory directory**: Now always `~/.agent-memory/`.
-- **Removed pi-specific tests**: Deleted `test/e2e.ts`, `test/eval-recall.ts`, `test/unit.ts`.
+AgentMemory Core is released under the MIT License. Jay Zeng retains copyright in his original contributions and may also offer commercial products or differently licensed versions of code for which he holds the necessary rights. Existing MIT grants remain valid, and adapted upstream portions remain subject to their preserved copyright notices and license terms.
 
-### 0.4.0
-
-- **Multi-platform support**: Memory system now works with Claude Code and OpenAI Codex via CLI + skills, in addition to pi.
-- **Extracted shared core**: `src/core.ts` contains platform-agnostic logic (paths, truncation, scratchpad, context builder, qmd) with zero pi peer dependencies.
-- **CLI binary**: `agent-memory` CLI with subcommands: `context`, `write`, `read`, `scratchpad`, `search`, `init`, `status`.
-- **Skill files**: `skills/claude-code/SKILL.md` and `skills/codex/SKILL.md` for installation into respective platforms.
-- **Configurable memory directory**: `AGENT_MEMORY_DIR` env var or `--dir` flag (default: `~/.agent-memory/`).
-- **CLI tests**: `test/cli.test.ts` with unit and subprocess tests.
-
-### 0.2.0
-
-- **Selective injection**: Before each turn, the user's prompt is searched against memory via qmd. Top results are injected into the system prompt alongside standard context, surfacing relevant past decisions without explicit tool calls.
-- **qmd auto-setup**: The extension automatically creates the collection and path contexts on session start when qmd is available. No manual `qmd collection add` needed.
-- **Tags and links**: `memory_write` and context injection now encourage `#tags` and `[[wiki-links]]` as searchable content conventions.
-- **Context priority reordering**: Injection order is now scratchpad > today > search results > MEMORY.md > yesterday.
-- **Unit tests**: Added deterministic tests (no LLM/qmd needed).
-- **Recall eval**: Added recall effectiveness evaluation.
-
-### 0.1.0
+## Changelog
 
-- Initial release: `memory_write`, `memory_read`, `scratchpad`, `memory_search` tools.
-- Context injection of MEMORY.md, scratchpad, and today/yesterday daily logs.
-- qmd integration for keyword, semantic, and hybrid search.
-- Debounced background `qmd update` after writes.
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.

package/dist/cli-spec.d.ts

@@ -6,7 +6,7 @@ export interface CliOptionSpec {
         kind: CliValueKind;
     };
 }
-export declare const COMMANDS: readonly ["context", "write", "read", "scratchpad", "search", "distil", "sync", "init", "status", "install-skills", "uninstall-skills", "install-hooks", "uninstall-hooks", "completion", "pro", "recall", "learn", "dashboard", "plugin", "version", "help"];
+export declare const COMMANDS: readonly ["context", "save", "note", "write", "read", "scratchpad", "search", "distil", "sync", "setup", "status", "doctor", "tutorial", "install-skills", "uninstall-skills", "install-hooks", "uninstall-hooks", "completion", "pro", "recall", "learn", "dashboard", "plugin", "serve", "upgrade", "version", "help"];
 export declare const PLUGIN_COMMANDS: readonly ["list", "status", "install", "update", "uninstall", "manage"];
 export declare const WORKER_ACTIONS: readonly [];
 export declare const SCRATCHPAD_ACTIONS: readonly ["add", "done", "undo", "clear_done", "list"];
@@ -23,3 +23,9 @@ export declare const OPTION_SPECS: Record<string, CliOptionSpec>;
 export declare const SHELL_DESCRIPTIONS: Record<string, string>;
 export declare function optionDescription(option: string): string;
 export declare function optionTakesValue(option: string): boolean;
+/**
+ * Render per-command help using existing spec metadata. Called when the user
+ * runs `agent-memory <cmd> --help` — should list the command's real flags with
+ * descriptions and one or two concrete examples, not the top-level command list.
+ */
+export declare function renderCommandHelp(command: string): string;

package/dist/cli-spec.js

@@ -1,13 +1,17 @@
 export const COMMANDS = [
     "context",
+    "save",
+    "note",
     "write",
     "read",
     "scratchpad",
     "search",
     "distil",
     "sync",
-    "init",
+    "setup",
     "status",
+    "doctor",
+    "tutorial",
     "install-skills",
     "uninstall-skills",
     "install-hooks",
@@ -18,6 +22,8 @@ export const COMMANDS = [
     "learn",
     "dashboard",
     "plugin",
+    "serve",
+    "upgrade",
     "version",
     "help",
 ];
@@ -26,24 +32,30 @@ export const WORKER_ACTIONS = [];
 export const SCRATCHPAD_ACTIONS = ["add", "done", "undo", "clear_done", "list"];
 export const COMMAND_DESCRIPTIONS = {
     context: "build context from scratchpad, logs, topics, and long-term memory",
+    save: 'shortcut: agent-memory save "<text>" → daily memory entry',
+    note: 'shortcut: agent-memory note "<text>" → scratchpad checklist item',
     write: "append or overwrite a daily, topic, or long-term memory entry",
     read: "read daily, topic, scratchpad, or long-term memory",
     scratchpad: "add, complete, reopen, list, or clear persistent checklist items",
     search: "search indexed memory with keyword, semantic, or deep qmd modes",
     distil: "rebuild a compact MEMORY.md index from logs and topics",
     sync: "update the qmd index and semantic embeddings",
-    init: "create memory storage and configure qmd when available",
+    setup: "one-shot idempotent installer: init + skills + hooks + plugin + mcp",
     status: "show memory paths, file counts, qmd, and embedding health",
+    doctor: "run a one-shot health check across memory, qmd, skills, hooks, and Pro",
+    tutorial: "guided 3-minute walkthrough in a throwaway sandbox",
     "install-skills": "install core instructions for detected agents",
     "uninstall-skills": "remove core instructions from detected agents",
-    "install-hooks": "install automatic SessionStart indexing and context hooks",
-    "uninstall-hooks": "remove only SessionStart hooks managed by agent-memory",
+    "install-hooks": "install managed context and memory-write reminder hooks",
+    "uninstall-hooks": "remove only hooks managed by agent-memory",
     completion: "install or print Bash, Zsh, Fish, or PowerShell completion",
     pro: "install, inspect, or upgrade AgentMemory Pro",
     recall: "recall decisions and context from prior coding sessions with Pro",
     learn: "find repeated corrections worth remembering with Pro",
     dashboard: "open the private local Memory Dashboard",
     plugin: "discover, install, update, or remove optional official plugins",
+    serve: "run as a Model Context Protocol (MCP) server over stdio",
+    upgrade: "check for and install newer agent-memory CLI and Pro plugin releases",
     version: "print the installed agent-memory version",
     help: "show this command overview",
 };
@@ -65,24 +77,41 @@ export const SCRATCHPAD_ACTION_DESCRIPTIONS = {
 };
 export const GLOBAL_OPTIONS = ["--dir", "--json", "--help", "--version", "-h", "-V"];
 export const COMMAND_OPTIONS = {
-    context: ["--query", "--no-search"],
+    context: ["--query", "--no-search", "--layer"],
+    save: ["--target"],
+    note: [],
     write: ["--content", "--target", "--mode", "--topic", "--date", "--source-uri"],
     read: ["--target", "--date", "--topic"],
     scratchpad: ["--text"],
     search: ["--query", "--mode", "--limit"],
     distil: ["--dry-run"],
     sync: [],
-    init: [],
+    init: ["--yes", "--skip-skills", "--skip-hooks"],
+    setup: ["--yes", "--skip-skills", "--skip-hooks", "--skip-plugin", "--skip-mcp"],
     status: ["--probe"],
-    "install-skills": [],
+    doctor: [],
+    tutorial: [],
+    "install-skills": ["--uninstall"],
     "uninstall-skills": [],
-    "install-hooks": ["--yes", "--all", "--only"],
+    "install-hooks": ["--yes", "--all", "--only", "--mode"],
     "uninstall-hooks": ["--only"],
     completion: ["--stdout"],
     pro: [],
-    recall: ["--scope", "--cwd", "--limit", "--context"],
-    learn: [],
+    recall: [
+        "--scope",
+        "--cwd",
+        "--limit",
+        "--context",
+        "--queries",
+        "--multi",
+        "--sessions",
+        "--events",
+        "--per-query",
+    ],
+    learn: ["--preview"],
     dashboard: ["--no-browser"],
+    serve: ["--mcp", "--register", "--only"],
+    upgrade: ["--check", "--refresh", "--yes", "--quiet", "--cli", "--plugin"],
     version: [],
     help: [],
 };
@@ -93,6 +122,12 @@ export const PLUGIN_COMMAND_OPTIONS = {
     update: ["--channel"],
     uninstall: ["--yes"],
     manage: ["--no-browser"],
+    // Plugin runtime commands forwarded to the installed bundle
+    index: ["--date", "--since"],
+    recall: ["--query", "--limit", "--cwd", "--host", "--mode"],
+    worker: ["--token"],
+    learn: ["--limit", "--dry-run"],
+    eval: ["--limit"],
 };
 export const WORKER_ACTION_OPTIONS = {};
 export const SCRATCHPAD_ACTION_OPTIONS = {
@@ -113,7 +148,14 @@ export const OPTION_SPECS = {
     "--no-search": { description: "build context without invoking qmd" },
     "--content": { description: "memory entry content to persist", value: { label: "text", kind: "value" } },
     "--target": { description: "memory destination or collection to read", value: { label: "target", kind: "value" } },
-    "--mode": { description: "write behavior or qmd search strategy", value: { label: "mode", kind: "value" } },
+    "--mode": {
+        description: "write behavior, qmd search strategy, or hook mode (stable|per-turn)",
+        value: { label: "mode", kind: "value" },
+    },
+    "--layer": {
+        description: "context layer to emit: stable, dynamic, or full (default)",
+        value: { label: "layer", kind: "value" },
+    },
     "--topic": { description: "topic name used to resolve a topic file", value: { label: "name", kind: "value" } },
     "--date": { description: "daily-log date in YYYY-MM-DD form", value: { label: "date", kind: "value" } },
     "--source-uri": {
@@ -132,8 +174,13 @@ export const OPTION_SPECS = {
     "--state": { description: "override the plugin state root", value: { label: "directory", kind: "directory" } },
     "--with-plugin": { description: "include both the core and optional plugin skills" },
     "--plugin-only": { description: "operate only on the optional plugin skill" },
-    "--yes": { description: "apply eligible hook changes without confirmation" },
+    "--yes": { description: "apply eligible changes without interactive prompts" },
     "--all": { description: "apply eligible hook changes without confirmation" },
+    "--skip-skills": { description: "init: don't prompt to install agent skills" },
+    "--skip-hooks": { description: "init: don't prompt to install SessionStart hooks" },
+    "--skip-plugin": { description: "setup: don't offer to install the paid plugin bundle" },
+    "--skip-mcp": { description: "setup: don't register the MCP server in detected local harnesses" },
+    "--preview": { description: "learn: show detected patterns without writing or consuming quota" },
     "--only": {
         description: "restrict hook changes to comma-separated agent keys",
         value: { label: "agents", kind: "value" },
@@ -156,6 +203,23 @@ export const OPTION_SPECS = {
         description: "surrounding events included with each recall hit",
         value: { label: "number", kind: "number" },
     },
+    "--queries": {
+        description: "JSON array of query strings for one-shot multi-query recall",
+        value: { label: "json", kind: "value" },
+    },
+    "--multi": { description: "treat each positional argument as a separate recall query" },
+    "--sessions": {
+        description: "maximum sessions returned by multi-query recall",
+        value: { label: "number", kind: "number" },
+    },
+    "--events": {
+        description: "top events per session returned by multi-query recall",
+        value: { label: "number", kind: "number" },
+    },
+    "--per-query": {
+        description: "candidate hits considered per query before fusion",
+        value: { label: "number", kind: "number" },
+    },
     "--pi": { description: "override the Pi session root", value: { label: "directory", kind: "directory" } },
     "--codex": { description: "override the Codex session root", value: { label: "directory", kind: "directory" } },
     "--claude": {
@@ -208,6 +272,13 @@ export const OPTION_SPECS = {
     "--agent": { description: "internal SessionStart host key", value: { label: "agent", kind: "value" } },
     "--token": { description: "internal session-worker lease token", value: { label: "token", kind: "value" } },
     "--uninstall": { description: "use install-skills compatibility uninstall mode" },
+    "--mcp": { description: "serve as an MCP server over stdio (used by Claude Code)" },
+    "--register": { description: "register the MCP server in detected supported agents and exit" },
+    "--check": { description: "upgrade: report available updates without installing" },
+    "--refresh": { description: "upgrade: force a live registry lookup and rewrite the 24h cache" },
+    "--quiet": { description: "upgrade: suppress non-error output (used by the passive session-start refresh)" },
+    "--cli": { description: "upgrade: limit action to the CLI binary" },
+    "--plugin": { description: "upgrade: limit action to the Pro plugin bundle" },
 };
 export const SHELL_DESCRIPTIONS = {
     bash: "generate or install Bash completion",
@@ -221,3 +292,134 @@ export function optionDescription(option) {
 export function optionTakesValue(option) {
     return OPTION_SPECS[option]?.value !== undefined;
 }
+// One-line usage template per command — shows the shape agents/humans should type.
+const COMMAND_USAGE = {
+    context: 'agent-memory context [--query "text"] [--no-search] [--json]',
+    save: 'agent-memory save "<text>" [--target daily|topic|long_term]',
+    note: 'agent-memory note "<text>"',
+    write: 'agent-memory write "<text>" [--target daily|topic|long_term] [--mode append|overwrite] [--topic <name>] [--date YYYY-MM-DD]',
+    read: "agent-memory read [--target daily|topic|long_term|scratchpad] [--date YYYY-MM-DD] [--topic <name>]",
+    scratchpad: 'agent-memory scratchpad <add|done|undo|clear_done|list> [--text "text"]',
+    search: 'agent-memory search --query "text" [--mode keyword|semantic|deep] [--limit N]',
+    distil: "agent-memory distil [--dry-run]",
+    sync: "agent-memory sync",
+    init: "agent-memory init [--yes] [--skip-skills] [--skip-hooks]",
+    setup: "agent-memory setup [--yes] [--json]",
+    status: "agent-memory status [--probe] [--json]",
+    doctor: "agent-memory doctor [--json]",
+    tutorial: "agent-memory tutorial",
+    "install-skills": "agent-memory install-skills [--json]",
+    "uninstall-skills": "agent-memory uninstall-skills [--json]",
+    "install-hooks": "agent-memory install-hooks [--yes] [--all] [--only claude,codex,cursor] [--mode stable|per-turn] [--json]",
+    "uninstall-hooks": "agent-memory uninstall-hooks [--only claude,codex,cursor] [--json]",
+    completion: "agent-memory completion [bash|zsh|fish|powershell] [--stdout]",
+    pro: "agent-memory pro <install|status|upgrade> [--channel stable] [--yes]",
+    recall: 'agent-memory recall "<query>" [--limit N] [--context N] [--scope current|global] [--cwd <path>] [--json]\n  Multi-query: agent-memory recall --queries \'["q1","q2","q3"]\' [--sessions N] [--events N]',
+    learn: "agent-memory learn [--preview] [--json]",
+    dashboard: "agent-memory dashboard [--no-browser]",
+    plugin: "agent-memory plugin <list|status|install|update|uninstall|manage> [--channel stable] [--yes] [--no-browser]",
+    upgrade: "agent-memory upgrade [--check] [--yes] [--cli|--plugin] [--refresh] [--json]",
+    version: "agent-memory version",
+    help: "agent-memory help [<command>]",
+};
+// Concrete examples per command — what an agent or dev is most likely to want.
+const COMMAND_EXAMPLES = {
+    save: [
+        'agent-memory save "shipped the new recall path — bundle at 1.2.3"',
+        'agent-memory save --target long_term "prefer bun test over npm test in example-api"',
+    ],
+    note: ['agent-memory note "verify the digest backfill against a real corpus"'],
+    write: [
+        'agent-memory write "keep sessions in reverse-chron order" --target long_term --mode overwrite',
+        'agent-memory write "half-line summary" --target topic --topic scheduling-machine',
+    ],
+    read: [
+        "agent-memory read --target long_term",
+        "agent-memory read --target daily --date 2026-08-24",
+        "agent-memory read --target topic --topic scheduling-machine",
+    ],
+    scratchpad: [
+        'agent-memory scratchpad add --text "chase down the flake in test/web.test.ts"',
+        'agent-memory scratchpad done --text "chase down the flake"',
+        "agent-memory scratchpad list",
+    ],
+    search: [
+        'agent-memory search --query "API test collection credentials"',
+        'agent-memory search --query "grafana alert routing" --mode semantic --limit 10',
+    ],
+    recall: [
+        'agent-memory recall "API test collection for booking service"',
+        'agent-memory recall --queries \'["API test collection for booking service","booking client integration","client credential setup"]\' --sessions 5',
+        'agent-memory recall "auth refresh" --scope current --limit 5',
+    ],
+    context: ["agent-memory context", 'agent-memory context --query "grafana alerts" --json'],
+    status: ["agent-memory status", "agent-memory status --json"],
+    init: ["agent-memory init", "agent-memory init --yes --skip-hooks"],
+    setup: ["agent-memory setup", "agent-memory setup --json"],
+    "install-hooks": [
+        "agent-memory install-hooks",
+        "agent-memory install-hooks --yes",
+        "agent-memory install-hooks --only claude,codex",
+        "agent-memory install-hooks --mode stable  # SessionStart only (skip UserPromptSubmit)",
+    ],
+    distil: ["agent-memory distil", "agent-memory distil --dry-run"],
+    learn: ["agent-memory learn", "agent-memory learn --preview  # see patterns without consuming quota or writing"],
+};
+/**
+ * Render per-command help using existing spec metadata. Called when the user
+ * runs `agent-memory <cmd> --help` — should list the command's real flags with
+ * descriptions and one or two concrete examples, not the top-level command list.
+ */
+export function renderCommandHelp(command) {
+    const canonical = command === "distill" ? "distil" : command;
+    const known = new Set([...COMMANDS, "distill", "setup"]);
+    if (!known.has(canonical)) {
+        return `agent-memory: unknown command '${command}'. Run 'agent-memory help' for the full list.`;
+    }
+    const description = COMMAND_DESCRIPTIONS[canonical] ??
+        (canonical === "setup" ? "one-shot idempotent installer: init + skills + hooks + plugin + mcp" : "");
+    const usage = COMMAND_USAGE[canonical] ?? `agent-memory ${canonical} [options]`;
+    const options = COMMAND_OPTIONS[canonical] ?? [];
+    const examples = COMMAND_EXAMPLES[canonical] ?? [];
+    const optLines = [];
+    // Command-specific options
+    for (const opt of options) {
+        const spec = OPTION_SPECS[opt];
+        if (!spec)
+            continue;
+        const label = spec.value ? `${opt} <${spec.value.label}>` : opt;
+        optLines.push(`  ${label.padEnd(24)}  ${spec.description}`);
+    }
+    // Global options that are always available
+    const globalKeys = ["--dir", "--json", "--help", "--version"];
+    const globalLines = globalKeys
+        .map((opt) => {
+        const spec = OPTION_SPECS[opt];
+        if (!spec)
+            return "";
+        const label = spec.value ? `${opt} <${spec.value.label}>` : opt;
+        return `  ${label.padEnd(24)}  ${spec.description}`;
+    })
+        .filter(Boolean);
+    // Command-specific subactions
+    let subactionLines = "";
+    if (canonical === "scratchpad") {
+        subactionLines = `\nActions:\n${SCRATCHPAD_ACTIONS.map((a) => `  ${a.padEnd(24)}  ${SCRATCHPAD_ACTION_DESCRIPTIONS[a]}`).join("\n")}\n`;
+    }
+    if (canonical === "plugin" || canonical === "pro") {
+        subactionLines = `\nSubcommands:\n${PLUGIN_COMMANDS.map((a) => `  ${a.padEnd(24)}  ${PLUGIN_COMMAND_DESCRIPTIONS[a]}`).join("\n")}\n`;
+    }
+    const parts = [`agent-memory ${canonical} — ${description}`, "", "Usage:", `  ${usage}`];
+    if (subactionLines)
+        parts.push(subactionLines);
+    if (optLines.length)
+        parts.push("\nOptions:", ...optLines);
+    if (globalLines.length)
+        parts.push("\nGlobal:", ...globalLines);
+    if (examples.length) {
+        parts.push("\nExamples:");
+        for (const ex of examples)
+            parts.push(`  $ ${ex}`);
+    }
+    return parts.join("\n");
+}