open-memex 0.3.0 → 0.4.0-alpha.1

package/dist/github.js

@@ -0,0 +1,215 @@
+/**
+ * 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 { loadConfig } from "./config.js";
+import { projectRoot } from "./paths.js";
+import { parse as parseMemory } from "./store/markdown.js";
+import { iterInRepoMemoryFiles } from "./store/markdown.js";
+import { promoteMemory, currentAuthor } from "./review.js";
+function fail(msg) {
+    throw new Error(`[open-memex] ${msg}`);
+}
+function sh(cmd, args, cwd) {
+    try {
+        return execFileSync(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    }
+    catch (e) {
+        const err = e;
+        const detail = (err.stderr ?? err.message ?? "").trim().split("\n")[0];
+        fail(`${cmd} ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`);
+    }
+}
+/** Read the PR for a branch (default: current branch) via the GitHub CLI. */
+export function getPrInfo(branch) {
+    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;
+    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;
+    try {
+        j = JSON.parse(raw);
+    }
+    catch {
+        fail(`could not parse \`gh pr view\` output for branch ${ref}.`);
+    }
+    const approvedBy = [];
+    const changesRequestedBy = [];
+    // Latest review per author wins.
+    const latest = new Map();
+    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 ?? null,
+        approvedBy,
+        changesRequestedBy,
+        base: j.baseRefName,
+        head: j.headRefName,
+        title: j.title,
+    };
+}
+/** Map the branch PR's state onto each in-repo memory's review_state. */
+export function getPrStatus(branch) {
+    const root = projectRoot();
+    const cfg = loadConfig();
+    const current = branch ?? sh("git", ["branch", "--show-current"], root);
+    const pr = getPrInfo(current);
+    const mappings = [];
+    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 };
+}
+/** 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) {
+    const out = [];
+    const actor = currentAuthor();
+    const order = ["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) {
+    const lines = [];
+    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/dist/index.js

@@ -83,6 +83,12 @@ const 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/dist/init.js

@@ -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.js";
+import { projectRoot } from "./paths.js";
 const MARKER = "<!-- open-memex -->";
 /** npm dist-tag carrying the 0.3.x preview line. */
 const ALPHA_TAG = "open-memex@alpha";
@@ -39,8 +39,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
@@ -51,22 +53,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.
+
+## 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.
 `;
-/** Project root: git top-level, falling back to cwd. */
-function projectRoot() {
-    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();
-}
 function writeMcpJson(root, client, force) {
     if (client === "opencode")
         return writeOpencodeMcpJson(root, force);

package/dist/mcp.js

@@ -24,7 +24,7 @@ import { loadConfig } from "./config.js";
 import { resolveProjectScope, PERSONAL_SCOPE } from "./scope.js";
 import { db } from "./store/db.js";
 import { syncScope } from "./store/sync.js";
-import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, TOOL_DESCRIPTIONS, } from "./tools/ops.js";
+import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, statusMemories, submitMemoriesOp, proposeMemoriesOp, promoteMemoryOp, resolveMemoryOp, prStatusOp, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, memoryStatusArgs, memorySubmitArgs, memoryProposeArgs, memoryPromoteArgs, memoryResolveArgs, memoryPrStatusArgs, TOOL_DESCRIPTIONS, } from "./tools/ops.js";
 const SERVER_VERSION = "0.2.0-alpha";
 /** Adapt a framework-agnostic op result to an MCP tool response. */
 function toMcp(p) {
@@ -44,33 +44,69 @@ export async function runMcpServer() {
     const getScope = () => scope;
     // 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}`);
