open-memex 0.3.0 → 0.4.0-alpha.4

package/src/cli.ts

@@ -6,11 +6,13 @@ import { syncScope, upsertFromFile, deleteFromIndex } from "./store/sync.ts";
 import { migrateScope, scopeHasFiles, type ConflictStrategy } from "./store/migrate.ts";
 import { migrateV2 } from "./store/v2migrate.ts";
 import { findDuplicates, supersede, setStatus } from "./store/lifecycle.ts";
-import { search, list } from "./retrieve/search.ts";
+import { proposeMemories, promoteMemory, listConflicts, resolveConflict, formatReviewHistory } from "./review.ts";
+import { getSyncStatus, formatSyncStatus, submitMemories } from "./submit.ts";
+import { getPrStatus, formatPrStatus, applyPrStatus } from "./github.ts";
+import { search, list, hitStateLabel } from "./retrieve/search.ts";
 import {
   writeMemoryFile,
   readMemoryFile,
-  deleteMemoryFile,
   ulid,
   msToRfc3339,
   type Frontmatter,
@@ -23,6 +25,189 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+/** Per-command help, printed by `open-memex <command> --help`.
+    AI assistants discover the CLI through --help, so every command needs one. */
+const COMMAND_HELP: Record<string, string> = {
+  where: `Show which project scope the current directory resolves to, and where its data lives.
+
+Usage: open-memex where`,
+
+  list: `List memories in a scope, newest first.
+
+Usage: open-memex list [--scope project|personal] [--type T] [--limit N]
+
+Flags:
+  --scope   project (default) or personal
+  --type    filter by memory type
+  --limit   max results
+
+Examples:
+  open-memex list
+  open-memex list --scope personal --limit 20`,
+
+  search: `Search memories by keyword (BM25 full-text), best matches first.
+
+Usage: open-memex search "query" [--scope project|personal|both] [--type T] [--limit N]
+
+Flags:
+  --scope   project (default), personal, or both
+  --type    filter by memory type
+  --limit   max results
+
+Example:
+  open-memex search "deploy checklist" --scope both`,
+
+  add: `Save a fact, preference, decision, or note to local memory.
+
+Usage: open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
+
+Flags:
+  --scope   project (default) or personal (personal never leaves this machine)
+  --type    memory type (default: fact)
+  --tag     comma-separated tags
+
+Example:
+  open-memex add "We deploy on Fridays" --scope project --tag process`,
+
+  supersede: `Replace a memory with a newer version. The old one is kept as history.
+
+Usage: open-memex supersede <id> "new content" [--type T] [--tag t1,t2]`,
+
+  status: `Change a memory's lifecycle status.
+
+Usage: open-memex status <id> active|deprecated|retracted|archived`,
+
+  forget: `Delete a memory by id.
+
+Usage: open-memex forget <id>`,
+
+  propose: `Copy personal memories into the project outbox as review drafts.
+The personal originals stay put. Nothing enters git at this step.
+
+Usage: open-memex propose <id...> --to project [--local-approve]
+
+Flags:
+  --to             project (required)
+  --local-approve  mark the copies approved right away (solo-dev shortcut)
+
+Example:
+  open-memex propose 01ABC 01DEF --to project`,
+
+  promote: `Advance a project memory one step up the review ladder
+(proposed → approved → published), or reject it with a note.
+Every transition is appended to the memory's review_history.
+Rejected memories are never deleted — they can be revised and resubmitted.
+
+Usage: open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
+
+Flags:
+  --reject    move back to rejected (requires --note)
+  --resubmit  move a rejected memory back to proposed
+  --note      reason for the transition (recorded in review_history)
+  --by        reviewer name (defaults to the git user)
+
+Examples:
+  open-memex promote 01ABC --note "verified against the runbook"
+  open-memex promote 01ABC --reject --note "outdated after the migration"`,
+
+  resolve: `List conflicted memories, or 3-way-merge one.
+
+Usage: open-memex resolve [id-or-path]
+
+With no argument, lists conflicts. With an id or file path, shows the
+3-way merge (base / outbox / repo) so you can resolve it by hand.
+Conflicts are never auto-resolved.`,
+
+  "sync-status": `Show the project memory sync pipeline: when the index last synced
+and what triggered it, drafts waiting in the outbox (appdata), memories in the
+repo awaiting review or published, and repo files not yet committed.
+
+Usage: open-memex sync-status`,
+
+  submit: `Move outbox drafts into a git branch for review: creates a branch
+(default mem/sync-*), copies the drafts into the repo memory dir as proposed
+(local-approved copies keep their approval), commits locally, and moves the
+outbox originals out. Prints the push and PR commands — those need your
+explicit approval and are never run automatically.
+
+Usage: open-memex submit <id...> [--onto <branch>] [--base <branch>]
+
+Flags:
+  --onto   submit onto the current branch instead of creating mem/sync-*
+  --base   base branch for the PR suggestion (default: the branch you're on)
+
+Example:
+  open-memex submit 01ABC 01DEF`,
+
+  "pr-status": `Map the current branch's GitHub PR state back onto review_state:
+merged → published, approval → approved (approved_by = the reviewer),
+changes-requested → suggestion only (never auto-rejects).
+Each memory in the PR is mapped independently; a human rejection is never
+overwritten. Report-only by default.
+
+Usage: open-memex pr-status [--apply]
+
+Flags:
+  --apply   write the transitions locally (still never pushes)`,
+
+  reindex: `Rebuild the SQLite index from the markdown files.
+
+Usage: open-memex reindex`,
+
+  scopes: `List the known scopes (personal + project).
+
+Usage: open-memex scopes`,
+
+  migrate: `Move memories between scopes, or convert a legacy my-o-memory data dir.
+
+Usage: open-memex migrate [--from <key>] [--to <key>] [--dry-run] [--on-conflict newer|overwrite|skip]
+       open-memex migrate --to-v2 [--dry-run]
+
+Flags:
+  --from / --to   scope keys (default: current project → personal)
+  --dry-run       preview without moving anything
+  --on-conflict   newer (default), overwrite, or skip
+  --to-v2         convert a legacy my-o-memory data dir to the v2 layout
+
+Always preview with --dry-run first; nothing moves without confirmation.`,
+
+  mcp: `Start the stdio MCP server (the same server editors connect to).
+
+Usage: open-memex mcp [--print-config vscode|cursor|claude|opencode|visualstudio]
+
+Flags:
+  --print-config   print the MCP client config instead of starting the server`,
+
+  init: `One-command project setup: writes the MCP config for your editor and the
+agent memory instructions. Existing files are merged, never clobbered.
+
+Usage: open-memex init [--client vscode|cursor|opencode|visualstudio]
+              [--instructions personal|project] [--force] [--yes]
+
+Flags:
+  --client        editor to configure (default: auto-detect)
+  --instructions  personal (default, ~/.copilot/copilot-instructions.md) or project
+  --force         overwrite existing config
+  --yes           accept all defaults, never prompt`,
+
+  config: `Show config, or set a key.
+
+Usage: open-memex config [set <key> <value>]
+
+Example:
+  open-memex config set sync.autoPull false`,
+
+  capture: `Preview what the keyword-capture watcher would extract from text.
+
+Usage: open-memex capture --dry-run "text"`,
+
+  doctor: `Environment health check: Node version, config source, scope resolution,
+storage writability, then boots a real MCP server and runs initialize +
+tools/list against it — all eleven tools must show up.
+
+Usage: open-memex doctor`,
+};
+
 function usage(exitCode = 1): never {
   console.log(`open-memex CLI
 
@@ -34,6 +219,12 @@ Usage:
   open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
   open-memex status <id> active|deprecated|retracted|archived
   open-memex forget <id>
+  open-memex propose <id...> --to project [--local-approve]
+  open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
+  open-memex resolve [id-or-path]
+  open-memex sync-status
+  open-memex submit <id...> [--onto <branch>] [--base <branch>]
+  open-memex pr-status [--apply]
   open-memex reindex
   open-memex scopes
   open-memex migrate [--from <key>] [--to <key>]
@@ -71,7 +262,9 @@ the \`--from\` key when migrating.
 git remote after memories were already stored under the cwd-based key.
 \`migrate --to-v2\` converts v1 memory files to the v2 format (§19):
 user→personal scope rename, epoch→RFC 3339 times, priority→importance,
-type: instruction→role split. Always preview with --dry-run first.`);
+type: instruction→role split. Always preview with --dry-run first.
+
+Run \`open-memex <command> --help\` for details on a single command.`);
   process.exit(exitCode);
 }
 
