open-memex 0.3.0 → 0.4.0-alpha.10

package/dist/mcp.js

@@ -1,9 +1,10 @@
 /**
  * open-memex generic MCP server (stdio transport).
  *
- * Exposes the same five memory tools as the opencode plugin
+ * Exposes the memory tools as the opencode plugin
  * (memory_add / memory_search / memory_list / memory_supersede /
- * memory_forget) over the Model Context Protocol, so any MCP client —
+ * memory_forget, plus memory_status / memory_submit / memory_propose /
+ * memory_promote / memory_resolve / memory_pr_status) over the Model Context Protocol, so any MCP client —
  * VS Code Copilot Chat, Cursor, Claude Code, etc. — can use open-memex
  * without a host-specific plugin.
  *
@@ -19,13 +20,69 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { z } from "zod";
 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";
-const SERVER_VERSION = "0.2.0-alpha";
+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";
+// Server version tracks package.json — never hardcode it here again.
+// package.json sits two levels above this file in both layouts
+// (src/mcp.ts and dist/mcp.js), same convention as cli.ts --version.
+const SERVER_VERSION = (() => {
+    try {
+        const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+        const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0-unknown";
+    }
+    catch {
+        return "0.0.0-unknown";
+    }
+})();
+/**
+ * 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, when you finish a meaningful chunk of work,
+  after the user commits (git commit), and after any memory_* action completes,
+  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. ALWAYS use the memory_status tool for this — never browse the
+  appdata directory directly.
+- After memory_submit, ask ONE follow-up: "want me to create a branch + push +
+  open the PR, or will you handle it yourself?" NEVER create branches, push, or
+  open PRs without the user's explicit approval. A "yes, you do it" covers the
+  whole chain — do NOT re-ask at each step.
+- 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.
+- At the same checkpoints (session start, end of a work chunk, after the user
+  commits, after any memory_* action), DISTILL the session: propose 1–3 short
+  memories capturing the useful conclusion — what was learned or decided, how an
+  issue was resolved, what to avoid, where the authoritative doc lives — not the
+  raw transcript. Save NOTHING the user did not approve; on approval call
+  memory_add with source "inference" at the confirmed scope. If the knowledge
+  already lives in project docs, save a \`reference\` memory pointing at the doc
+  instead of copying it. Long-form notes are fine ONLY when the user explicitly
+  asks to save one.
+- 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) {
     return p.then((r) => ({ content: [{ type: "text", text: r.output }] }), (e) => ({
@@ -44,33 +101,83 @@ 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}`);
-    const server = new McpServer({ name: "open-memex", version: SERVER_VERSION });
+    // D12: pulls are explicit by default — session start never touches the
+    // network. With sync.autoPull, one best-effort pull; a failure never
+    // blocks the session, it just logs and continues.
+    if (cfg.sync?.autoPull) {
+        try {
+            const { GitProvider } = await import("./providers/git.js");
+            const r = new GitProvider().pull(process.cwd());
+            syncScope(scope.key, "pull");
+            console.error(`[open-memex] auto-pull: ${r.branch} ${r.fastForwarded ? "fast-forwarded" : "already up to date"}`);
+        }
+        catch (e) {
+            console.error(`[open-memex] auto-pull skipped: ${e.message}`);
+        }
+    }
+    // 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 }, { instructions: SERVER_INSTRUCTIONS });
     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/providers/git.js

@@ -0,0 +1,142 @@
+/**
+ * GitProvider — the git transport for repo-synced shared scopes (§9, D12).
+ *
+ * Git is a transport, not the product boundary: this provider moves the
+ * in-repo memory dir (`.ai/open-memex/`) between the local checkout and the
+ * remote. It never touches the appdata outbox, never force-pushes, never
+ * auto-merges a divergence — those are human decisions.
+ *
+ * Hard rules (from §9 / D12 / D36):
+ * - pull is explicit (`open-memex pull`); pull = fetch + fast-forward only.
+ * - push is explicit (`open-memex push`); the tool never pushes on its own.
+ * - a failed pull/push fails with a clear message and leaves no broken state.
+ */
+import { execFileSync } from "node:child_process";
+function fail(msg) {
+    throw new Error(`[open-memex] ${msg}`);
+}
+/** Run git, raising a readable error. `timeoutMs` guards network calls. */
+function git(root, args, timeoutMs = 0) {
+    try {
+        return execFileSync("git", args, {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            ...(timeoutMs > 0 ? { timeout: timeoutMs } : {}),
+        }).trim();
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === "ETIMEDOUT")
+            fail(`git ${args.join(" ")} timed out — remote unreachable?`);
+        const detail = (err.stderr ?? err.message ?? "").trim().split("\n")[0];
+        fail(`git ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`);
+    }
+}
+const FETCH_TIMEOUT_MS = 30_000;
+export class GitProvider {
+    name = "git";
+    capabilities = {
+        read: true,
+        write: true,
+        delete: false,
+        history: true,
+        sync: "bidirectional",
+    };
+    /** Current branch + upstream, or a clear failure when git can't answer. */
+    status(root) {
+        git(root, ["rev-parse", "--git-dir"]);
+        const branch = git(root, ["branch", "--show-current"]) ||
+            git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
+        let upstream = null;
+        try {
+            upstream = git(root, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
+        }
+        catch {
+            upstream = null;
+        }
+        let ahead = 0;
+        let behind = 0;
+        if (upstream) {
+            const counts = git(root, ["rev-list", "--left-right", "--count", `HEAD...${upstream}`]);
+            const [a, b] = counts.split(/\s+/).map((n) => parseInt(n, 10));
+            ahead = Number.isFinite(a) ? a : 0;
+            behind = Number.isFinite(b) ? b : 0;
+        }
+        const remote = upstream ? upstream.split("/")[0] : null;
+        return { branch, upstream, remote, ahead, behind };
+    }
+    /**
+     * Explicit pull: fetch + fast-forward only (§9).
+     * Diverged branches are NOT merged — the user resolves them by hand.
+     */
+    pull(root) {
+        const st = this.status(root);
+        if (!st.upstream || !st.remote) {
+            fail(`branch ${st.branch} has no upstream — set one with ` +
+                `\`git push -u <remote> ${st.branch}\`, then pull again`);
+        }
+        git(root, ["fetch", st.remote], FETCH_TIMEOUT_MS);
+        const before = git(root, ["rev-parse", "HEAD"]);
+        const remoteSha = git(root, ["rev-parse", st.upstream]);
+        if (before === remoteSha) {
+            return {
+                at: new Date().toISOString(),
+                branch: st.branch,
+                remote: st.remote,
+                before,
+                after: before,
+                fastForwarded: false,
+            };
+        }
+        // Fast-forward is possible iff HEAD is an ancestor of the upstream.
+        let ffPossible = false;
+        try {
+            git(root, ["merge-base", "--is-ancestor", "HEAD", st.upstream]);
+            ffPossible = true;
+        }
+        catch {
+            ffPossible = false;
+        }
+        if (!ffPossible) {
+            fail(`branch ${st.branch} has diverged from ${st.upstream} — ` +
+                `open-memex never force-merges; resolve it by hand ` +
+                `(rebase or merge), then pull again`);
+        }
+        git(root, ["merge", "--ff-only", st.upstream]);
+        const after = git(root, ["rev-parse", "HEAD"]);
+        return {
+            at: new Date().toISOString(),
+            branch: st.branch,
+            remote: st.remote,
+            before,
+            after,
+            fastForwarded: true,
+        };
+    }
+    /** Explicit push of the current branch. Never called automatically. */
+    push(root) {
+        const st = this.status(root);
+        if (!st.remote) {
+            // No upstream yet: push explicitly sets it (-u), still user-invoked.
+            const remotes = git(root, ["remote"]);
+            const remote = remotes.split("\n").map((r) => r.trim()).filter(Boolean)[0];
+            if (!remote)
+                fail("no git remote configured — add one before pushing");
+            git(root, ["push", "-u", remote, st.branch], FETCH_TIMEOUT_MS);
+            return {
+                at: new Date().toISOString(),
+                branch: st.branch,
+                remote,
+                head: git(root, ["rev-parse", "HEAD"]),
+            };
+        }
+        git(root, ["push", st.remote, st.branch], FETCH_TIMEOUT_MS);
+        return {
+            at: new Date().toISOString(),
+            branch: st.branch,
+            remote: st.remote,
+            head: git(root, ["rev-parse", "HEAD"]),
+        };
+    }
+}

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