@memstack/cli 0.8.0 → 0.8.1

package/README.md

@@ -1,6 +1,6 @@
 # @memstack/cli
 
-CLI for MemStack — shell-based agent memory. Use from bash scripts, opencode/Claude Code shell tools, CI pipelines, or any subprocess-capable agent.
+CLI for MemStack — shell-based agent memory. Connect Claude Code and Codex to one shared memory per project, or use it from bash scripts, CI pipelines, or any subprocess-capable agent.
 
 ## Installation
 
@@ -10,9 +10,41 @@ npm install -g @memstack/cli
 npx @memstack/cli [command]
 ```
 
+## Claude Code and Codex
+
+Give both agents one persistent memory per project. MemStack never installs
+storage drivers; install the one for your store with the MCP server:
+
+```bash
+npm install -g @memstack/cli @memstack/mcp better-sqlite3@^11.10.0
+memstack init                   # LLM provider + store → ~/.memstack/config.json
+memstack connect claude-code
+memstack connect codex          # then approve the MemStack hook once in Codex with /hooks
+```
+
+| Command | What it does |
+|---|---|
+| `init` | Choose an LLM provider and store; verifies the key with a real request. Non-interactive: `--provider openai-compatible\|anthropic --base-url <url> --model <name> --api-key-env <VAR> --store <type> [--path <file> \| --url <url>] --yes`. |
+| `connect <claude-code\|codex>` | Registers your installed `memstack-mcp`, adds a session-start hook that loads project memories, and for Codex a marked block in `~/.codex/AGENTS.md`. Checks the server first and undoes everything if a step fails. `--dry-run`, `--no-hooks`, `--no-agents-md`. |
+| `disconnect <claude-code\|codex>` | Removes everything `connect` added, restoring each file exactly. Memories are kept. |
+| `status` | Config, storage, the current project, and each agent's connection, hook, and guidance. |
+| `doctor` | Diagnoses problems and prints the fix for each. `--live` tests the LLM key. Exits non-zero when it finds a problem. |
+| `memories [query]` | Lists or searches the current project's memories. `--global`, `--limit <n>`, `--delete <id>`. |
+| `project` | Shows the current project ID. `project pin <id>` writes `.memstack.json`; `project merge <old-id>` moves memories from an old ID. |
+
+These commands print readable text, not JSON, and read
+`~/.memstack/config.json` (or `$MEMSTACK_HOME/config.json`) overlaid with the
+environment variables below. Projects are identified by the repository's
+first commit, so clones, worktrees, and renamed remotes share memories. See
+[Harness Memory](https://github.com/isiomaC/memstack#harness-memory-claude-code--codex)
+for details.
+
 ## Configuration
 
-All via environment variables. Same scheme as @memstack/mcp.
+Every command reads `~/.memstack/config.json` (written by `memstack init`),
+overlaid with these environment variables: any LLM variable replaces the
+file's LLM settings, and `MEMSTACK_STORAGE` replaces its storage settings.
+`memstack status` shows which source is in use. Same scheme as @memstack/mcp.
 
 | Variable | Purpose | Default |
 |---|---|---|
@@ -29,7 +61,18 @@ All via environment variables. Same scheme as @memstack/mcp.
 
 ## Commands
 
-All output is JSON to stdout. Errors go to stderr.
+The memory commands below print JSON to stdout. Errors go to stderr.
+`memstack <command> --help` prints a command's flags; `memstack --version`
+prints the installed version.
+
+Inside a code repository, `--project` can replace `--actor` on any of them. It
+uses the repository's project, the same memory Claude Code and Codex share
+through `memstack connect`:
+
+```bash
+memstack store --project --content "Deploy with fly deploy" --type instruction
+memstack retrieve --project --query "deploy"
+```
 
 ### store
 ```bash

package/dist/cli.js

@@ -1,11 +1,12 @@
 #!/usr/bin/env node
 import { parseArgs } from 'util';
 import { readFile, writeFile } from 'fs/promises';
-import { MemStack, HarnessMemory, projectNamespace, defaultRecallNamespaces, AnthropicLLMAdapter, OpenAILLMAdapter, OpenAIEmbeddingAdapter, RedisStorageAdapter, SQLiteStorageAdapter, PostgresStorageAdapter, DiskStorageAdapter, MarkdownStorageAdapter, InMemoryStorageAdapter } from '@memstack/core';
-import { existsSync, mkdirSync, realpathSync, readFileSync, writeFileSync, statSync, chmodSync, renameSync, rmSync, copyFileSync, constants } from 'fs';
+import { createRequire } from 'module';
+import { projectNamespace, MemStack, HarnessMemory, defaultRecallNamespaces, AnthropicLLMAdapter, OpenAILLMAdapter, OpenAIEmbeddingAdapter, RedisStorageAdapter, SQLiteStorageAdapter, PostgresStorageAdapter, DiskStorageAdapter, MarkdownStorageAdapter, InMemoryStorageAdapter } from '@memstack/core';
+import { realpathSync, existsSync, mkdirSync, readFileSync, writeFileSync, statSync, chmodSync, renameSync, rmSync, copyFileSync, constants } from 'fs';
 import { homedir } from 'os';