@@ -196,6 +389,17 @@ async function main() {
     return;
   }
 
+  // Per-command help: `open-memex <command> --help`. Checked before loadConfig()
+  // so it works even when the environment is broken.
+  if (rest.includes("--help") || rest.includes("-h")) {
+    const h = COMMAND_HELP[cmd];
+    if (h) {
+      console.log(`open-memex ${cmd}\n\n${h}`);
+      return;
+    }
+    usage(0);
+  }
+
   const cfg = loadConfig();
   const project = resolveProjectScope(process.cwd());
 
@@ -344,8 +548,8 @@ async function main() {
   }
 
   if (cmd === "reindex") {
-    const a = syncScope(project.key);
-    const b = syncScope(PERSONAL_SCOPE.key);
+    const a = syncScope(project.key, "cli");
+    const b = syncScope(PERSONAL_SCOPE.key, "cli");
     console.log(
       `reindexed. project: +${a.added} ~${a.updated} -${a.removed} (scanned ${a.scanned}), personal: +${b.added} ~${b.updated} -${b.removed} (scanned ${b.scanned})`,
     );
@@ -355,7 +559,7 @@ async function main() {
   if (cmd === "list") {
     const flags = parseFlags(rest);
     const s = resolveCliScope(flags, project);
-    syncScope(s.key);
+    syncScope(s.key, "cli");
     const hits = list(s.key, {
       type: flags.type,
       limit: flags.limit ? Number(flags.limit) : undefined,
@@ -366,7 +570,8 @@ async function main() {
     }
     for (const h of hits) {
       const dep = h.status === "deprecated" ? " [deprecated]" : "";
-      console.log(`[${h.type}]${dep} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
+      const rev = hitStateLabel(h);
+      console.log(`[${h.type}]${dep}${rev} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
     }
     return;
   }
@@ -375,8 +580,8 @@ async function main() {
     const query = rest[0];
     if (!query || query.startsWith("--")) usage();
     const flags = parseFlags(rest.slice(1));
-    syncScope(project.key);
-    syncScope(PERSONAL_SCOPE.key);
+    syncScope(project.key, "cli");
+    syncScope(PERSONAL_SCOPE.key, "cli");
     const keys =
       flags.scope === "personal" || flags.scope === "user"
         ? [PERSONAL_SCOPE.key]
@@ -395,7 +600,8 @@ async function main() {
     for (const h of hits) {
       const tag = h.scope_key === PERSONAL_SCOPE.key ? "personal" : "project";
       const dep = h.status === "deprecated" ? " [deprecated]" : "";
-      console.log(`[${tag}/${h.type}]${dep} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
+      const rev = hitStateLabel(h);
+      console.log(`[${tag}/${h.type}]${dep}${rev} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
     }
     return;
   }
@@ -438,6 +644,12 @@ async function main() {
       updated_at: rfc,
       supersedes: null,
       superseded_by: null,
+      review_state: "draft",
+      proposed_by: null,
+      approved_by: null,
+      derived_from: null,
+    review_note: null,
+    review_history: [],
     };
     const { filePath } = writeMemoryFile(fm, red);
     const mf = readMemoryFile(filePath);
@@ -504,19 +716,195 @@ async function main() {
   if (cmd === "forget") {
     const id = rest[0];
     if (!id) usage();
-    const row = db().prepare(`SELECT scope_key FROM memories WHERE id = ?`).get(id) as
-      | { scope_key: string }
+    const row = db().prepare(`SELECT file_path FROM memories WHERE id = ?`).get(id) as
+      | { file_path: string }
       | undefined;
     if (!row) {
       console.error("not found");
       process.exit(1);
     }
-    deleteMemoryFile(row.scope_key, id);
+    // Delete by indexed file_path — location-agnostic (appdata or in-repo, 2B/D24).
+    if (row.file_path) {
+      try {
+        fs.unlinkSync(row.file_path);
+      } catch {
+        /* already gone */
+      }
+    }
     deleteFromIndex(id);
     console.log(`deleted ${id}`);
     return;
   }
 
+/** Positional args with flags (and their values) skipped. */
+function positionalArgs(argv: string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a.startsWith("--")) {
+      const val = argv[i + 1];
+      if (val !== undefined && !val.startsWith("--")) i++; // skip the flag's value
+    } else {
+      out.push(a);
+    }
+  }
+  return out;
+}
+
+  if (cmd === "propose") {
+    const flags = parseFlags(rest);
+    const ids = positionalArgs(rest);
+    if (ids.length === 0) usage();
+    const to = flags.to ?? "project";
+    if (to !== "project") {
+      console.error(`propose --to "${to}" is not supported yet (org sharing is Phase 4).`);
+      process.exit(2);
+    }
+    try {
+      const batch = proposeMemories(ids, { localApprove: flags["local-approve"] === "true" });
+      for (const { sourceId, result: r } of batch) {
+        console.log(`proposed ${sourceId} → ${r.id}  [${r.reviewState}]`);
+      }
+      console.log(`Next: these are drafts in the outbox (appdata) — nothing is in git yet.`);
+      console.log(`  open-memex sync-status`);
+      console.log(`  open-memex submit ${batch.map(({ result: r }) => r.id).join(" ")}   # new branch, local commit; prints push + PR commands`);
+    } catch (e) {
+      console.error(`propose failed: ${(e as Error).message}`);
+      process.exit(2);
+    }
+    return;
+  }
+
+  if (cmd === "promote") {
+    const flags = parseFlags(rest);
+    const id = rest.find((a) => !a.startsWith("--"));
+    if (!id) usage();
+    try {
+      const r = promoteMemory(id, {
+        reject: flags.reject === "true",
+        resubmit: flags.resubmit === "true",
+        note: flags.note,
+        by: flags.by,
+      });
+      console.log(`promote ${r.id}: ${r.from} → ${r.to}`);
+      if (r.to === "published") {
+        console.log(`  merged to the shared branch? Teammates pick it up with an explicit pull.`);
+      }
+      if (r.to === "rejected") {
+        console.log(`  not deleted — the file stays on your branch. Your call:`);
+        console.log(`  accept: close the PR and delete the branch;`);
+        console.log(`  revise: edit the file, then \`open-memex promote ${r.id} --resubmit\`;`);
+        console.log(`  keep: leave it as a [rejected] record.`);
+      }
+      if (r.history.length > 0) {
+        console.log(`  history (${r.history.length}):`);
+        for (const h of formatReviewHistory(r.history)) console.log(h);
+      }
+    } catch (e) {
+      console.error(`promote failed: ${(e as Error).message}`);
+      process.exit(2);
+    }
+    return;
+  }
+
+  if (cmd === "resolve") {
+    const target = rest.find((a) => !a.startsWith("--"));
+    try {
+      if (!target) {
+        const conflicts = listConflicts();
+        if (conflicts.length === 0) {
+          console.log("(no conflicted memory files)");
+        } else {
+          for (const c of conflicts) console.log(`conflicted: ${c.id}  ${c.filePath}`);
+          console.log(`\nRun \`open-memex resolve <id>\` to attempt a field-level 3-way merge.`);
+        }
+        return;
+      }
+      const outcome = resolveConflict(target);
+      if (!outcome.ok) {
+        console.error(`cannot auto-resolve ${path.basename(outcome.filePath)} — semantic conflicts need a human:`);
+        for (const c of outcome.conflicts) {
+          console.error(`  ${c.field}:`);
+          console.error(`    base:   ${c.base}`);
+          console.error(`    ours:   ${c.ours}`);
+          console.error(`    theirs: ${c.theirs}`);
+        }
+        console.error(`Edit the file manually, then \`git add\` it. Nothing was written.`);
+        process.exit(3);
+      }
+      console.log(`resolved ${path.basename(outcome.filePath)}`);
+      if (outcome.autoMerged.length > 0)
+        console.log(`  auto-merged: ${outcome.autoMerged.join(", ")}`);
+      console.log(`  next: git add ${path.relative(process.cwd(), outcome.filePath)}`);
+    } catch (e) {
+      console.error(`resolve failed: ${(e as Error).message}`);
+      process.exit(2);
+    }
+    return;
+  }
+
+  if (cmd === "sync-status") {
+    syncScope(project.key, "cli");
+    syncScope(PERSONAL_SCOPE.key, "cli");
+    try {
+      console.log(formatSyncStatus(getSyncStatus()));
+    } catch (e) {
+      console.error(`sync-status failed: ${(e as Error).message}`);
+      process.exit(2);
+    }
+    return;
+  }
+
+  if (cmd === "pr-status") {
+    const flags = parseFlags(rest);
+    try {
+      const st = getPrStatus();
+      console.log(formatPrStatus(st));
+      if (flags.apply === "true") {
+        const applied = applyPrStatus(st);
+        if (applied.length === 0) {
+          console.log(`nothing to apply.`);
+        } else {
+          for (const a of applied) {
+            console.log(`applied ${a.memoryId.slice(0, 8)}: ${a.from} → ${a.to} (by ${a.by})`);
+          }
+        }
+      }
+    } catch (e) {
+      console.error(`pr-status failed: ${(e as Error).message}`);
+      process.exit(2);
+    }
+    return;
+  }
+
+  if (cmd === "submit") {
+    const flags = parseFlags(rest);
+    const ids = positionalArgs(rest);
+    if (ids.length === 0) usage();
+    syncScope(project.key, "submit");
+    try {
+      const r = submitMemories(ids, { onto: flags.onto, base: flags.base });
+      for (const s of r.submitted) {
+        console.log(`submitted ${s.id} → ${path.relative(process.cwd(), s.filePath)}  [${s.reviewState}]`);
+      }
+      for (const id of r.skippedIdentical) {
+        console.log(`already on branch: ${id} (identical content — outbox copy removed)`);
+      }
+      if (!r.committed) {
+        console.log(`nothing new to commit — branch ${r.branch} already holds these memories.`);
+      } else {
+        console.log(`committed on ${r.branch}.`);
+      }
+      console.log(`Next (needs your approval — open-memex never pushes for you):`);
+      console.log(`  ${r.pushCommand}`);
+      console.log(`  ${r.prCommand}`);
+    } catch (e) {
+      console.error(`submit failed: ${(e as Error).message}`);
+      process.exit(2);
+    }
+    return;
+  }
+
   if (cmd === "scopes") {
     const { memories } = paths();
     if (!fs.existsSync(memories)) {

package/src/config.ts

@@ -13,6 +13,12 @@ export interface MyOMemoryConfig {
   keywordPersonalPatterns: string[];
   redactPatterns: string[];
   logLevel: "debug" | "info" | "warn" | "error";
+  /**
+   * In-repo project-memory directory, relative to the project root (2B/D23).
+   * Default `.ai/open-memex/`. Must stay relative and `..`-free so project
+   * memories can never escape the repo.
+   */
+  memoryDir: string;
 }
 
 export const DEFAULT_CONFIG: MyOMemoryConfig = {
@@ -47,6 +53,7 @@ export const DEFAULT_CONFIG: MyOMemoryConfig = {
   // Add only your own extra patterns here.
   redactPatterns: [],
   logLevel: "info",
+  memoryDir: ".ai/open-memex",
 };
 
 function stripJsonComments(raw: string): string {
@@ -80,12 +87,21 @@ function toNonNegInt(v: unknown): number {
   return n;
 }
 
+function toRelativeDir(v: unknown): string {
+  if (typeof v !== "string" || !v.trim()) throw new Error("must be a non-empty relative directory");
+  const t = v.trim().replace(/\\/g, "/").replace(/\/+$/, "");
+  if (!t || path.isAbsolute(t) || t.split("/").includes(".."))
+    throw new Error('must be a relative path without ".." (e.g. ".ai/open-memex")');
+  return t;
+}
+
 /** Keys users may change via `open-memex config set <key> <value>`, with validators. */
 export const SETTABLE_KEYS: Record<string, (v: unknown) => unknown> = {
   maxProjectMemories: toNonNegInt,
   maxProfileItems: toNonNegInt,
   injectOnFirstTurn: toBool,
   keywordCaptureEnabled: toBool,
+  memoryDir: toRelativeDir,
   logLevel: (v) => {
     if (v !== "info" && v !== "debug") throw new Error('must be "info" or "debug"');
     return v;