@staix/agent-mem 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 STAIxBWLB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# agent-mem
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.1.1. Requires Bun 1.4.2 or later; no runtime dependencies.
+
+## Install
+
+Install the public package:
+
+```sh
+bun add -g @staix/agent-mem
+amem --version
+amem --help
+```
+
+From a checkout, install development dependencies with `bun install` and run `bun src/cli.ts --help`.
+
+## CLI
+
+The flat `amem` commands mirror `ahub memory` arguments; goals use `amem goal`:
+
+```sh
+amem list --json
+amem search "release decision" --limit 10
+amem show <id> --json
+amem graph <id-or-node> --hops 2 --json
+amem suggestions
+amem goal list --all --json
+amem goal new "Ship a release" --milestone "Review changes"
+```
+
+`amem goal link` requires the host task boundary; use `ahub goal link` for board links.
+
+Memory commands: `list`, `search`, `show`, `graph`, `suggestions`, `confirm`, `reject`, `promote`, `demote`, `forget`, `supersede`, `rebuild`, `dedupe`, `sync`, `machine`, and `import`. Use `--json` where supported by the corresponding `ahub memory` command. `dedupe` previews candidates; `dedupe --apply` appends reconciliation operations.
+
+`amem` is for the person. Every command is refused when an agent-session marker is present, including `AGENTHUB_PEER_ID`, `CLAUDECODE`, and `CODEX_THREAD_ID`. Agents read memory through the hub's `hub_memory_*` tools. Environment-marker detection is an honest-session guard, not authentication. Mutating commands also require a TTY on stdin.
+
+This package does not ship the host's privacy policy. Person reads show stored data without screening. Import and promotion retain the built-in secret screen. Commands that cross the privacy boundary require the person's explicit `--policy-free` choice:
+
+```sh
+amem promote <id> --policy-free
+amem import claude-mem --db <path> --policy-free
+amem sync --remote <private-git-url> --policy-free
+```
+
+Use `ahub memory` for the policy-applying path. `--policy-free` does not bypass the secret screen or the sync remote's privacy checks. Forgetting a shared note appends an operation; its previous content remains in the remote's git history.
+
+## Shell completion
+
+Generate completion for `zsh`, `bash`, or `fish` with `amem completion <shell>`. Generation prints a script to stdout; it does not install files or edit shell configuration. The following commands are for a person's terminal.
+
+### zsh
+
+```sh
+mkdir -p ~/.zfunc
+amem completion zsh > ~/.zfunc/_amem
+```
+
+Enable it by adding these lines to `~/.zshrc`, placing `fpath` before your existing `compinit` call (use only one `compinit` call):
+
+```sh
+fpath=(~/.zfunc $fpath)
+autoload -Uz compinit
+compinit
+```
+
+Start a new shell. After upgrading amem, regenerate `~/.zfunc/_amem` with the same command and start a new shell. To remove it, delete `~/.zfunc/_amem` and start a new shell; remove the added `fpath` entry only if no other completions use that directory.
+
+### bash
+
+```sh
+mkdir -p ~/.local/share/bash-completion/completions
+amem completion bash > ~/.local/share/bash-completion/completions/amem
+```
+
+Enable it by adding this line to `~/.bashrc`:
+
+```sh
+source ~/.local/share/bash-completion/completions/amem
+```
+
+Source that file or start a new interactive Bash. After upgrading amem, regenerate it and source it again. To remove it, delete that file, remove its source line from `~/.bashrc`, and run `complete -r amem` in the current shell (or start a new shell).
+
+### fish
+
+```sh
+mkdir -p ~/.config/fish/completions
+amem completion fish > ~/.config/fish/completions/amem.fish
+```
+
+Fish loads this directory automatically. Start a new fish shell. After upgrading amem, regenerate the file and start a new shell. To remove it, delete `~/.config/fish/completions/amem.fish` and start a new shell, or run `complete -c amem -e` to clear the current shell's definitions.
+
+### Manual Tab checks
+
+These interactive checks remain unrun until a person checks them in each installed shell; automated syntax/candidate tests do not establish terminal behavior.
+
+- Type `amem ` and press Tab: top-level commands appear.
+- Type `amem goal ` and press Tab: goal subcommands appear.
+- Type `amem list --tier ` and press Tab: `short` and `long` appear.
+- Type `amem goal state <id> ` and press Tab: goal states appear.
+- Type `amem import claude-mem --db ` and press Tab in a directory containing a filename with spaces: the path remains one argument.
+- Type `amem completion ` and press Tab: `zsh`, `bash`, and `fish` appear.
+
+## Data directory
+
+`memoryHome()` selects `AMEM_HOME` first, otherwise `$AGENTHUB_HOME/memory`, otherwise `~/.agenthub/memory`. `AMEM_HOME` names the memory directory itself; `AGENTHUB_HOME` names its parent. Existing agent-hub memory directories need no migration. An explicit `StoreOptions.home` retains the parent-directory convention and appends `/memory`.
+
+The JSONL segments are authoritative. `index.db` is derived and can be rebuilt. Entries are immutable; changes append operations. The compatibility schema remains `agent-hub.memory/v1` because it participates in entry IDs.
+
+## Library
+
+```ts
+import { MemoryStore, memoryProjectKey } from "@staix/agent-mem";
+
+const store = new MemoryStore();
+try {
+  const notes = store.list({ project: memoryProjectKey(process.cwd()) });
+  console.log(notes);
+} finally {
+  store.close();
+}
+```
+
+The root entry needs Bun (it loads `bun:sqlite`). Node hosts that need only the deny list, hardened git invocation, `realPath` or process identity import `@staix/agent-mem/platform`, which uses `node:` built-ins only.
+
+The entry point exports the store, types and identity helpers, sync and claude-mem import, project/home helpers, raw memory/goal command handlers, and platform helpers. Hosts inject their own privacy policy through `StoreOptions.screen`; CLI wrappers can supply screened reads and import policy through the raw command options.
+
+## Development
+
+```sh
+bun install --frozen-lockfile
+bun x tsc --noEmit
+bun scripts/check-boundary.ts
+bun test
+npm pack --dry-run
+```
+
+CI runs the typecheck, boundary check and tests on Ubuntu and macOS with Bun 1.4.2. Tests use synthetic fixtures and isolated homes, not personal memory stores.
+
+## Publishing
+
+0.1.0 was published once by hand, because npm trusted publishing requires an existing package; the trusted publisher for repository `STAIxBWLB/agent-mem` and workflow `release.yml` was configured after it. Every later release goes through the tag workflow.
+
+After setup, a `v*` tag triggers both operating-system gates. The tag must equal `v` plus `package.json`'s version. Only after both gates pass does the release job install npm 11.20.0 (trusted publishing needs 11.5.1 or later) and run `npm publish --access public`, authenticated through GitHub OIDC with `id-token: write`; npm adds provenance itself. The workflow uses no `NPM_TOKEN`.
+
+License: MIT.