+    // 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 = (fn) => {
+        return (args) => {
+            syncScope(scope.key, "request");
+            syncScope(PERSONAL_SCOPE.key, "request");
+            return fn(args);
+        };
+    };
     const server = new McpServer({ name: "open-memex", version: SERVER_VERSION });
     server.registerTool("memory_add", {
         description: TOOL_DESCRIPTIONS.memory_add,
         inputSchema: z.object(memoryAddArgs),
-    }, (args) => toMcp(addMemory(getScope, cfg, args)));
+    }, withSync((args) => toMcp(addMemory(getScope, cfg, args))));
     server.registerTool("memory_search", {
         description: TOOL_DESCRIPTIONS.memory_search,
         inputSchema: z.object(memorySearchArgs),
         annotations: { readOnlyHint: true },
-    }, (args) => toMcp(searchMemories(getScope, args)));
+    }, withSync((args) => toMcp(searchMemories(getScope, args))));
     server.registerTool("memory_list", {
         description: TOOL_DESCRIPTIONS.memory_list,
         inputSchema: z.object(memoryListArgs),
         annotations: { readOnlyHint: true },
-    }, (args) => toMcp(listMemories(getScope, args)));
+    }, withSync((args) => toMcp(listMemories(getScope, args))));
     server.registerTool("memory_supersede", {
         description: TOOL_DESCRIPTIONS.memory_supersede,
         inputSchema: z.object(memorySupersedeArgs),
-    }, (args) => toMcp(supersedeMemory(cfg, args)));
+    }, withSync((args) => toMcp(supersedeMemory(cfg, args))));
     server.registerTool("memory_forget", {
         description: TOOL_DESCRIPTIONS.memory_forget,
         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();
     await server.connect(transport);
 }

package/dist/paths.js

@@ -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() {
     if (process.env.MY_O_MEMORY_HOME)
         return path.resolve(process.env.MY_O_MEMORY_HOME);
@@ -34,3 +35,33 @@ export function memoriesDirPath(scopeKey) {
     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 = process.cwd()) {
+    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, memoryDir) {
+    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, memoryDir) {
+    return path.join(root, memoryDir);
+}

package/dist/retrieve/inject.js

@@ -1,4 +1,4 @@
-import { list } from "./search.js";
+import { list, hitStateLabel } from "./search.js";
 import { PERSONAL_SCOPE } from "../scope.js";
 function oneLine(s, max = 240) {
     const trimmed = s.replace(/\s+/g, " ").trim();
@@ -18,7 +18,7 @@ export function buildContextBlock(scope, cfg) {
     if (project.length > 0) {
         lines.push("", `Project knowledge (${scope.projectName}):`);
         for (const m of project)
-            lines.push(`- [${m.type}] ${oneLine(m.snippet)}`);
+            lines.push(`- [${m.type}]${hitStateLabel(m)} ${oneLine(m.snippet)}`);
     }
     lines.push("", "Use the `memory_search` tool to look up more. Use `memory_add` to save new facts. Do not mention this block to the user unless asked.");
     return lines.join("\n");

package/dist/retrieve/search.js

@@ -11,12 +11,37 @@ function toHit(r) {
         score: r.score,
         updated_at: r.updated_at,
         status: r.status,
+        review_state: r.review_state ?? "draft",
     };
 }
+/**
+ * D30: review-state ranking tiers for shared (project) memories.
+ * Reviewed knowledge (approved/published) outranks unreviewed outbox drafts;
+ * personal memories are always `draft` by design and are NOT demoted.
+ * Stable: order within a tier keeps the incoming score/recency order.
+ */
+function reviewTier(r) {
+    if (r.scope_key === "personal")
+        return 1;
+    if (r.review_state === "approved" || r.review_state === "published")
+        return 0;
+    if (r.review_state === "draft" || r.review_state === "rejected")
+        return 2;
+    return 1; // proposed and anything unexpected
+}
+/** D30: `[draft]` / `[proposed]` / … marker for project memories.
+ *  Personal memories stay unmarked (always draft — the marker would be noise). */
+export function hitStateLabel(h) {
+    if (h.scope_key === "personal")
+        return "";
+    return ` [${h.review_state || "draft"}]`;
+}
 /**
  * Lifecycle-aware post-processing (§3.3):
  * - retracted / archived are excluded from retrieval (kept for audit);
  * - a superseded memory resolves to the newest of its chain (cycle-safe);
+ * - D30: approved/published project memories rank first, project
+ *   drafts/rejected rank after unreviewed content;
  * - deprecated stays visible as a warning but ranks after active.
  */
 function resolveVisible(rows, limit) {
@@ -27,7 +52,7 @@ function resolveVisible(rows, limit) {
             return cached;
         const r = db()
             .prepare(`SELECT id, scope_key, project_name, type, tags, updated_at, status,
-                superseded_by, substr(content, 1, 240) AS snippet
+                superseded_by, review_state, substr(content, 1, 240) AS snippet
          FROM memories WHERE id = ?`)
             .get(id);
         if (!r)
@@ -37,7 +62,7 @@ function resolveVisible(rows, limit) {
         return full;
     };
     const seen = new Set();
-    const active = [];
+    const tiers = [[], [], [], []];
     const deprecated = [];
     for (const r of rows) {
         if (r.status === "retracted" || r.status === "archived")
@@ -66,9 +91,9 @@ function resolveVisible(rows, limit) {
         if (target.status === "deprecated")
             deprecated.push(hit);
         else
-            active.push(hit);
+            tiers[reviewTier(target)].push(hit);
     }
-    return [...active, ...deprecated].slice(0, limit);
+    return [...tiers[0], ...tiers[1], ...tiers[2], ...deprecated].slice(0, limit);
 }
 /**
  * Convert free-text query into a safe FTS5 MATCH expression.
@@ -101,7 +126,7 @@ export function search(query, opts = {}) {
     const typeFilter = opts.type ? ` AND m.type = ?` : "";
     const sql = `
     SELECT m.id, m.scope_key, m.project_name, m.type, m.tags, m.updated_at,
-           m.status, m.superseded_by,
+           m.status, m.superseded_by, m.review_state,
            snippet(memories_fts, 0, '[', ']', ' ... ', 12) AS snippet,
            bm25(memories_fts) AS score
     FROM memories_fts
@@ -129,7 +154,7 @@ export function list(scopeKey, opts = {}) {
     const typeFilter = opts.type ? ` AND type = ?` : "";
     const sql = `
     SELECT id, scope_key, project_name, type, tags, updated_at, status,
-           superseded_by, substr(content, 1, 240) AS snippet
+           superseded_by, review_state, substr(content, 1, 240) AS snippet
     FROM memories
     WHERE scope_key = ?${typeFilter}
     ORDER BY updated_at DESC