@staix/agent-mem 0.14.0 → 0.15.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mem",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Bounded project memory tools and seven deterministic capture hooks, without a resident worker.",
   "mcpServers": {
     "agent-mem": {

package/README.md

@@ -2,7 +2,7 @@
 
 Curated memory with append-only JSONL logs, a derived SQLite index, short- and long-term tiers, a typed graph, goals with leases, and git sync between machines. Extracted from [agent-hub](https://github.com/STAIxBWLB/agent-hub), with compatible storage and entry IDs.
 
-Version: 0.14.0. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.15.0. Requires Bun 1.4.2 or later; no runtime dependencies.
 
 ## Quick start
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Curated, shared memory for coding agents: append-only logs, a derived index, tiers and a typed graph.",
   "license": "MIT",
   "type": "module",

package/src/cli-agent-reads.ts

@@ -6,6 +6,16 @@ import type { ParsedCommand } from "./commands-table.ts";
 
 const UNAVAILABLE = "Memory operation unavailable or refused; no partial result is shown.";
 const RESULT_BYTES = 262_144;
+const AGENT_READS = "Agent reads: search, list, show, brief, graph, vault-candidates, capacity.";
+
+/** A refusal decided from the parsed command alone, before any store or file is opened: safe to show as is. */
+export class AgentUsageError extends Error {
+  constructor(message: string) { super(message); this.name = "AgentUsageError"; }
+}
+const accepts = (command: string, allowed: readonly string[]) => new AgentUsageError(allowed.length
+  ? `agent-marked ${command} accepts only ${allowed.length === 1 ? allowed[0] : `${allowed.slice(0, -1).join(", ")} and ${allowed.at(-1)}`}.`
+  : `agent-marked ${command} accepts no options.`);
+
 type ReadCall = { tool: keyof ReturnType<typeof createMemoryMcp>["tools"]; args: Record<string, unknown> };
 
 function values(argv: readonly string[], name: string): string[] {
@@ -29,50 +39,54 @@ function positiveLimit(value: string | boolean | undefined): number | undefined
 function route(parsed: ParsedCommand, argv: readonly string[]): ReadCall | undefined {
   const { path, options, positionals, definition } = parsed;
 
-  if (path[0] === "machine" && options["--label"] === undefined) throw new Error(UNAVAILABLE);
+  if (path[0] === "machine" && options["--label"] === undefined) throw new AgentUsageError(`amem machine without --label is not available to an agent-marked session. ${AGENT_READS}`);
   // Write/preview/confirmation paths continue through the guarded administrative handlers.
   if (definition.mutates !== undefined) return undefined;
-  if (path[0] === "project" && path[1] === "export") throw new Error(UNAVAILABLE);
+  if (path[0] === "project" && path[1] === "export") throw new AgentUsageError(`amem project export is not available to an agent-marked session. ${AGENT_READS}`);
   if (path[0] === "setup") return undefined;
 
   const flags = Object.keys(options).filter(key => key !== "--json" && key !== "--policy-free");
   const only = (...allowed: string[]) => flags.every(flag => allowed.includes(flag));
   const limit = positiveLimit(options["--limit"]);
-  if (options["--limit"] !== undefined && limit === undefined) throw new Error(UNAVAILABLE);
+  if (options["--limit"] !== undefined && limit === undefined) throw new AgentUsageError("--limit takes a whole number from 1 to 100.");
 
   if (path[0] === "search") {
-    if (!only("--limit", "--since", "--explain") || !positionals.join(" ").trim()) throw new Error(UNAVAILABLE);
+    if (!only("--limit", "--since", "--explain")) throw accepts("search", ["--limit", "--since", "--explain"]);
+    if (!positionals.join(" ").trim()) throw new AgentUsageError("agent-marked search needs a query.");
     return { tool: "amem_search", args: { query: positionals.join(" "), ...(limit === undefined ? {} : { limit }), ...(options["--since"] !== undefined ? { since: options["--since"] } : {}), ...(options["--explain"] === true ? { explain: true } : {}) } };
   }
   if (path[0] === "list") {
-    if (!only("--limit", "--since")) throw new Error(UNAVAILABLE);
+    if (!only("--limit", "--since")) throw accepts("list", ["--limit", "--since"]);
     return { tool: "amem_timeline", args: { ...(limit === undefined ? {} : { limit }), ...(options["--since"] !== undefined ? { since: options["--since"] } : {}) } };
   }
   if (path[0] === "show") {
-    if (!only() || positionals.length !== 1 || !positionals[0]!.trim()) throw new Error(UNAVAILABLE);
+    if (!only()) throw accepts("show", []);
+    if (positionals.length !== 1 || !positionals[0]!.trim()) throw new AgentUsageError("agent-marked show takes exactly one id.");
     return { tool: "amem_show", args: { id: positionals[0] } };
   }
   if (path[0] === "brief") {
-    if (!only("--for", "--paths", "--symbols", "--bytes") || typeof options["--for"] !== "string") throw new Error(UNAVAILABLE);
+    if (!only("--for", "--paths", "--symbols", "--bytes")) throw accepts("brief", ["--for", "--paths", "--symbols", "--bytes"]);
+    if (typeof options["--for"] !== "string") throw new AgentUsageError("agent-marked brief needs --for.");
     const rawBytes = options["--bytes"];
-    if (rawBytes !== undefined && !/^[1-9][0-9]*$/.test(String(rawBytes))) throw new Error(UNAVAILABLE);
+    if (rawBytes !== undefined && !/^[1-9][0-9]*$/.test(String(rawBytes))) throw new AgentUsageError("--bytes takes a positive whole number.");
     return { tool: "amem_brief", args: { intent: options["--for"], paths: values(argv, "--paths"), symbols: values(argv, "--symbols"), ...(rawBytes === undefined ? {} : { maxBytes: Number(rawBytes) }) } };
   }
   if (path[0] === "graph") {
-    if (!only("--hops") || positionals.length !== 1) throw new Error(UNAVAILABLE);
+    if (!only("--hops")) throw accepts("graph", ["--hops"]);
+    if (positionals.length !== 1) throw new AgentUsageError("agent-marked graph takes exactly one start id.");
     const hops = options["--hops"] === undefined ? 1 : Number(options["--hops"]);
-    if (hops !== 1 && hops !== 2) throw new Error(UNAVAILABLE);
+    if (hops !== 1 && hops !== 2) throw new AgentUsageError("--hops takes 1 or 2.");
     return { tool: "amem_graph", args: { start: positionals[0], ...(options["--hops"] === undefined ? {} : { hops }) } };
   }
   if (path[0] === "vault-candidates") {
-    if (!only("--limit") || options["--all-projects"] !== undefined || options["--project"] !== undefined) throw new Error(UNAVAILABLE);
+    if (!only("--limit") || options["--all-projects"] !== undefined || options["--project"] !== undefined) throw accepts("vault-candidates", ["--limit"]);
     return { tool: "amem_vault_candidates", args: limit === undefined ? {} : { limit } };
   }
   if (path[0] === "capacity" && path.length === 1) {
-    if (!only()) throw new Error(UNAVAILABLE);
+    if (!only()) throw accepts("capacity", []);
     return { tool: "amem_capacity", args: {} };
   }
-  throw new Error(UNAVAILABLE);
+  throw new AgentUsageError(`amem ${path.join(" ")} is not available to an agent-marked session. ${AGENT_READS}`);
 }
 
 /** Route marked-agent read commands through the same startup-bound MCP policy and handlers. */

package/src/cli.ts

@@ -1,5 +1,5 @@
 import { activatePublicPruneView } from "./memory/public-prune-activation.ts";
-import { agentCliRead } from "./cli-agent-reads.ts";
+import { AgentUsageError, agentCliRead } from "./cli-agent-reads.ts";
 import { cliAttribution, withCliAttribution } from "./memory/cli-attribution.ts";
 import { randomUUID } from "node:crypto";
 import type { Writable } from "node:stream";
@@ -212,6 +212,14 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
       if (!readable) throw new CliPartialApplyError(error.applied.length, error.jsonOutput);
       const safe = new DecayApplyError(error.report, undefined); safe.jsonOutput = error.jsonOutput; throw safe;
     }
+    // Data-free errors (decided before any store or file is opened) keep their own message.
+    if (marked && error instanceof AgentUsageError) throw error;
+    if (marked) {
+      // parseCommand is pure: when it rejects argv, the error it raised is a usage error, not memory data.
+      let usage: Error | undefined;
+      try { parseCommand(argv); } catch (parseError) { usage = parseError as Error; }
+      if (usage) throw Object.assign(new Error(usage.message), (error as { exitCode?: number }).exitCode === undefined ? {} : { exitCode: (error as { exitCode?: number }).exitCode });
+    }
     // Marked administrative failures must not reveal a target's private state or native errors.
     if (marked) throw Error("Memory operation unavailable or refused; no partial result is shown.");
     throw error;
@@ -223,14 +231,14 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
     await serveMcp({ tools: memory.tools, close: memory.close, onEmitted: memory.onEmitted, version: VERSION });
     return "";
   }
-  if (argv[0] === "hook") {
+  if (argv[0] === "hook" && !argv.includes("--help")) {
     const { hookMain } = await import("./hooks.ts");
     return hookMain(argv.slice(1));
   }
   if (argv[0] === "ingest") {
     // Capture-only native intake: no project/home override, policy bypass or curated write capability.
     const parsed = parseCommand(argv);
-    if (parsed.options["--help"] === true) return commandHelp();
+    if (parsed.options["--help"] === true) return commandHelp(argv);
     const kind = parsed.positionals[0];
     if (parsed.positionals.length !== 1 || !["codex", "kimi", "pi", "qwen"].includes(kind ?? "")) throw new Error("usage: amem ingest codex|kimi|pi|qwen [--since ISO] [--json]");
     const { ingestTranscript } = await import("./ingest.ts");
@@ -244,7 +252,7 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
   if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "version")) return `amem ${VERSION}`;
   if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "help")) return commandHelp();
   if (argv[0] === "--version" || argv[0] === "version") return `amem ${VERSION}`;