package/bin/amem.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+// Plain JavaScript: refuse Node before it can load TypeScript or bun:sqlite.
+const version = /^(\d+)\.(\d+)\.(\d+)/.exec(process.versions.bun ?? "");
+if (!version || Number(version[1]) < 1 || (Number(version[1]) === 1 && (Number(version[2]) < 4 || (Number(version[2]) === 4 && Number(version[3]) < 2)))) {
+  console.error("amem: Bun >=1.4.2 is required. Install Bun: https://bun.sh");
+  process.exit(1);
+}
+const { main } = await import("../src/cli.ts");
+await main();

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Curated, shared memory for coding agents: append-only logs, a derived index, tiers and a typed graph.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/STAIxBWLB/agent-mem.git"
+  },
+  "engines": {
+    "bun": ">=1.4.2"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "typescript": "^5.8.0"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./platform": "./src/memory/platform.ts"
+  },
+  "bin": {
+    "amem": "./bin/amem.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "bun x tsc --noEmit && bun scripts/check-boundary.ts && bun test --timeout 20000"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,58 @@
+import { readFileSync } from "node:fs";
+import { MemoryStore, looksSecret } from "./memory/store.ts";
+import { rawMemoryCommand, rawGoalCommand } from "./memory/commands.ts";
+
+import { commandHelp, parseCommand } from "./commands-table.ts";
+import { completionScript } from "./completion.ts";
+
+export const PERSON_ONLY = "amem is for the person; agents read memory through the hub's hub_memory_* tools";
+const VERSION = (JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string }).version;
+export interface CliContext { cwd?: string; env?: Readonly<Record<string, string | undefined>>; stdinTTY?: boolean }
+
+/** Honest native-shell defaults, matching every marker detectCliIdentity treats as non-console (invalid included). */
+export function agentMarked(env: Readonly<Record<string, string | undefined>>): boolean {
+  return ["AGENTHUB_PEER_ID", "CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID"].some(key => env[key] !== undefined);
+}
+
+export async function runCli(argv: readonly string[], context: CliContext = {}): Promise<string> {
+  if (agentMarked(context.env ?? process.env)) throw new Error(PERSON_ONLY);
+  if (argv[0] === "--version" || argv[0] === "version") return `amem ${VERSION}`;
+  if (argv[0] === "--help" || argv[0] === "help" || argv.includes("--help")) return commandHelp();
+  let parsed;
+  try {
+    parsed = parseCommand(argv);
+    if (parsed.path[0] === "version") return `amem ${VERSION}`;
+    if (parsed.path[0] === "completion") {
+      if (parsed.positionals.length !== 1) throw new Error("usage: amem completion zsh|bash|fish");
+      return completionScript(parsed.positionals[0]!);
+    }
+  } catch (error) {
+    if (argv.find(arg => !arg.startsWith("--")) === "completion") Object.assign(error as Error, { exitCode: 2 });
+    throw error;
+  }
+  const { definition, options, rawArgs: args } = parsed;
+  const goal = parsed.path[0] === "goal", sub = goal ? parsed.path[1]! : parsed.path[0]!;
+  const policyFree = options["--policy-free"] === true;
+  const mutating = definition.mutates === true || definition.mutates === "apply" && options["--apply"] === true || definition.mutates === "label" && options["--label"] !== undefined;
+  if (mutating && !(context.stdinTTY ?? process.stdin.isTTY)) throw new Error("mutating commands require a terminal on stdin");
+  if (definition.policyFree && !policyFree) {
+    throw new Error(`${sub} requires --policy-free; use ahub memory ${sub} to apply the host's privacy policy`);
+  }
+  // ponytail: board task links need the host's authenticated task boundary; add a host bridge before supporting them here.
+  if (goal && sub === "link") throw new Error("goal link needs host integration; use ahub goal link");
+  const crosses = definition.policyFree === true && policyFree;
+  // Reads can trigger held-note reconciliation. Defer it unless this terminal explicitly authorized crossing policy.
+  const open = () => new MemoryStore({ screen: note => !crosses ? "skip" : looksSecret(`${note.title ?? ""}\n${note.text}`) ? "keep" : "promote" });
+  const cwd = context.cwd ?? process.cwd();
+  // A person's reads are unscreened. Writes crossing the boundary remain secret-screened without host policy.
+  return goal
+    ? rawGoalCommand(args, cwd, { open, clean: (title, milestones) => !mutating || !looksSecret(`${title}\n${milestones.join("\n")}`) })
+    : rawMemoryCommand(args, cwd, { open, readable: notes => notes, importPolicy: () => () => false });
+}
+
+export async function main(argv = process.argv.slice(2)): Promise<void> {
+  try { console.log(await runCli(argv)); }
+  catch (error) { console.error(`amem: ${(error as Error).message}`); process.exitCode = (error as { exitCode?: number }).exitCode ?? 1; }
+}
+
+if (import.meta.main) await main();

