open-memex 0.3.0 → 0.4.0-alpha.1

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,
@@ -34,6 +36,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>]
@@ -344,8 +352,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 +363,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 +374,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 +384,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 +404,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 +448,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 +520,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;

package/src/github.ts

@@ -0,0 +1,257 @@
+/**
+ * 2B/D32: GitHub PR ↔ review_state mapping.
+ *
+ * Memories ride into review inside a branch + PR (dedicated memory PR or
+ * together with code). The PR's lifecycle on GitHub is the team's review
+ * signal; this module reads it back and maps it onto each memory's own
+ * review_state:
+ *
+ *   PR merged                        → proposed/approved → published
+ *   PR reviewDecision == APPROVED     → proposed → approved (approved_by = reviewer login)
+ *   PR reviewDecision == CHANGES_REQUESTED → suggestion only, printed for the human
+ *
+ * Per-memory independence: every memory on the branch keeps its own state.
+ * A locally `rejected` memory is never flipped by a PR approval, and a
+ * changes-requested review never auto-rejects — the human runs `promote`.
+ *
+ * Report by default; `--apply` performs the mapped transitions locally
+ * (file rewrite + index, never a push — inside the D27 local-git line).
+ * Needs the GitHub CLI (`gh`) authenticated on the user's machine.
+ */
+
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { loadConfig } from "./config.ts";
+import { projectRoot } from "./paths.ts";
+import { parse as parseMemory, type ReviewState } from "./store/markdown.ts";
+import { iterInRepoMemoryFiles } from "./store/markdown.ts";
+import { promoteMemory, currentAuthor } from "./review.ts";
+
+function fail(msg: string): never {
+  throw new Error(`[open-memex] ${msg}`);
+}
+
+function sh(cmd: string, args: string[], cwd: string): string {
+  try {
+    return execFileSync(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  } catch (e) {
+    const err = e as { stderr?: string; message?: string };
+    const detail = (err.stderr ?? err.message ?? "").trim().split("\n")[0];
+    fail(`${cmd} ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`);
+  }
+}
+
+export interface PrInfo {
+  number: number;
+  url: string;
+  state: "open" | "closed"; // GitHub PR state
+  merged: boolean;
+  mergedAt: string | null;
+  reviewDecision: "APPROVED" | "CHANGES_REQUESTED" | "REVIEW_REQUIRED" | null;
+  approvedBy: string[];
+  changesRequestedBy: string[];
+  base: string;
+  head: string;
+  title: string;
+}
+
+interface GhPrJson {
+  number: number;
+  url: string;
+  state: string;
+  mergedAt: string | null;
+  isMerged?: boolean;
+  reviewDecision?: string | null;
+  baseRefName: string;
+  headRefName: string;
+  title: string;
+  reviews?: Array<{ author: { login: string }; state: string; submittedAt: string }>;
+}
+
+/** Read the PR for a branch (default: current branch) via the GitHub CLI. */
+export function getPrInfo(branch?: string): PrInfo | null {
+  const root = projectRoot();
+  // `gh` must exist and be authenticated on the user's machine.
+  try {
+    execFileSync("gh", ["--version"], { stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    fail("the GitHub CLI (`gh`) is not installed — install it and run `gh auth login` first.");
+  }
+  const ref = branch ?? sh("git", ["branch", "--show-current"], root);
+  if (!ref) fail("not on a branch — check out the memory branch first.");
+  let raw: string;
+  try {
+    raw = sh("gh", ["pr", "view", ref, "--json",
+      "number,url,state,mergedAt,reviewDecision,baseRefName,headRefName,title,reviews"], root);
+  } catch {
+    return null; // no PR for this branch yet
+  }
+  let j: GhPrJson;
+  try {
+    j = JSON.parse(raw) as GhPrJson;
+  } catch {
+    fail(`could not parse \`gh pr view\` output for branch ${ref}.`);
+  }
+  const approvedBy: string[] = [];
+  const changesRequestedBy: string[] = [];
+  // Latest review per author wins.
+  const latest = new Map<string, { state: string; at: string }>();
+  for (const r of j.reviews ?? []) {
+    const login = r.author?.login;
+    if (!login) continue;
+    const prev = latest.get(login);
+    if (!prev || r.submittedAt >= prev.at) latest.set(login, { state: r.state, at: r.submittedAt });
+  }
+  for (const [login, r] of latest) {
+    if (r.state === "APPROVED") approvedBy.push(login);
+    else if (r.state === "CHANGES_REQUESTED") changesRequestedBy.push(login);
+  }
+  return {
+    number: j.number,
+    url: j.url,
+    state: j.state === "OPEN" ? "open" : "closed",
+    merged: !!j.mergedAt,
+    mergedAt: j.mergedAt,
+    reviewDecision: (j.reviewDecision as PrInfo["reviewDecision"]) ?? null,
+    approvedBy,
+    changesRequestedBy,
+    base: j.baseRefName,
+    head: j.headRefName,
+    title: j.title,
+  };
+}
+
+export interface MemoryPrMapping {
+  memoryId: string;
+  from: ReviewState;
+  /** Null = no automatic transition; see reason. */
+  suggestedTo: ReviewState | null;
+  reason: string;
+  approvedBy: string | null;
+}
+
+export interface PrStatus {
+  branch: string;
+  pr: PrInfo | null;
+  mappings: MemoryPrMapping[];
+}
+
+/** Map the branch PR's state onto each in-repo memory's review_state. */
+export function getPrStatus(branch?: string): PrStatus {
+  const root = projectRoot();
+  const cfg = loadConfig();
+  const current = branch ?? sh("git", ["branch", "--show-current"], root);
+  const pr = getPrInfo(current);
+
+  const mappings: MemoryPrMapping[] = [];
+  for (const fp of iterInRepoMemoryFiles(root, cfg.memoryDir)) {
+    const raw = fs.readFileSync(fp, "utf8");
+    const parsed = parseMemory(raw);
+    if (!parsed) continue;
+    const from = parsed.fm.review_state ?? "draft";
+    const id = parsed.fm.id;
+    if (!pr) {
+      mappings.push({ memoryId: id, from, suggestedTo: null, reason: `no PR for branch ${current} yet`, approvedBy: null });
+      continue;
+    }
+    if (from === "published") {
+      mappings.push({ memoryId: id, from, suggestedTo: null, reason: "already published", approvedBy: null });
+      continue;
+    }
+    if (from === "rejected") {
+      mappings.push({ memoryId: id, from, suggestedTo: null, reason: `stays rejected — a PR ${pr.merged ? "merge" : "approval"} never overrides a human rejection`, approvedBy: null });
+      continue;
+    }
+    if (pr.merged) {
+      if (from === "proposed" || from === "approved") {
+        mappings.push({ memoryId: id, from, suggestedTo: "published", reason: `PR #${pr.number} merged`, approvedBy: null });
+      } else {
+        mappings.push({ memoryId: id, from, suggestedTo: null, reason: `PR #${pr.number} merged, but memory is "${from}"`, approvedBy: null });
+      }
+      continue;
+    }
+    if (pr.reviewDecision === "APPROVED" && from === "proposed") {
+      const by = pr.approvedBy[0] ?? null;
+      mappings.push({
+        memoryId: id, from, suggestedTo: "approved",
+        reason: `PR #${pr.number} approved${by ? ` by @${by}` : ""}`, approvedBy: by,
+      });
+      continue;
+    }
+    if (pr.reviewDecision === "CHANGES_REQUESTED") {
+      const by = pr.changesRequestedBy[0] ?? null;
+      mappings.push({
+        memoryId: id, from, suggestedTo: null,
+        reason: `PR #${pr.number} has changes requested${by ? ` by @${by}` : ""} — run \`open-memex promote ${id} --reject --note "..."\` yourself if you agree`,
+        approvedBy: null,
+      });
+      continue;
+    }
+    mappings.push({
+      memoryId: id, from, suggestedTo: null,
+      reason: pr.state === "open" ? `PR #${pr.number} still awaiting review` : `PR #${pr.number} is closed without merge`,
+      approvedBy: null,
+    });
+  }
+  return { branch: current, pr, mappings };
+}
+
+export interface PrApplyResult {
+  memoryId: string;
+  from: ReviewState;
+  to: ReviewState;
+  by: string;
+}
+
+/** Apply the mapped transitions locally (no push — D27). Advances step by
+ *  step through the ladder, so a merged PR moves proposed → approved →
+ *  published with each step in the audit trail. */
+export function applyPrStatus(st: PrStatus): PrApplyResult[] {
+  const out: PrApplyResult[] = [];
+  const actor = currentAuthor();
+  const order: ReviewState[] = ["draft", "proposed", "approved", "published"];
+  for (const m of st.mappings) {
+    if (!m.suggestedTo || order.indexOf(m.from) >= order.indexOf(m.suggestedTo)) continue;
+    const by = m.approvedBy ?? actor;
+    const note = m.suggestedTo === "published" && st.pr
+      ? `PR #${st.pr.number} merged`
+      : m.reason;
+    let cur = m.from;
+    while (order.indexOf(cur) < order.indexOf(m.suggestedTo)) {
+      const r = promoteMemory(m.memoryId, { by, note });
+      cur = r.to;
+      out.push({ memoryId: m.memoryId, from: r.from, to: r.to, by });
+    }
+  }
+  return out;
+}
+
+export function formatPrStatus(st: PrStatus): string {
+  const lines: string[] = [];
+  lines.push(`branch: ${st.branch}`);
+  if (!st.pr) {
+    lines.push(`PR: none yet — push the branch and open one, then re-run.`);
+  } else {
+    const p = st.pr;
+    lines.push(`PR #${p.number}: ${p.title}`);
+    lines.push(`  ${p.url}`);
+    lines.push(`  state: ${p.merged ? `merged${p.mergedAt ? ` at ${p.mergedAt}` : ""}` : p.state}` +
+      (p.reviewDecision ? `, reviews: ${p.reviewDecision}` : ""));
+    if (p.approvedBy.length > 0) lines.push(`  approved by: ${p.approvedBy.map((l) => "@" + l).join(", ")}`);
+    if (p.changesRequestedBy.length > 0) lines.push(`  changes requested by: ${p.changesRequestedBy.map((l) => "@" + l).join(", ")}`);
+  }
+  if (st.mappings.length === 0) {
+    lines.push(`no in-repo memories on this branch.`);
+  } else {
+    lines.push(`memories (${st.mappings.length}):`);
+    for (const m of st.mappings) {
+      const arrow = m.suggestedTo ? ` → [${m.suggestedTo}]` : "";
+      lines.push(`  ${m.memoryId.slice(0, 8)}  [${m.from}]${arrow}  ${m.reason}`);
+    }
+    if (st.mappings.some((m) => m.suggestedTo)) {
+      lines.push(`run with --apply to perform the mapped transitions locally (no push).`);
+    }
+  }
+  return lines.join("\n");
+}

package/src/index.ts

@@ -93,6 +93,12 @@ const plugin: Plugin = async ({ worktree, directory }) => {
           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: [],
         };
         try {
           const { filePath } = writeMemoryFile(fm, content);

package/src/init.ts

@@ -3,9 +3,9 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 import { DEFAULT_CONFIG, saveConfig } from "./config.ts";
+import { projectRoot } from "./paths.ts";
 
 const MARKER = "<!-- open-memex -->";
 
@@ -50,8 +50,10 @@ const INSTRUCTIONS = `${MARKER}
 > Applies only when the \`open-memex\` MCP server is available in this session
 > (the \`memory_*\` tools exist). Otherwise ignore this section.
 
-You have a local memory MCP server (\`open-memex\`) with five tools:
-\`memory_add\`, \`memory_search\`, \`memory_list\`, \`memory_supersede\`, \`memory_forget\`.
+You have a local memory MCP server (\`open-memex\`) with eleven tools:
+\`memory_add\`, \`memory_search\`, \`memory_list\`, \`memory_supersede\`, \`memory_forget\`,
+\`memory_status\`, \`memory_submit\`, \`memory_propose\`, \`memory_promote\`, \`memory_resolve\`,
+\`memory_pr_status\`.
 
 - BE PROACTIVE. When the user shares something worth remembering across sessions
   (a decision, a preference, a project convention, a fix and its cause), call
@@ -62,21 +64,32 @@ You have a local memory MCP server (\`open-memex\`) with five tools:
 - Memories default to this project's scope; use the \`personal\` scope for facts about
   the user that hold across all projects. When a saved fact becomes outdated, call
   \`memory_supersede\` instead of adding a duplicate.
-`;
 
-/** Project root: git top-level, falling back to cwd. */
-function projectRoot(): string {
-  try {
-    const top = execFileSync("git", ["rev-parse", "--show-toplevel"], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
-    if (top) return top;
-  } catch {
-    /* not a git repo — use cwd */
-  }
-  return process.cwd();
-}
+## Syncing project memories for review (D26)
+
+Project memories you save land in a local outbox first — they are NOT in git yet.
+Syncing them into the repo for review is an explicit, user-approved step:
+
+- At session start, and when you finish a meaningful chunk of work, call
+  \`memory_status\`. If the outbox has drafts, summarize them (one line each) and ask
+  the user which ones to sync. Sync NOTHING the user did not name.
+- When the user approves, ask ONE follow-up: a separate memory-only branch/PR
+  (recommended), or fold the memories into the current branch alongside code?
+  A "yes, you do it" answer covers the whole chain — branch, local commit,
+  push, PR creation — do NOT re-ask at each step. If the user says they will
+  do it themselves, hand them the printed push/PR commands and do nothing.
+  Then call \`memory_submit\` with the approved ids (\`onto\` = current branch name
+  only for the fold-into-code path). It creates the branch, copies the drafts in
+  as \`proposed\`, commits locally, and prints the push + PR commands.
+- Base branch for the memory PR defaults to the branch you are on; the user may
+  redirect it to the integration branch (main) for branch-independent knowledge.
+- If anything conflicts (same id with different content, push rejected), STOP and
+  let the user judge — never overwrite.
+- After the PR merges, call \`memory_pr_status\` (with \`apply\` when the user
+  approves) to map the PR's review state back onto each memory — merged means
+  \`published\`, an approval means \`approved\` (credited to the reviewer).
+- \`personal\` scope memories NEVER leave the machine.
+`;
 
 function writeMcpJson(root: string, client: string, force: boolean): string | null {
   if (client === "opencode") return writeOpencodeMcpJson(root, force);