open-memex 0.3.0 → 0.4.0-alpha.4

package/dist/cli.js

@@ -6,8 +6,11 @@ import { syncScope, upsertFromFile, deleteFromIndex } from "./store/sync.js";
 import { migrateScope, scopeHasFiles } from "./store/migrate.js";
 import { migrateV2 } from "./store/v2migrate.js";
 import { findDuplicates, supersede, setStatus } from "./store/lifecycle.js";
-import { search, list } from "./retrieve/search.js";
-import { writeMemoryFile, readMemoryFile, deleteMemoryFile, ulid, msToRfc3339, } from "./store/markdown.js";
+import { proposeMemories, promoteMemory, listConflicts, resolveConflict, formatReviewHistory } from "./review.js";
+import { getSyncStatus, formatSyncStatus, submitMemories } from "./submit.js";
+import { getPrStatus, formatPrStatus, applyPrStatus } from "./github.js";
+import { search, list, hitStateLabel } from "./retrieve/search.js";
+import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, } from "./store/markdown.js";
 import { loadConfig } from "./config.js";
 import { paths } from "./paths.js";
 import { redact } from "./redact.js";
@@ -15,6 +18,168 @@ import { resolveMcpCommand } from "./init.js";
 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 = {
+    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) {
     console.log(`open-memex CLI
 
@@ -26,6 +191,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>]
@@ -63,7 +234,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);
 }
 function parseFlags(argv) {
@@ -163,6 +336,16 @@ async function main() {
         console.log(`open-memex ${pkg.version}`);
         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());
     // `migrate --to-v2` is a pure file operation (V2-DESIGN §19) — it runs
@@ -294,15 +477,15 @@ async function main() {
         return;
     }
     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})`);
         return;
     }
     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,
@@ -313,7 +496,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;
     }
@@ -322,8 +506,8 @@ async function main() {
         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]
             : flags.scope === "project"
@@ -341,7 +525,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;
     }
@@ -384,6 +569,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);
@@ -447,16 +638,202 @@ async function main() {
         const id = rest[0];
         if (!id)
             usage();
-        const row = db().prepare(`SELECT scope_key FROM memories WHERE id = ?`).get(id);
+        const row = db().prepare(`SELECT file_path FROM memories WHERE id = ?`).get(id);
         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) {
+        const out = [];
+        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.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.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.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.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.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.message}`);
+            process.exit(2);
+        }
+        return;
+    }
     if (cmd === "scopes") {
         const { memories } = paths();
         if (!fs.existsSync(memories)) {

package/dist/config.js

@@ -33,6 +33,7 @@ export const DEFAULT_CONFIG = {
     // Add only your own extra patterns here.
     redactPatterns: [],
     logLevel: "info",
+    memoryDir: ".ai/open-memex",
 };
 function stripJsonComments(raw) {
     // Line comments
@@ -63,12 +64,21 @@ function toNonNegInt(v) {
         throw new Error("must be a non-negative integer");
     return n;
 }
+function toRelativeDir(v) {
+    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 = {
     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"');