package/src/commands-table.ts

@@ -0,0 +1,123 @@
+import { GOAL_STATES, KINDS } from "./memory/store.ts";
+
+export interface OptionDefinition { description: string; value?: "text" | "path" | readonly string[] }
+export interface ArgumentDefinition { name: string; values?: readonly string[]; path?: boolean; variadic?: boolean }
+export interface CommandDefinition {
+  description: string;
+  options?: Record<string, OptionDefinition>;
+  args?: readonly ArgumentDefinition[];
+  commands?: Record<string, CommandDefinition>;
+  mutates?: boolean | "apply" | "label";
+  policyFree?: boolean;
+  defaultCommand?: string;
+}
+const flag = (description: string): OptionDefinition => ({ description });
+const text = (description: string): OptionDefinition => ({ description, value: "text" });
+const json = { "--json": flag("Print JSON where supported") };
+const policy = { "--policy-free": flag("Explicitly bypass host privacy policy") };
+const filters = { ...json, "--tier": { description: "Memory tier", value: ["short", "long"] } as OptionDefinition,
+  "--kind": { description: "Note kind", value: KINDS }, "--peer": text("Author peer"), "--machine": text("Machine ID"),
+  "--since": text("ISO date or time"), "--limit": text("Maximum results") };
+export const GLOBAL_OPTIONS = { "--help": flag("Show help") };
+export const ROOT_OPTIONS = { "--version": flag("Show version"), ...json };
+export const COMMANDS: Record<string, CommandDefinition> = {
+  list: { description: "List memory", options: filters },
+  search: { description: "Search memory", options: filters, args: [{ name: "words", variadic: true }] },
+  show: { description: "Show a note", options: json, args: [{ name: "id" }] },
+  graph: { description: "Show a graph", options: { ...json, "--hops": { description: "Graph depth", value: ["1", "2"] } }, args: [{ name: "id-or-node" }] },
+  suggestions: { description: "List pending suggestions", options: json },
+  confirm: { description: "Confirm a suggestion", options: json, args: [{ name: "id" }], mutates: true },
+  reject: { description: "Reject a suggestion", options: json, args: [{ name: "id" }], mutates: true },
+  promote: { description: "Promote a note", options: { ...json, ...policy }, args: [{ name: "id" }], mutates: true, policyFree: true },
+  demote: { description: "Demote a note", options: json, args: [{ name: "id" }], mutates: true },
+  forget: { description: "Forget a note", options: json, args: [{ name: "id" }], mutates: true },
+  supersede: { description: "Replace a note", options: json, args: [{ name: "old-id" }, { name: "new-id" }], mutates: true },
+  rebuild: { description: "Rebuild the derived index", options: json, mutates: true },
+  dedupe: { description: "Preview duplicate reconciliation", options: { ...json, "--apply": flag("Append reconciliation operations") }, mutates: "apply" },
+  sync: { description: "Sync a private remote", options: { ...json, ...policy, "--remote": text("Private git URL") }, mutates: true, policyFree: true },
+  machine: { description: "Show or label this machine", options: { ...json, "--label": text("Machine label") }, mutates: "label" },
+  import: { description: "Import external memory", options: { ...json, ...policy, "--db": { description: "SQLite database file", value: "path" }, "--limit": text("Maximum observations"), "--restart": flag("Restart import cursor") }, mutates: true, policyFree: true,
+    commands: { "claude-mem": { description: "Import claude-mem observations" } } },
+  goal: { description: "Long-term goals", options: json, defaultCommand: "list", commands: {
+    list: { description: "List goals", options: { "--all": flag("Include completed goals") } },
+    show: { description: "Show a goal", args: [{ name: "id" }] },
+    new: { description: "Create a goal", options: { "--milestone": text("Milestone"), "--depends": text("Dependency goal ID"), "--shared": flag("Share across projects") }, args: [{ name: "title", variadic: true }], mutates: true },
+    link: { description: "Link through ahub goal link", args: [{ name: "id" }, { name: "task-id" }], mutates: true },
+    state: { description: "Set goal state", args: [{ name: "id" }, { name: "state", values: GOAL_STATES }], mutates: true },
+    done: { description: "Complete a goal", args: [{ name: "id" }], mutates: true },
+    take: { description: "Take a goal lease", options: { "--force": flag("Override the prior lease") }, args: [{ name: "id" }], mutates: true },
+  } },
+  completion: { description: "Print static shell completion", args: [{ name: "shell", values: ["zsh", "bash", "fish"] }] },
+  help: { description: "Show help" }, version: { description: "Show version" },
+};
+
+export interface CompletionDefinition { path: string[]; options: Record<string, OptionDefinition>; args: ArgumentDefinition[]; children: string[] }
+export function completionDefinitions(): CompletionDefinition[] {
+  const rows: CompletionDefinition[] = [{ path: [], options: { ...GLOBAL_OPTIONS, ...ROOT_OPTIONS, ...COMMANDS.list!.options }, args: [], children: Object.keys(COMMANDS) }];
+  const walk = (commands: Record<string, CommandDefinition>, path: string[], inherited: Record<string, OptionDefinition>) => {
+    for (const [name, command] of Object.entries(commands)) {
+      const next = [...path, name], ownOptions = { ...inherited, ...command.options };
+      const options = { ...ownOptions, ...(command.defaultCommand ? command.commands?.[command.defaultCommand]?.options : {}) };
+      rows.push({ path: next, options, args: [...command.args ?? []], children: Object.keys(command.commands ?? {}) });
+      if (command.commands) walk(command.commands, next, ownOptions);
+    }
+  };
+  walk(COMMANDS, [], GLOBAL_OPTIONS); return rows;
+}
+export interface ParsedCommand { path: string[]; definition: CommandDefinition; options: Record<string, string | boolean>; positionals: string[]; rawArgs: string[] }
+
+/** Pure validation, shared definitions with help/completion; no store, files or network. */
+export function parseCommand(argv: readonly string[]): ParsedCommand {
+  const tokens = argv.flatMap(token => {
+    const equals = token.startsWith("--") ? token.indexOf("=") : -1;
+    return equals >= 0 ? [token.slice(0, equals), token.slice(equals + 1)] : [token];
+  });
+  const path: string[] = [], options: Record<string, string | boolean> = {}, positionals: string[] = [];
+  let definition: CommandDefinition = { description: "amem", commands: COMMANDS };
+  let available: Record<string, OptionDefinition> = { ...GLOBAL_OPTIONS, ...ROOT_OPTIONS, ...COMMANDS.list!.options };
+  const commandIndexes = new Set<number>();
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]!;
+    if (token.startsWith("--")) {
+      const option = available[token];
+      if (!option) throw new Error(`unknown option ${token}`);
+      if (option.value !== undefined) {
+        const value = tokens[++i];
+        if (value === undefined || value.startsWith("--")) throw new Error(`${token} needs a value`);
+        if (Array.isArray(option.value) && !option.value.includes(value)) throw new Error(`${token} takes ${option.value.join(" or ")}`);
+        options[token] = value;
+      } else options[token] = true;
+    } else if (definition.commands) {
+      const child: CommandDefinition | undefined = definition.commands[token];
+      if (!child) throw new Error(`unknown command ${[...path, token].join(" ")}`);
+      commandIndexes.add(i);
+      definition = { ...definition, ...child }; path.push(token);
+      // Child metadata inherits policy, but its command children belong only to that child.
+      definition.commands = child.commands;
+      available = completionDefinitions().find(row => row.path.join(" ") === path.join(" "))!.options;
+    } else positionals.push(token);
+  }
+  if (!path.length) {
+    const name = options["--version"] === true ? "version" : "list";
+    path.push(name); definition = COMMANDS[name]!;
+  }
+  if (definition.defaultCommand && definition.commands) {
+    const name = definition.defaultCommand; definition = { ...definition, ...definition.commands[name]!, commands: undefined }; path.push(name);
+  }
+  if (positionals.length > (definition.args?.length ?? 0) && !definition.args?.at(-1)?.variadic) throw new Error(`too many arguments for ${path.join(" ")}`);
+  for (let i = 0; i < positionals.length; i++) {
+    const argument = definition.args?.[i];
+    if (argument?.values && !argument.values.includes(positionals[i]!)) throw new Error(`${argument.name} takes ${argument.values.join(" or ")}`);
+  }
+  const allowed = path[0] === "version" && options["--version"] === true ? completionDefinitions()[0]!.options : completionDefinitions().find(row => row.path.join(" ") === path.join(" "))!.options;
+  for (const name of Object.keys(options)) if (!allowed[name]) throw new Error(`unknown option ${name} for ${path.join(" ")}`);
+  const rawArgs = [...(path[0] === "goal" ? path.slice(1) : path), ...tokens.filter((arg, index) => arg !== "--policy-free" && !commandIndexes.has(index))];
+  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: use ahub memory for the host's privacy policy.", "Mutating commands require a terminal on stdin. Agents use the hub's hub_memory_* tools."].join("\n");
+}

