open-memex 0.3.0 → 0.4.0-alpha.4

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,35 @@ 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 says "sync memory" (or "同步记忆"), treat it as a request to run
+  the sync flow above: call \`memory_status\`, summarize the outbox drafts, and ask
+  which ones to sync.
+- 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);

package/src/mcp.ts

@@ -30,17 +30,56 @@ import {
   listMemories,
   supersedeMemory,
   forgetMemory,
+  statusMemories,
+  submitMemoriesOp,
+  proposeMemoriesOp,
+  promoteMemoryOp,
+  resolveMemoryOp,
+  prStatusOp,
   memoryAddArgs,
   memorySearchArgs,
   memoryListArgs,
   memorySupersedeArgs,
   memoryForgetArgs,
+  memoryStatusArgs,
+  memorySubmitArgs,
+  memoryProposeArgs,
+  memoryPromoteArgs,
+  memoryResolveArgs,
+  memoryPrStatusArgs,
   TOOL_DESCRIPTIONS,
   type ToolResult,
 } from "./tools/ops.ts";
 
 const SERVER_VERSION = "0.2.0-alpha";
 
+/**
+ * D26: session-start guidance delivered through the MCP handshake itself.
+ * The init-written instruction files only exist if the user ran
+ * `open-memex init --client`; the initialize `instructions` reach every MCP
+ * client at connect time. Still advisory — no MCP consumer offers a hard
+ * session-start hook — but it is the strongest signal available.
+ */
+const SERVER_INSTRUCTIONS = `You are connected to an open-memex local memory MCP server
+(eleven memory_* tools: add, search, list, supersede, forget, status, submit,
+propose, promote, resolve, pr_status).
+
+- At the START of this session, call memory_status. If the project outbox has
+  drafts waiting for review, summarize them (one line each) and ask the user
+  which ones to sync into the repo. Sync NOTHING the user did not name.
+- When the user says "sync memory" (or "同步记忆"), treat it as a request to run
+  the sync flow: call memory_status, summarize the outbox drafts, and ask which
+  ones to sync.
+- When you finish a meaningful chunk of work, call memory_status again as a checkpoint.
+- BE PROACTIVE: when the user shares something worth remembering across sessions
+  (a decision, a preference, a project convention, a fix and its cause), call
+  memory_add without being asked. Keep each memory to one self-contained statement.
+- Before asking the user about past decisions, conventions, or preferences they
+  may have told you before, call memory_search first.
+- Memories default to this project's scope; use the personal scope for facts
+  about the user that hold across all projects.
+- personal scope memories NEVER leave this machine.`;
+
 /** Adapt a framework-agnostic op result to an MCP tool response. */
 function toMcp(p: Promise<ToolResult>) {
   return p.then(
@@ -64,11 +103,25 @@ export async function runMcpServer() {
 
   // Init DB and one-shot sync of markdown -> index, mirroring the plugin.
   db();
-  syncScope(scope.key);
-  syncScope(PERSONAL_SCOPE.key);
+  syncScope(scope.key, "session");
+  syncScope(PERSONAL_SCOPE.key, "session");
   console.error(`[open-memex] MCP server up. scope=${scope.key}`);
 
-  const server = new McpServer({ name: "open-memex", version: SERVER_VERSION });
+  // D26: re-sync on every request, not just at startup. The in-repo dir
+  // follows the current git branch, so a branch switch mid-session would
+  // otherwise leave the index pointing at files that no longer exist.
+  const withSync = <A extends object, R>(fn: (args: A) => R) => {
+    return (args: A): R => {
+      syncScope(scope.key, "request");
+      syncScope(PERSONAL_SCOPE.key, "request");
+      return fn(args);
+    };
+  };
+
+  const server = new McpServer(
+    { name: "open-memex", version: SERVER_VERSION },
+    { instructions: SERVER_INSTRUCTIONS },
+  );
 
   server.registerTool(
     "memory_add",
@@ -76,7 +129,7 @@ export async function runMcpServer() {
       description: TOOL_DESCRIPTIONS.memory_add,
       inputSchema: z.object(memoryAddArgs),
     },
-    (args) => toMcp(addMemory(getScope, cfg, args)),
+    withSync((args) => toMcp(addMemory(getScope, cfg, args))),
   );
 
   server.registerTool(
@@ -86,7 +139,7 @@ export async function runMcpServer() {
       inputSchema: z.object(memorySearchArgs),
       annotations: { readOnlyHint: true },
     },
-    (args) => toMcp(searchMemories(getScope, args)),
+    withSync((args) => toMcp(searchMemories(getScope, args))),
   );
 
   server.registerTool(
@@ -96,7 +149,7 @@ export async function runMcpServer() {
       inputSchema: z.object(memoryListArgs),
       annotations: { readOnlyHint: true },
     },
-    (args) => toMcp(listMemories(getScope, args)),
+    withSync((args) => toMcp(listMemories(getScope, args))),
   );
 
   server.registerTool(
@@ -105,7 +158,7 @@ export async function runMcpServer() {
       description: TOOL_DESCRIPTIONS.memory_supersede,
       inputSchema: z.object(memorySupersedeArgs),
     },
-    (args) => toMcp(supersedeMemory(cfg, args)),
+    withSync((args) => toMcp(supersedeMemory(cfg, args))),
   );
 
   server.registerTool(
@@ -115,7 +168,63 @@ export async function runMcpServer() {
       inputSchema: z.object(memoryForgetArgs),
       annotations: { destructiveHint: true },
     },
-    (args) => toMcp(forgetMemory(args)),
+    withSync((args) => toMcp(forgetMemory(args))),
+  );
+
+  server.registerTool(
+    "memory_status",
+    {
+      description: TOOL_DESCRIPTIONS.memory_status,
+      inputSchema: z.object(memoryStatusArgs),
+      annotations: { readOnlyHint: true },
+    },
+    withSync((_args) => toMcp(statusMemories())),
+  );
+
+  server.registerTool(
+    "memory_submit",
+    {
+      description: TOOL_DESCRIPTIONS.memory_submit,
+      inputSchema: z.object(memorySubmitArgs),
+    },
+    withSync((args) => toMcp(submitMemoriesOp(args))),
+  );
+
+  server.registerTool(
+    "memory_propose",
+    {
+      description: TOOL_DESCRIPTIONS.memory_propose,
+      inputSchema: z.object(memoryProposeArgs),
+    },
+    withSync((args) => toMcp(proposeMemoriesOp(args))),
+  );
+
+  server.registerTool(
+    "memory_promote",
+    {
+      description: TOOL_DESCRIPTIONS.memory_promote,
+      inputSchema: z.object(memoryPromoteArgs),
+    },
+    withSync((args) => toMcp(promoteMemoryOp(args))),
+  );
+
+  server.registerTool(
+    "memory_resolve",
+    {
+      description: TOOL_DESCRIPTIONS.memory_resolve,
+      inputSchema: z.object(memoryResolveArgs),
+    },
+    withSync((args) => toMcp(resolveMemoryOp(args))),
+  );
+
+  server.registerTool(
+    "memory_pr_status",
+    {
+      description: TOOL_DESCRIPTIONS.memory_pr_status,
+      inputSchema: z.object(memoryPrStatusArgs),
+      annotations: { readOnlyHint: true },
+    },
+    withSync((args) => toMcp(prStatusOp(args))),
   );
 
   const transport = new StdioServerTransport();

package/src/paths.ts

@@ -1,6 +1,7 @@
 import path from "node:path";
 import fs from "node:fs";
 import os from "node:os";
+import { execFileSync } from "node:child_process";
 
 function dataRoot(): string {
   if (process.env.MY_O_MEMORY_HOME) return path.resolve(process.env.MY_O_MEMORY_HOME);
@@ -43,3 +44,34 @@ export function memoriesDirPath(scopeKey: string): string {
   const { memories } = paths();
   return path.join(memories, scopeKey);
 }
+
+/** Project root: git top-level, falling back to cwd (2B: in-repo memory dir anchor). */
+export function projectRoot(cwd: string = process.cwd()): string {
+  try {
+    const top = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (top) return top;
+  } catch {
+    /* not a git repo — use cwd */
+  }
+  return path.resolve(cwd);
+}
+
+/**
+ * In-repo memory directory for a project scope (2B/D23): `<root>/<memoryDir>/`,
+ * default `<root>/.ai/open-memex/`. Created on demand. `memoryDir` must be a
+ * relative path without `..` segments (validated by `config set`).
+ */
+export function inRepoMemoriesDir(root: string, memoryDir: string): string {
+  const dir = path.join(root, memoryDir);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** Same as `inRepoMemoriesDir` but never creates the directory. */
+export function inRepoMemoriesDirPath(root: string, memoryDir: string): string {
+  return path.join(root, memoryDir);
+}

package/src/retrieve/inject.ts

@@ -1,4 +1,4 @@
-import { list } from "./search.ts";
+import { list, hitStateLabel } from "./search.ts";
 import type { Scope } from "../scope.ts";
 import { PERSONAL_SCOPE } from "../scope.ts";
 import type { MyOMemoryConfig } from "../config.ts";
@@ -23,7 +23,7 @@ export function buildContextBlock(scope: Scope, cfg: MyOMemoryConfig): string |
 
   if (project.length > 0) {
     lines.push("", `Project knowledge (${scope.projectName}):`);
-    for (const m of project) lines.push(`- [${m.type}] ${oneLine(m.snippet)}`);
+    for (const m of project) lines.push(`- [${m.type}]${hitStateLabel(m)} ${oneLine(m.snippet)}`);
   }
 
   lines.push(