myagentmemory 0.4.12 → 0.4.14

package/README.md

@@ -1,10 +1,36 @@
-# agent-memory
+# AgentMemory
 
-Persistent memory for coding agents — [Claude Code](https://claude.ai/code), [OpenAI Codex](https://github.com/openai/codex), Cursor, and Agent (Cursor CLI). Semantic search powered by [qmd](https://github.com/tobi/qmd).
+**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.
 
-Thanks to https://github.com/skyfallsin/pi-mem for inspiration.
+[![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/)
 
-Long-term facts, daily logs, topic/event notes, and a scratchpad checklist stored as plain markdown files. Optional qmd integration adds keyword, semantic, and hybrid search across all memory files, plus automatic selective injection of relevant past memories into every turn.
+[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)
+
+> **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?
+
+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.
+
+- **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.
+
+> **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*.
+
+### Product boundary
+
+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.
+
+### Optional official plugins
+
+The MIT-licensed core can discover and host separately distributed, signed first-party plugins while remaining fully useful on its own. Optional plugins may use their own license and distribution terms; their implementation and browser assets are not part of the `myagentmemory` package. `agent-memory plugin list` and `plugin status` report local state. In an interactive terminal, `agent-memory plugin install` opens a nonce-bound loopback page for an email address, resumes the waiting command, verifies signed release metadata and the downloaded bundle, and installs atomically. This temporary beta grants unlimited local use. The email remains in a mode-0600 local activation record and is also sent with bounded activation metadata to the private commercial service; memory, sessions, queries, repository paths, IP addresses, and user-agent strings are not stored in the activation database. Authentication and payment will replace this temporary flow later. See the [official plugin bootstrap and host contract](docs/official-plugin-bootstrap.md).
 
 ## Installation
 
@@ -13,11 +39,11 @@ Long-term facts, daily logs, topic/event notes, and a scratchpad checklist store
 brew tap jayzeng/agentmemory https://github.com/jayzeng/agentmemory
 brew install jayzeng/agentmemory/agent-memory
 
-# Install the CLI globally
+# Install the portable CLI globally (Node.js 20+; macOS, Linux, or Windows)
 npm install -g myagentmemory
 
-# If you hit SSL errors due to corporate MITM/inspection, try:
-# npm config set strict-ssl false
+# If corporate TLS inspection requires a private CA, use your organization's CA file:
+# npm config set cafile /path/to/corporate-ca.pem
 
 # Or build from source
 bun run build:cli
@@ -33,11 +59,9 @@ agent-memory install-skills
 agent-memory uninstall-skills
 ```
 
-### Pi users
-
-If you're on Pi and prefer a native extension, use `pi-memory` (https://github.com/jayzeng/pi-memory) instead of installing this skill. The CLI + skill workflow here is the cross-platform alternative, and works fine on Pi without any extension.
+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.
 
-This installs:
+`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
 - `~/.cursor/skills/agent-memory/SKILL.md` — Cursor skill
@@ -47,6 +71,10 @@ This installs:
 - `%USERPROFILE%\.cursor\skills\agent-memory\SKILL.md` — Cursor skill (Windows)
 - `%USERPROFILE%\.agents\skills\agent-memory\SKILL.md` — Agent CLI skill (Windows)
 
+### Pi users
+
+If you're on Pi and prefer a native extension, use `pi-memory` (https://github.com/jayzeng/pi-memory) instead of installing this skill. The CLI + skill workflow here is the cross-platform alternative, and works fine on Pi without any extension.
+
 ### Optional: Enable search with qmd
 
 When qmd is installed, the collection is automatically set up via `agent-memory init`.
@@ -62,25 +90,45 @@ qmd embed
 
 Without qmd, all core tools (write/read/scratchpad) work normally. Only `memory_search` and selective injection require qmd.
 
-## Architecture
+## Memory lifecycle
+
+AgentMemory implements a state lifecycle rather than a transcript archive. Scratch, daily, topic, and durable memory are destinations for different needs—not mandatory steps through which every entry must pass.
+
+```
+Session / external evidence
+             │
+             ▼
+   Extract, qualify, or discard
+             │
+             ├── Scratch  — short-lived follow-ups
+             ├── Daily    — chronological evidence
+             ├── Topic    — continuing threads
+             └── Durable  — curated facts and decisions
+                                      │
+                                      ▼
+                    Retrieve · supersede · invalidate · forget
+```
+
+The files are the current implementation of this lifecycle. The durable state remains useful even if the agent, model, harness, or optional retriever changes. The [field report](https://www.jayzeng.com/writing/agentmemory-field-report/) explains the evidence and design lessons behind it.
+
+## Repository architecture
 
 ```
-  ┌──────────────┐
-  │  src/core.ts │  ← all logic (paths, truncation, scratchpad,
-  │              │    context builder, qmd, tool functions)
-  └──────┬───────┘
-         │
-    ┌────┴─────────────────┐
-    ▼                      ▼
-  ┌──────────┐   ┌──────────────┐
-  │ src/     │   │ skills/      │
-  │ cli.ts   │   │ ├─ claude-code/SKILL.md
-  │          │   │ ├─ codex/SKILL.md
-  │          │   │ ├─ cursor/SKILL.md
-  │          │   │ └─ agent/SKILL.md
-  └──────────┘   └──────────────┘
-   CLI binary     instruction files
-   `agent-memory` that invoke CLI
+  ┌───────────────┐
+  │  src/core.ts  │  ← all logic: paths, truncation, scratchpad,
+  └───────┬───────┘     context builder, qmd, tool functions
+          │
+     ┌────┴─────┐
+     ▼          ▼
+  ┌─────────┐   ┌─────────────────────────┐
+  │ src/    │   │ skills/                 │
+  │ cli.ts  │   │ ├─ claude-code/SKILL.md │
+  │         │   │ ├─ codex/SKILL.md       │
+  │         │   │ ├─ cursor/SKILL.md      │
+  │         │   │ └─ agent/SKILL.md       │
+  └─────────┘   └─────────────────────────┘
+   CLI command    instruction files
+  `agent-memory`  that invoke the CLI
 ```
 
 The memory directory defaults to `~/.agent-memory/`. Override with `AGENT_MEMORY_DIR` env var or `--dir` flag.
@@ -89,15 +137,19 @@ The memory directory defaults to `~/.agent-memory/`. Override with `AGENT_MEMORY
 
 | Command | Purpose |
 |---------|---------|
-| `agent-memory context [--no-search]` | Build & print context injection string to stdout |
-| `agent-memory write --target <long_term\|daily\|topic> --content <text> [--mode append\|overwrite] [--topic <name>] [--date YYYY-MM-DD]` | Write to memory files |
+| `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 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 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 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 plugin <list\|status\|install\|update\|uninstall\|manage>` | Discover and manage optional signed first-party plugins |
 
 Global flags: `--dir <path>` (override directory), `--json` (machine output)
 
@@ -115,14 +167,14 @@ If the first search doesn't find what you need, try rephrasing or switching mode
 
 ```
 ~/.agent-memory/
-  MEMORY.md              # Curated long-term memory
-  SCRATCHPAD.md           # Checklist of things to fix/remember
+  MEMORY.md                # Curated long-term memory
+  SCRATCHPAD.md            # Checklist of things to fix/remember
   daily/
-    2026-02-15.md         # Daily append-only log
+    2026-02-15.md          # Daily append-only log
     2026-02-14.md
     ...
   topics/
-    auth.md               # Topic/event log linked back to daily entries
+    auth.md                # Topic/event log linked back to daily entries
 ```
 
 ## Topic notes
@@ -139,25 +191,31 @@ agent-memory read --target topics
 
 ### Context injection
 
-Before every agent turn, the following are injected into the system prompt (in priority order):
+The context builder emits the following sections in priority order. Installed skills load base context at session start; callers can optionally supply `--query` to add relevant qmd results:
 
 1. **Open scratchpad items** (up to 2K chars)
 2. **Recent topic entries** (up to 2K chars) — most recent topic notes with backlinks
-3. **Today's daily log** (up to 3K chars, tail)
+3. **Today's daily log** (up to 3K chars, head + tail)
 4. **Relevant memories via qmd search** (up to 2.5K chars) — searches using the user's current prompt to surface related past context
 5. **MEMORY.md** (up to 4K chars, middle-truncated)
 6. **Yesterday's daily log** (up to 3K chars, tail — lowest priority, trimmed first)
 
-Total injection is capped at 16K chars. When qmd is unavailable, step 3 is skipped and the rest works as before.
+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.
 
-For Claude Code, context is injected via the `!`agent-memory context`` syntax in the SKILL.md. For Codex, Cursor, and Agent, the agent runs `agent-memory context` at session start.
+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.
 
 ### Selective injection
 
-When qmd is available, the system automatically searches memory using the user's prompt on demand (CLI). The top 3 keyword results are injected alongside the standard context.
+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.
 
 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.
 
+### Provenance, temporal state, and secret screening
+
+`write --source-uri <uri>` stores an addressable `Source:` line with the entry. Plain-Markdown compatibility is retained: complete write entries containing standalone header metadata lines such as `Trust: untrusted`, `Status: expired`, `Status: superseded`, `Status: revoked`, or `Status: retired` are kept on disk but omitted from direct, distilled, and auto-retrieved agent context. A standalone past `Valid until: YYYY-MM-DD` line is also honored. These phrases inside ordinary prose are not treated as metadata.
+
+Writes screen a bounded set of high-confidence credential shapes and replace matching values with `[REDACTED_SECRET]` before persistence. Context rendering applies the same screening to legacy files. This is defense in depth, not a secrets vault; avoid passing real credentials in command arguments or memory content.
+
 ### Tags and links
 
 Use `#tags` and `[[wiki-links]]` in memory content to improve searchability:
@@ -185,6 +243,7 @@ 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_PLUGIN_DIR` | path | `~/.agent-memory/system/plugins` | Machine-local official plugin installation root; independent of `AGENT_MEMORY_DIR` |
 
 ## Running tests
 
@@ -192,6 +251,14 @@ These are content conventions, not enforced metadata. qmd's full-text indexing m
 # Unit tests (no LLM, no qmd — fast, deterministic)
 bun test test/unit.test.ts
 bun test test/cli.test.ts
+
+# External-feedback dataset and deterministic capability probes
+bun run build:eval
+bun run test:eval
+bun run eval:feedback
+
+# Optional: add isolated live qmd multilingual retrieval probes
+bun run eval:feedback --live-qmd
 ```
 
 ### Test levels
@@ -200,6 +267,7 @@ bun test test/cli.test.ts
 |-------|------|-------------|---------------|
 | Unit | `test/unit.test.ts` | None | Utilities, scratchpad parsing, context builder, qmd helpers, tool functions |
 | CLI | `test/cli.test.ts` | None | CLI commands, subprocess integration |
+| Feedback eval | `test/eval.test.ts`, `eval/` | qmd optional | External feedback, capability gaps, multilingual retrieval, and qualitative boundaries |
 
 ## Development
 
@@ -216,24 +284,25 @@ agent-memory install-skills
 
 ## Publishing (maintainers)
 
-```bash
-# Confirm package name is available
-npm view agent-memory
+Publication is tag-driven through `.github/workflows/publish-npm.yml`. Configure `jayzeng/agentmemory` and `publish-npm.yml` as the npm trusted publisher for `myagentmemory`, merge a versioned changelog/package update, and push the matching `v<version>` tag. The workflow uses short-lived OIDC credentials, runs the complete release gate, and publishes the public package with provenance. Do not publish this package from the private plugin workspace.
 
-# Bump version (choose patch/minor/major)
-npm version patch
+### Repository assets (maintainers)
 
-# Publish to npm (public)
-npm publish --access public
-```
+- **Social preview image:** `.github/assets/social-preview.png` (1280×640)
+- **Release notes template:** `.github/release.yml` (used by GitHub auto-generated release notes)
+- **Landing page source:** `docs/index.html` (deployed by `.github/workflows/deploy-pages.yml`)
+
+## Acknowledgments
+
+Inspired by [skyfallsin/pi-mem](https://github.com/skyfallsin/pi-mem). Semantic search is powered by [qmd](https://github.com/tobi/qmd).
 
 ## Changelog
 
-### 0.5.0
+### 0.4.12
 
 - **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` → `agent-memory`.
+- **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`.

package/dist/cli-spec.d.ts

@@ -0,0 +1,25 @@
+export type CliValueKind = "directory" | "file" | "number" | "value";
+export interface CliOptionSpec {
+    description: string;
+    value?: {
+        label: string;
+        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", "plugin", "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"];
+export declare const COMMAND_DESCRIPTIONS: Record<(typeof COMMANDS)[number], string>;
+export declare const PLUGIN_COMMAND_DESCRIPTIONS: Record<(typeof PLUGIN_COMMANDS)[number], string>;
+export declare const WORKER_ACTION_DESCRIPTIONS: Record<(typeof WORKER_ACTIONS)[number], string>;
+export declare const SCRATCHPAD_ACTION_DESCRIPTIONS: Record<(typeof SCRATCHPAD_ACTIONS)[number], string>;
+export declare const GLOBAL_OPTIONS: readonly ["--dir", "--json", "--help", "--version", "-h", "-V"];
+export declare const COMMAND_OPTIONS: Record<string, readonly string[]>;
+export declare const PLUGIN_COMMAND_OPTIONS: Record<string, readonly string[]>;
+export declare const WORKER_ACTION_OPTIONS: Record<string, readonly string[]>;
+export declare const SCRATCHPAD_ACTION_OPTIONS: Record<string, readonly string[]>;
+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;

package/dist/cli-spec.js

@@ -0,0 +1,211 @@
+export const COMMANDS = [
+    "context",
+    "write",
+    "read",
+    "scratchpad",
+    "search",
+    "distil",
+    "sync",
+    "init",
+    "status",
+    "install-skills",
+    "uninstall-skills",
+    "install-hooks",
+    "uninstall-hooks",
+    "completion",
+    "plugin",
+    "version",
+    "help",
+];
+export const PLUGIN_COMMANDS = ["list", "status", "install", "update", "uninstall", "manage"];
+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",
+    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",
+    status: "show memory paths, file counts, qmd, and embedding health",
+    "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",
+    completion: "install or print Bash, Zsh, Fish, or PowerShell completion",
+    plugin: "index, recall, learn from, and evaluate prior agent sessions",
+    version: "print the installed agent-memory version",
+    help: "show top-level, command, or nested plugin help",
+};
+export const PLUGIN_COMMAND_DESCRIPTIONS = {
+    list: "list optional official plugins and local availability",
+    status: "show the installed bundle and entitlement state",
+    install: "authenticate if needed, then install or upgrade the official bundle",
+    update: "upgrade an existing official bundle when a compatible release exists",
+    uninstall: "remove official plugin executables while preserving user data",
+    manage: "open the AgentMemory account and billing website",
+};
+export const WORKER_ACTION_DESCRIPTIONS = {};
+export const SCRATCHPAD_ACTION_DESCRIPTIONS = {
+    add: "add a new open checklist item; requires --text",
+    done: "complete the first open substring match; requires --text",
+    undo: "reopen the first completed substring match; requires --text",
+    clear_done: "remove every completed checklist item",
+    list: "show checklist items and completion counts",
+};
+export const GLOBAL_OPTIONS = ["--dir", "--json", "--help", "--version", "-h", "-V"];
+export const COMMAND_OPTIONS = {
+    context: ["--query", "--no-search"],
+    write: ["--content", "--target", "--mode", "--topic", "--date", "--source-uri"],
+    read: ["--target", "--date", "--topic"],
+    scratchpad: ["--text"],
+    search: ["--query", "--mode", "--limit"],
+    distil: ["--dry-run"],
+    sync: [],
+    init: [],
+    status: ["--probe"],
+    "install-skills": [],
+    "uninstall-skills": [],
+    "install-hooks": ["--yes", "--all", "--only"],
+    "uninstall-hooks": ["--only"],
+    completion: ["--stdout"],
+    version: [],
+    help: [],
+};
+export const PLUGIN_COMMAND_OPTIONS = {
+    list: [],
+    status: ["--channel"],
+    install: ["--channel", "--no-browser", "--yes"],
+    update: ["--channel"],
+    uninstall: ["--yes"],
+    manage: ["--no-browser"],
+};
+export const WORKER_ACTION_OPTIONS = {};
+export const SCRATCHPAD_ACTION_OPTIONS = {
+    add: ["--text"],
+    done: ["--text"],
+    undo: ["--text"],
+    clear_done: [],
+    list: [],
+};
+export const OPTION_SPECS = {
+    "--dir": { description: "override the active memory directory", value: { label: "directory", kind: "directory" } },
+    "--json": { description: "emit command-specific structured JSON" },
+    "--help": { description: "show help for the selected command" },
+    "--version": { description: "print the installed version and exit" },
+    "-h": { description: "show help for the selected command" },
+    "-V": { description: "print the installed version and exit" },
+    "--query": { description: "memory search or context-retrieval query", value: { label: "text", kind: "value" } },
+    "--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" } },
+    "--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": {
+        description: "optional provenance URI stored with an entry",
+        value: { label: "uri", kind: "value" },
+    },
+    "--text": { description: "checklist item text or substring to match", value: { label: "text", kind: "value" } },
+    "--limit": { description: "maximum number of search or recall results", value: { label: "number", kind: "number" } },
+    "--dry-run": { description: "preview generated memory without writing MEMORY.md" },
+    "--probe": { description: "run a live semantic query to verify embeddings" },
+    "--since": { description: "metrics reporting window in days", value: { label: "days", kind: "number" } },
+    "--port": {
+        description: "web-console port; use 0 to select an available port",
+        value: { label: "number", kind: "number" },
+    },
+    "--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" },
+    "--all": { description: "apply eligible hook changes without confirmation" },
+    "--only": {
+        description: "restrict hook changes to comma-separated agent keys",
+        value: { label: "agents", kind: "value" },
+    },
+    "--stdout": { description: "print the completion script without installing it" },
+    "--channel": {
+        description: "select the official release channel",
+        value: { label: "channel", kind: "value" },
+    },
+    "--no-browser": { description: "print account URLs instead of opening a browser" },
+    "--scope": {
+        description: "search globally or only in the current workspace",
+        value: { label: "scope", kind: "value" },
+    },
+    "--cwd": {
+        description: "restrict session operations to a working directory",
+        value: { label: "directory", kind: "directory" },
+    },
+    "--context": {
+        description: "surrounding events included with each recall hit",
+        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": {
+        description: "override the Claude Code session root",
+        value: { label: "directory", kind: "directory" },
+    },
+    "--host": {
+        description: "session host (pi/codex/claude) or web loopback bind address",
+        value: { label: "host", kind: "value" },
+    },
+    "--max-per-host": {
+        description: "maximum session files read from each host",
+        value: { label: "number", kind: "number" },
+    },
+    "--recent": {
+        description: "most recently modified session files refreshed per host",
+        value: { label: "number", kind: "number" },
+    },
+    "--interval": {
+        description: "watch polling interval in milliseconds",
+        value: { label: "milliseconds", kind: "number" },
+    },
+    "--once": { description: "run one watch iteration and exit" },
+    "--lines": {
+        description: "number of recent worker log entries to return",
+        value: { label: "number", kind: "number" },
+    },
+    "--threshold": {
+        description: "minimum repeated evidence required for a candidate",
+        value: { label: "number", kind: "number" },
+    },
+    "--output": { description: "also write the report to this file", value: { label: "file", kind: "file" } },
+    "--replay": { description: "back up and rebuild derived learning layers" },
+    "--journal": {
+        description: "override the experience journal directory",
+        value: { label: "directory", kind: "directory" },
+    },
+    "--candidates-dir": {
+        description: "override the candidate ledger directory",
+        value: { label: "directory", kind: "directory" },
+    },
+    "--decisions-dir": {
+        description: "override the decision ledger directory",
+        value: { label: "directory", kind: "directory" },
+    },
+    "--auto-dir": {
+        description: "override the materialized auto-memory directory",
+        value: { label: "directory", kind: "directory" },
+    },
+    "--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" },
+};
+export const SHELL_DESCRIPTIONS = {
+    bash: "generate or install Bash completion",
+    zsh: "generate or install Zsh completion",
+    fish: "generate or install Fish completion",
+    powershell: "generate or install PowerShell completion",
+};
+export function optionDescription(option) {
+    return OPTION_SPECS[option]?.description ?? option;
+}
+export function optionTakesValue(option) {
+    return OPTION_SPECS[option]?.value !== undefined;
+}

package/dist/cli.d.ts

@@ -12,6 +12,10 @@
  *   search     — Search via qmd
  *   init       — Create dirs, detect qmd, setup collection
  *   status     — Show config, qmd status, file counts
+ *   completion — Install or print shell completion
+ *   install-hooks — Install managed session-start hooks
+ *   uninstall-hooks — Remove managed session-start hooks
+ *   plugin     — Discover and bootstrap optional official plugins
  *
  * Global flags:
  *   --dir <path>   Override memory directory