package/src/completion.ts

@@ -0,0 +1,240 @@
+import { completionDefinitions } from "./commands-table.ts";
+
+const quote = (text: string) => `'${text.replace(/'/g, `'"'"'`)}'`;
+const print = (values: readonly string[]) => values.length ? `printf '%s\\n' ${values.map(quote).join(" ")}` : "true";
+
+/** Static lookup data generated from the exact definitions the CLI uses. No installed executable is queried. */
+function metadata(fish: boolean): string {
+  const cases: [string, string[]][] = [];
+  for (const definition of completionDefinitions()) {
+    const state = definition.path.join(" ");
+    cases.push([`children:${state}:`, definition.children]);
+    cases.push([`options:${state}:`, Object.keys(definition.options)]);
+    for (const [name, option] of Object.entries(definition.options)) {
+      if (option.value === undefined) continue;
+      cases.push([`type:${state}:${name}`, [typeof option.value === "string" ? option.value : "enum"]]);
+      if (typeof option.value !== "string") cases.push([`values:${state}:${name}`, [...option.value]]);
+    }
+    for (const [index, argument] of definition.args.entries()) {
+      cases.push([`argument:${state}:${index}`, [argument.path ? "path" : argument.values ? "enum" : "text"]]);
+      if (argument.values) cases.push([`arguments:${state}:${index}`, [...argument.values]]);
+    }
+  }
+  if (fish) return `function _amem_meta\n    switch "$argv[1]:$argv[2]:$argv[3]"\n${cases.map(([key, values]) => `        case ${quote(key)}\n            ${print(values)}`).join("\n")}\n    end\nend\n`;
+  return `_amem_meta() {\n  case "$1:$2:$3" in\n${cases.map(([key, values]) => `    ${quote(key)}) ${print(values)} ;;`).join("\n")}\n  esac\n}\n`;
+}
+
+/** Bash and zsh share a POSIX-style word walker; the last supplied token is the current prefix. */
+const context = `_amem_context() {
+  _amem_state='' _amem_pos=0 _amem_pending='' _amem_cur='' _amem_literal=0
+  local word child option i=0
+  for word do
+    i=$((i + 1))
+    if [ "$i" -eq "$#" ]; then _amem_cur=$word; break; fi
+    if [ -n "$_amem_pending" ]; then _amem_pending=''; continue; fi
+    if [ "$_amem_literal" -eq 0 ]; then
+      if [ "$word" = '--' ]; then _amem_literal=1; continue; fi
+      case "$word" in
+        --*=*) continue ;;
+        -*)
+          if [ -n "$(_amem_meta type "$_amem_state" "$word")" ]; then _amem_pending=$word; fi
+          continue ;;
+      esac
+      if [ "$_amem_pos" -eq 0 ]; then
+        child=''
+        while IFS= read -r option; do
+          if [ "$option" = "$word" ]; then child=$word; break; fi
+        done <<AMEM_CHILDREN
+$(_amem_meta children "$_amem_state" '')
+AMEM_CHILDREN
+        if [ -n "$child" ]; then _amem_state="\${_amem_state:+$_amem_state }$child"; _amem_pos=0; continue; fi
+      fi
+    fi
+    _amem_pos=$((_amem_pos + 1))
+  done
+}
+
+_amem_emit() {
+  local candidate
+  while IFS= read -r candidate; do
+    [ -n "$candidate" ] || continue
+    case "$candidate" in "$_amem_cur"*) printf '%s\\n' "$_amem_lead$candidate" ;; esac
+  done
+}
+`;
+
+function shCandidates(zsh: boolean): string {
+  const files = zsh ? `local pattern="\${(b)_amem_cur}*" candidate
+    local -a paths
+    paths=( \${~pattern}(N) )
+    for candidate in "\${paths[@]}"; do
+      [ -d "$candidate" ] && candidate="$candidate/"
+      printf '%s\\n' "$_amem_lead$candidate"
+    done` : `local candidate
+    while IFS= read -r candidate; do
+      [ -d "$candidate" ] && candidate="$candidate/"
+      printf '%s\\n' "$_amem_lead$candidate"
+    done < <(compgen -f -- "$_amem_cur")`;
+  return `${context}
+_amem_candidates() {
+  ${zsh ? "emulate -L zsh" : ":"}
+  _amem_context "$@"
+  local kind='' _amem_lead=''
+  if [ -n "$_amem_pending" ]; then
+    kind=$(_amem_meta type "$_amem_state" "$_amem_pending")
+  elif [ "$_amem_literal" -eq 0 ]; then
+    case "$_amem_cur" in
+      --*=*)
+        _amem_pending=\${_amem_cur%%=*}
+        _amem_lead="$_amem_pending="
+        _amem_cur=\${_amem_cur#*=}
+        kind=$(_amem_meta type "$_amem_state" "$_amem_pending") ;;
+    esac
+  fi
+  if [ -z "$kind" ] && [ -z "$_amem_pending" ]; then kind=$(_amem_meta argument "$_amem_state" "$_amem_pos"); fi
+  if [ "$kind" = path ]; then
+    ${files}
+  elif [ "$kind" = enum ]; then
+    if [ -n "$_amem_pending" ]; then _amem_meta values "$_amem_state" "$_amem_pending"
+    else _amem_meta arguments "$_amem_state" "$_amem_pos"; fi | _amem_emit
+  elif [ -n "$_amem_pending" ]; then
+    return 0
+  else
+    if [ "$_amem_literal" -eq 0 ]; then
+      {
+        [ "$_amem_pos" -ne 0 ] || _amem_meta children "$_amem_state" ''
+        _amem_meta options "$_amem_state" ''
+      } | _amem_emit
+    fi
+  fi
+}
+`;
+}
+
+function bash(): string {
+  return `# amem bash completion; generated from command definitions.\n${metadata(false)}${shCandidates(false)}
+_amem_complete() {
+  local candidate
+  COMPREPLY=()
+  while IFS= read -r candidate; do COMPREPLY+=("$candidate"); done < <(_amem_candidates "\${COMP_WORDS[@]:1:COMP_CWORD}")
+  compopt -o filenames 2>/dev/null || :
+}
+complete -F _amem_complete amem
+`;
+}
+
+function zsh(): string {
+  return `#compdef amem\n# amem zsh completion; generated from command definitions.\n${metadata(false)}${shCandidates(true)}
+_amem_complete() {
+  emulate -L zsh
+  local -a candidates
+  _amem_context "\${words[@]:1:$((CURRENT - 1))}"
+  local kind=''
+  if [ -n "$_amem_pending" ]; then kind=$(_amem_meta type "$_amem_state" "$_amem_pending")
+  else kind=$(_amem_meta argument "$_amem_state" "$_amem_pos"); fi
+  if [ "$kind" = path ]; then _files; return; fi
+  candidates=( "\${(@f)$(_amem_candidates "\${words[@]:1:$((CURRENT - 1))}")}" )
+  (( \${#candidates} )) && compadd -- "\${candidates[@]}"
+}
+# An autoloaded _amem file is itself the first completion invocation.
+if [[ "\${funcstack[1]-}" == _amem ]]; then
+  _amem_complete
+elif (( $+functions[compdef] )); then
+  compdef _amem_complete amem
+fi
+`;
+}
+
+function fish(): string {
+  return `# amem fish completion; generated from command definitions.\n${metadata(true)}
+function _amem_candidates
+    set -l state ''
+    set -l positional 0
+    set -l pending ''
+    set -l literal 0
+    set -l current ''
+    set -l index 0
+    for word in $argv
+        set index (math $index + 1)
+        if test $index -eq (count $argv)
+            set current "$word"
+            break
+        end
+        if test -n "$pending"
+            set pending ''
+            continue
+        end
+        if test $literal -eq 0
+            if test "$word" = --
+                set literal 1
+                continue
+            end
+            if string match -q -- '-*' "$word"
+                set -l option_kind (_amem_meta type "$state" "$word")
+                if not string match -q -- '*=*' "$word"; and test (count $option_kind) -gt 0
+                    set pending "$word"
+                end
+                continue
+            end
+            if test $positional -eq 0; and contains -- "$word" (_amem_meta children "$state" '')
+                set state (string trim -- "$state $word")
+                set positional 0
+                continue
+            end
+        end
+        set positional (math $positional + 1)
+    end
+    set -l kind ''
+    set -l lead ''
+    if test -n "$pending"
+        set kind (_amem_meta type "$state" "$pending")
+    else if test $literal -eq 0; and string match -q -- '--*=*' "$current"
+        set pending (string split -m 1 = -- "$current")[1]
+        set lead "$pending="
+        set current (string split -m 1 = -- "$current")[2]
+        set kind (_amem_meta type "$state" "$pending")
+    end
+    if test -z "$kind"; and test -z "$pending"
+        set kind (_amem_meta argument "$state" "$positional")
+    end
+    if test "$kind" = path
+        for candidate in "$current"*
+            if test -d "$candidate"
+                set candidate "$candidate/"
+            end
+            printf '%s\\n' "$lead$candidate"
+        end
+    else
+        set -l candidates
+        if test "$kind" = enum
+            if test -n "$pending"
+                set candidates (_amem_meta values "$state" "$pending")
+            else
+                set candidates (_amem_meta arguments "$state" "$positional")
+            end
+        else if test -z "$pending"; and test $literal -eq 0
+            if test $positional -eq 0
+                set candidates (_amem_meta children "$state" '')
+            end
+            set -a candidates (_amem_meta options "$state" '')
+        end
+        set -l prefix_regex (string escape --style=regex -- "$current")
+        for candidate in $candidates
+            if string match -rq -- "^$prefix_regex" "$candidate"
+                printf '%s\\n' "$lead$candidate"
+            end
+        end
+    end
+end
+
+complete -c amem -f -a '(_amem_candidates (commandline -opc)[2..-1] (commandline -ct))'
+`;
+}
+
+/** Generate a self-contained script; neither generation nor completion consults memory or network. */
+export function completionScript(shell: string): string {
+  if (shell === "bash") return bash();
+  if (shell === "zsh") return zsh();
+  if (shell === "fish") return fish();
+  throw new Error(`unsupported completion shell ${shell}; choose zsh, bash or fish`);
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./memory/store.ts";
+export * from "./memory/sync.ts";
+export * from "./memory/import.ts";
+export * from "./memory/project.ts";
+export * from "./memory/home.ts";
+export * from "./memory/platform.ts";
+export * from "./memory/commands.ts";