-import { join, resolve, delimiter, dirname, basename } from 'path';
-import { execFile, spawn, execFileSync } from 'child_process';
+import { resolve, join, dirname, delimiter, basename } from 'path';
+import { execFile, execFileSync, spawn } from 'child_process';
 import { createHash } from 'crypto';
 import { createInterface } from 'readline/promises';
 
@@ -262,9 +263,6 @@ async function buildStorageAdapter(env) {
       throw new Error(`Unknown MEMSTACK_STORAGE: "${storage}". Supported: memory, markdown, disk, postgres, sqlite, redis`);
   }
 }
-async function loadConfigFromEnv() {
-  return buildConfig(process.env);
-}
 async function loadConfig(options = {}) {
   return buildConfig(mergeConfigFile(readConfigFile(options.configPath), process.env));
 }
@@ -304,7 +302,7 @@ async function buildConfig(env) {
 
 // src/config.ts
 async function loadConfig2() {
-  const { config } = await loadConfigFromEnv();
+  const { config } = await loadConfig();
   return config;
 }
 var createRunner = (env = process.env) => (command, args) => new Promise((resolve2) => {
@@ -337,9 +335,9 @@ function claudeCodeAdapter(options = {}) {
     // Also on clear and compact, so the memories survive /clear and context compaction.
     sessionHook: { path: settingsPath, matcher: "startup|resume|clear|compact" },
     async inspect() {
-      const version = await runner(binary, ["--version"]);
-      const state = { installed: version.code === 0, configPath };
-      if (state.installed) state.version = version.stdout.trim().split(/\s+/)[0];
+      const version2 = await runner(binary, ["--version"]);
+      const state = { installed: version2.code === 0, configPath };
+      if (state.installed) state.version = version2.stdout.trim().split(/\s+/)[0];
       state.entry = readEntry(configPath);
       return state;
     },
@@ -403,7 +401,7 @@ var CODEX_INSTRUCTIONS = [
   "## Project memory (MemStack)",
   "",
   "When the user asks you to remember something, save it with the memstack `memory_store` tool. Do not only acknowledge it, and do not write it into project files unless the user asks for a file change.",
-  "Before answering questions about this project's conventions, decisions, or the user's preferences, check `memory_retrieve`."
+  "At the start of a task, and before answering questions about this project's conventions, decisions, or the user's preferences, check `memory_retrieve`: it holds what earlier sessions, in Codex or other agents, were told to remember."
 ].join("\n");
 function renderBlock(body, harness) {
   return `${BEGIN} (managed by \`memstack connect ${harness}\`; removed by \`memstack disconnect ${harness}\`) -->
@@ -461,10 +459,10 @@ function codexAdapter(options = {}) {
     instructions: { path: join(home, "AGENTS.md"), body: CODEX_INSTRUCTIONS },
     sessionHook: { path: join(home, "hooks.json"), matcher: "startup|resume" },
     async inspect() {
-      const version = await runner(binary, ["--version"]);
-      const state = { installed: version.code === 0, configPath };
+      const version2 = await runner(binary, ["--version"]);
+      const state = { installed: version2.code === 0, configPath };
       if (!state.installed) return state;
-      state.version = version.stdout.trim().split(/\s+/).pop();
+      state.version = version2.stdout.trim().split(/\s+/).pop();
       const got = await runner(binary, ["mcp", "get", SERVER_NAME, "--json"]);
       if (got.code !== 0) {
         if (/No MCP server named/i.test(got.stderr + got.stdout)) return state;
@@ -978,9 +976,19 @@ async function disconnect(ids, flags) {
 var label = (name) => (name ? `${name}:` : "").padEnd(14);
 async function status() {
   const file = readConfigFile();
-  out(`${label("Config")}${file ? configFilePath() : "none (run `memstack init`)"}`);
-  if (file?.llm) out(`${label("LLM")}${file.llm.provider}${file.llm.model ? ` (${file.llm.model})` : ""}${file.llm.baseURL ? ` at ${file.llm.baseURL}` : ""}`);
-  if (file?.storage) out(`${label("Storage")}${file.storage.type}${file.storage.path ? ` at ${file.storage.path}` : file.storage.url ? " (URL configured)" : ""}`);
+  const fromEnv = envOverrides();
+  const config = file ? configFilePath() : fromEnv.llm || fromEnv.storage ? "none, using environment variables" : "none (run `memstack init`)";
+  out(`${label("Config")}${config}`);
+  const env = mergeConfigFile(file, process.env);
+  const envNote = (overridden) => overridden ? " (from environment variables)" : "";
+  if (env.OPENAI_API_KEY || env.ANTHROPIC_API_KEY) {
+    const provider = env.ANTHROPIC_API_KEY ? "anthropic" : "openai-compatible";
+    const baseURL = provider === "openai-compatible" ? env.MEMSTACK_OPENAI_BASE_URL : void 0;
+    out(`${label("LLM")}${provider}${env.MEMSTACK_LLM_MODEL ? ` (${env.MEMSTACK_LLM_MODEL})` : ""}${baseURL ? ` at ${baseURL}` : ""}${envNote(fromEnv.llm)}`);
+  } else if (file || fromEnv.llm) {
+    out(`${label("LLM")}no API key (run \`memstack init\`)`);
+  }
+  if (env.MEMSTACK_STORAGE) out(`${label("Storage")}${describeStorage(env)}${envNote(fromEnv.storage)}`);
   const project = resolveProject();
   out(`${label("Project")}${project.id} (${describeSource(project.source)}: ${project.key})`);
   const mcp = findMemstackMcp();
@@ -1008,6 +1016,20 @@ async function status() {
   }
   return 0;
 }
+function envOverrides() {
+  return {
+    llm: ["OPENAI_API_KEY", "ANTHROPIC_API_KEY", "MEMSTACK_OPENAI_BASE_URL", "MEMSTACK_LLM_MODEL"].some((key) => process.env[key] !== void 0),
+    storage: process.env.MEMSTACK_STORAGE !== void 0
+  };
+}
+function describeStorage(env) {
+  const type = env.MEMSTACK_STORAGE;
+  if (type === "memory") return "memory (lost when the process exits)";
+  const path = type === "sqlite" ? env.SQLITE_PATH : type === "disk" || type === "markdown" ? env.MEMSTACK_DIR : void 0;
+  if (path) return `${type} at ${path}`;
+  const url = type === "postgres" ? env.DATABASE_URL : type === "redis" ? env.REDIS_URL : void 0;
+  return url ? `${type} (URL configured)` : type;
+}
 function hookState(adapter, mcp) {
   const current = readHook(adapter.sessionHook.path);
   if (!current) return "missing";
@@ -1026,6 +1048,7 @@ async function doctor(flags) {
   try {
     file = readConfigFile();
     if (file) pass(`Config file ${configFilePath()}`);
+    else if (envOverrides().llm || envOverrides().storage) pass(`Using environment variables (no config file at ${configFilePath()})`);
     else warn(`No config file at ${configFilePath()}; run \`memstack init\`.`);
   } catch (error) {
     fail2(error.message);
@@ -1227,6 +1250,149 @@ function createPrompter() {
   };
 }
 
+// src/help.ts
+var ACTOR = `  --actor <id>       Actor ID that groups related memories
+  --project          Use this repository's project instead of --actor, the same
+                     memories Claude Code and Codex see through \`memstack connect\``;
+var MEMORY_ENV = `
+Reads ~/.memstack/config.json (written by \`memstack init\`); environment variables
+such as OPENAI_API_KEY and MEMSTACK_STORAGE override it. Prints JSON.
+`;
+var COMMAND_HELP = {
+  init: `memstack init [flags]
+
+Choose an LLM provider and a store, check the key with a real request, and write
+~/.memstack/config.json (readable only by you). Prompts for anything not given
+as a flag; with --yes or without a terminal it uses flags and existing values.
+
+  --provider <name>    openai-compatible (default) or anthropic
+  --base-url <url>     OpenAI-compatible endpoint, e.g. https://api.deepseek.com
+  --model <name>       Model override
+  --api-key-env <VAR>  Read the API key from this environment variable
+  --store <type>       Storage type (default: sqlite)
+  --path <path>        File or directory for sqlite, disk, or markdown
+  --url <url>          Connection URL for postgres, redis, or mongodb
+  --yes                Don't prompt
+`,
+  connect: `memstack connect <claude-code|codex> [flags]
+
+Register MemStack's MCP server with a harness, add a session-start hook that
+loads the project's memories, and for Codex add a marked block to
+~/.codex/AGENTS.md. Checks the server first and undoes every change if a step
+fails. Safe to run again.
+
+  --dry-run        Show what would change without changing it
+  --no-hooks       Skip the session-start hook
+  --no-agents-md   Skip the Codex AGENTS.md block
+`,
+  disconnect: `memstack disconnect <claude-code|codex> [flags]
+
+Remove everything \`memstack connect\` added. Memories are kept.
+
+  --dry-run   Show what would change without changing it
+`,
+  status: `memstack status
+
+Show where configuration comes from (config file or environment variables), the
+LLM and storage in use, this repository's project ID, and each harness's
+connection, guidance, and session-start hook.
+`,
+  doctor: `memstack doctor [flags]
+
+Check the configuration, storage driver, MCP server, and harness connections,
+and print a fix for each problem. Exits non-zero when it finds any.
+
+  --live   Also send a test request to the LLM provider
+`,
+  memories: `memstack memories [query] [flags]
+
+List this repository's memories (project and global), or search them.
+
+  --global        Only global memories
+  --limit <n>     Maximum to show (default: 20)
+  --delete <id>   Delete one memory
+`,
+  project: `memstack project [pin <id> | merge <old-id>]
+
+  memstack project               Show this repository's project ID and where it comes from
+  memstack project pin <id>      Write .memstack.json so every clone uses <id>
+  memstack project merge <old>   Move memories stored under an old project ID to this one
+`,
+  store: `memstack store --content <text> (--actor <id> | --project) [flags]
+
+${ACTOR}
+  --content <text>   Memory text (required)
+  --type <type>      interaction (default), summary, observation, fact, reflection,
+                     preference, decision, or instruction
+  --importance <n>   0.0 to 1.0
+  --tags <a,b>       Comma-separated tags
+${MEMORY_ENV}`,
+  retrieve: `memstack retrieve (--actor <id> | --project) [flags]
+
+${ACTOR}
+  --query <text>          Search text
+  --strategy <name>       recent (default), important, semantic, or hybrid
+  --limit <n>             Default: 10
+  --tags <a,b>            Only memories with these tags
+  --created-after <iso>   e.g. 2026-01-01T00:00:00Z
+  --created-before <iso>
+${MEMORY_ENV}`,
+  context: `memstack context (--actor <id> | --project) [flags]
+
+Compile memories into a token-budgeted system prompt.
+
+${ACTOR}
+  --max-tokens <n>   Token budget (default: 2000)
+${MEMORY_ENV}`,
+  summarize: `memstack summarize (--actor <id> | --project) [flags]
+
+Compress old interactions into summaries.
+
+${ACTOR}
+  --older-than <d>   Only memories older than this, e.g. 7d, 24h, 30m
+${MEMORY_ENV}`,
+  prune: `memstack prune (--actor <id> | --project) [flags]
+
+${ACTOR}
+  --type <name>            byAge (default), byImportance, or byCount
+  --max-age <d>            For byAge, e.g. 30d
+  --min-importance <n>     For byImportance
+  --max-count <n>          For byCount: keep the top n
+  --dry-run                Show what would be removed
+${MEMORY_ENV}`,
+  purge: `memstack purge (--actor <id> | --project)
+
+Delete every memory for the actor.
+
+${ACTOR}
+${MEMORY_ENV}`,
+  merge: `memstack merge --ids <id,id,...>
+
+Merge several memories into one.
+${MEMORY_ENV}`,
+  stats: `memstack stats [--actor <id> | --project]
+
+Memory counts and diagnostics; all actors when neither flag is given.
+${MEMORY_ENV}`,
+  delete: `memstack delete --id <id>
+${MEMORY_ENV}`,
+  health: `memstack health
+
+Check storage, LLM, and embedding connectivity.
+${MEMORY_ENV}`,
+  export: `memstack export [--actor <id> | --project] [--out <file>]
+
+Export memories as a JSON snapshot; all actors when neither flag is given.
+${MEMORY_ENV}`,
+  import: `memstack import (--actor <id> | --project) --file <file>
+
+Import memories from a JSON snapshot.
+
+${ACTOR}
+  --file <file>   Snapshot path (required)
+${MEMORY_ENV}`
+};
+
 // src/cli.ts
 process.stdout.on("error", (error) => {
   if (error.code === "EPIPE") process.exit(0);
@@ -1268,24 +1434,43 @@ async function main() {
       global: { type: "boolean" },
       delete: { type: "string" },
       "no-agents-md": { type: "boolean" },
-      "no-hooks": { type: "boolean" }
+      "no-hooks": { type: "boolean" },
+      project: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" }
     }
   });
+  if (values.version) {
+    process.stdout.write(`${version()}
+`);
+    return;
+  }
   const command = positionals[0];
+  if (command === "help" || values.help) {
+    const topic = command === "help" ? positionals[1] : command;
+    if (topic && !COMMAND_HELP[topic]) fail(`Unknown command: ${topic}. Run memstack --help for the list.`);
+    process.stdout.write(topic ? COMMAND_HELP[topic] : USAGE);
+    return;
+  }
   if (!command) {
-    printUsage();
+    process.stderr.write(USAGE);
     process.exit(1);
   }
   if (HARNESS_COMMANDS.includes(command)) {
     process.exitCode = await runHarnessCommand(command, positionals.slice(1), values);
     return;
   }
+  if (!COMMAND_HELP[command]) fail(`Unknown command: ${command}. Run memstack --help for the list.`);
+  if (values.project) {
+    if (values.actor) fail("Use either --actor or --project, not both");
+    values.actor = projectNamespace(resolveProject().id);
+  }
   const config = await loadConfig2();
   const ms = new MemStack(config);
   let result;
   switch (command) {
     case "store": {
-      if (!values.actor) fail("--actor is required");
+      if (!values.actor) fail("--actor (or --project) is required");
       if (!values.content) fail("--content is required");
       const importance = values.importance ? Math.max(0, Math.min(1, Number(values.importance))) : void 0;
       result = await ms.memory.store({
@@ -1298,7 +1483,7 @@ async function main() {
       break;
     }
     case "retrieve": {
-      if (!values.actor) fail("--actor is required");
+      if (!values.actor) fail("--actor (or --project) is required");
       result = await ms.memory.retrieve({
         actorId: values.actor,
         query: values.query,
@@ -1311,7 +1496,7 @@ async function main() {
       break;
     }
     case "context": {
-      if (!values.actor) fail("--actor is required");
+      if (!values.actor) fail("--actor (or --project) is required");
       result = await ms.memory.compileContext({
         actorId: String(values.actor),
         maxTokens: values["max-tokens"] ? Number(values["max-tokens"]) : void 0
@@ -1319,7 +1504,7 @@ async function main() {
       break;
     }
     case "summarize": {
-      if (!values.actor) fail("--actor is required");
+      if (!values.actor) fail("--actor (or --project) is required");
       const durationMs = values["older-than"] ? parseDuration(String(values["older-than"])) : void 0;
       const olderThan = durationMs ? new Date(Date.now() - durationMs) : void 0;
       result = await ms.memory.summarize({
@@ -1329,7 +1514,7 @@ async function main() {
       break;
     }
     case "prune": {
-      if (!values.actor) fail("--actor is required");
+      if (!values.actor) fail("--actor (or --project) is required");
       const VALID_TYPES = ["byAge", "byImportance", "byCount", "byType", "custom", "compose"];
       const pruneType = values.type ?? "byAge";
       if (!VALID_TYPES.includes(String(pruneType))) {
@@ -1350,7 +1535,7 @@ async function main() {
       break;
     }
     case "purge": {
-      if (!values.actor) fail("--actor is required");
+      if (!values.actor) fail("--actor (or --project) is required");
       result = await ms.memory.purgeActor(String(values.actor));
       break;
     }
@@ -1385,7 +1570,7 @@ async function main() {
       break;
     }
     case "import": {
-      if (!values.actor) fail("--actor is required");
+      if (!values.actor) fail("--actor (or --project) is required");
       if (!values.file) fail("--file is required");
       const raw = await readFile(String(values.file), "utf-8");
       let snapshot2 = JSON.parse(raw);
@@ -1400,8 +1585,7 @@ async function main() {
       break;
     }
     default:
-      printUsage();
-      process.exit(1);
+      fail(`Unknown command: ${command}. Run memstack --help for the list.`);
   }
   process.stdout.write(JSON.stringify(result, null, 2) + "\n");
   await ms.close();
@@ -1427,8 +1611,10 @@ function parseDuration(input) {
       return value;
   }
 }
-function printUsage() {
-  process.stderr.write(`memstack <command> [flags]
+function version() {
+  return createRequire(import.meta.url)("../package.json").version;
+}
+var USAGE = `memstack <command> [flags]
 
 Agent harnesses (Claude Code, Codex):
   init        Choose an LLM provider and store; writes ~/.memstack/config.json
@@ -1455,9 +1641,8 @@ Commands:
   export      Export all memories
   import      Import memories from a JSON snapshot
 
-Run memstack <command> --help for flags.
-`);
-}
+Run memstack <command> --help for flags, or memstack --version.
+`;
 function fail(message) {
   process.stderr.write(`Error: ${message}
 `);