-  if (argv[0] === "--help" || argv[0] === "help" || argv.includes("--help")) return commandHelp();
+  if (argv[0] === "--help" || argv[0] === "help" || argv.includes("--help")) return commandHelp(argv);
   let parsed;
   try {
     parsed = parseCommand(argv);

package/src/commands-table.ts

@@ -167,7 +167,7 @@ export function parseCommand(argv: readonly string[]): ParsedCommand {
         options[token] = value;
       } else options[token] = true;
     } else if (definition.commands) {
-      const child: CommandDefinition | undefined = definition.commands[token];
+      const child: CommandDefinition | undefined = Object.hasOwn(definition.commands, token) ? definition.commands[token] : undefined;
       if (!child) throw new Error(`unknown command ${[...path, token].join(" ")}`);
       commandIndexes.add(i);
       definition = { ...definition, ...child }; path.push(token);
@@ -194,9 +194,36 @@ export function parseCommand(argv: readonly string[]): ParsedCommand {
   return { path, definition, options, positionals, rawArgs };
 }
 
-export function commandHelp(): string {
-  return ["usage: amem <command> [options]", "  [--help] [--version] [--json]", ...completionDefinitions().filter(row => row.path.length).map(row => {
-    const names = [...row.path, ...row.args.map(arg => `<${arg.name}>`)].join(" ");
-    return `  ${names}${Object.entries(row.options).map(([name, option]) => ` [${name}${option.value === undefined ? "" : ` <${Array.isArray(option.value) ? option.value.join("|") : option.value}>`}]`).join("")}`;
-  }), "--policy-free: accepted and ignored; the configured privacy policy (amem.config.json in the memory home, narrowed by .amem/config) always applies.", "Agent-marked reads use the MCP privacy ceiling. Explicit apply/confirm flags do not require a terminal; review walk and the note editor remain interactive."].join("\n");
+const optionLabel = (name: string, option: OptionDefinition) =>
+  `${name}${option.value === undefined ? "" : ` <${Array.isArray(option.value) ? option.value.join("|") : option.value}>`}`;
+const usageRow = (row: CompletionDefinition) =>
+  `${[...row.path, ...row.args.map(arg => `<${arg.name}>`)].join(" ")}${Object.entries(row.options).map(([name, option]) => ` [${optionLabel(name, option)}]`).join("")}`;
+const described = (rows: [string, string][]) => {
+  // Long enum labels (review --kind) would push every description far right; they overflow instead.
+  const width = Math.min(24, Math.max(...rows.map(([label]) => label.length)));
+  return rows.map(([label, description]) => `  ${label.padEnd(width)}  ${description}`);
+};
+
+/** Full command list, or one command's help when argv names a command path (defaultCommand is not applied). */
+export function commandHelp(argv: readonly string[] = []): string {
+  const path: string[] = [], rows = completionDefinitions();
+  let commands: Record<string, CommandDefinition> | undefined = COMMANDS, command: CommandDefinition | undefined, row = rows[0]!;
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i]!;
+    if (token.startsWith("--")) {
+      // An option's value is never a command name.
+      if (!token.includes("=") && row.options[token]?.value !== undefined) i++;
+      continue;
+    }
+    if (!commands || !Object.hasOwn(commands, token)) break;
+    command = commands[token]!; path.push(token); commands = command.commands;
+    row = rows.find(candidate => candidate.path.join(" ") === path.join(" "))!;
+  }
+  if (command && path[0] !== "help") {
+    const lines = [`usage: amem ${usageRow(row)}`, "", command.description, "", "options:", ...described(Object.entries(row.options).map(([name, option]) => [optionLabel(name, option), option.description]))];
+    if (command.commands) lines.push("", "commands:", ...described(Object.entries(command.commands).map(([name, child]) => [name, child.description])));
+    return lines.join("\n");
+  }
+  return ["usage: amem <command> [options]", "  [--help] [--version] [--json]", ...completionDefinitions().filter(row => row.path.length).map(row => `  ${usageRow(row)}`),
+    "--policy-free: accepted and ignored; the configured privacy policy (amem.config.json in the memory home, narrowed by .amem/config) always applies.", "Agent-marked reads use the MCP privacy ceiling. Explicit apply/confirm flags do not require a terminal; review walk and the note editor remain interactive."].join("\n");
 }