open-memex 0.5.0 → 0.6.0-alpha.4

package/src/mcp.ts

@@ -52,8 +52,10 @@ import {
   memoryResolveArgs,
   memoryPrStatusArgs,
   TOOL_DESCRIPTIONS,
+  withOutboxNote,
   type ToolResult,
 } from "./tools/ops.ts";
+import { outboxDraftCount } from "./submit.ts";
 
 // Server version tracks package.json — never hardcode it here again.
 // package.json sits two levels above this file in both layouts
@@ -75,40 +77,49 @@ const SERVER_VERSION: string = (() => {
  * 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).
+const SERVER_INSTRUCTIONS = `You are connected to an open-memex local memory MCP server.
+Its tools are memory_add, memory_search, memory_list, memory_supersede,
+memory_forget, memory_status, memory_submit, memory_propose, memory_promote,
+memory_resolve, memory_pr_status — always call them by these full names.
 
-- 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,
+- The server tells you when project outbox drafts are waiting for review —
+  in tool results, and in these session-start instructions. When it does,
   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.
+  repo; sync NOTHING the user did not name. If you already asked about these
+  drafts this session, don't ask again. When the server reports none waiting,
+  do nothing.
+- When the user says "sync memory" (or "同步记忆"), call memory_status,
+  summarize the outbox drafts (one line each), and ask which ones to sync.
+  ALWAYS use the memory_status tool for this — never browse the memory data
+  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.
+- BE PROACTIVE about facts the user states directly: when the user shares a
+  decision, preference, project convention, or fix-and-cause worth remembering
+  across sessions, call memory_add without being asked. Keep each memory to one
+  self-contained statement, and add a brief "(noted in memory)" so the user
+  sees it worked.
+- For conclusions YOU infer (the user never stated them): when you finish a
+  task the user would describe in one sentence, consider distilling the
+  session — if there is something worth keeping,
+  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), each with its proposed scope. Save
+  NOTHING the user did not approve; on approval call memory_add with source
+  "inference" at the approved scope. If the knowledge already lives in project
+  docs, save it as type "reference" 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.
+  may have told you before, call memory_search first — try a few keyword
+  variants (including the user's own language) when the first search comes up
+  empty.
 - 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.`;
+  about the user that hold across all projects. When a saved fact becomes
+  outdated, call memory_supersede (find the old memory's id with memory_search
+  first) instead of adding a duplicate.
+`;
 
 /** Adapt a framework-agnostic op result to an MCP tool response. */
 function toMcp(p: Promise<ToolResult>) {
@@ -164,9 +175,17 @@ export async function runMcpServer() {
     };
   };
 
+  // D53: session-start outbox state, pushed. The stdio server starts fresh per
+  // session, so construction-time state ≈ session-start state.
+  const n = outboxDraftCount(scope.key);
+  const instructions =
+    n > 0
+      ? `${SERVER_INSTRUCTIONS}\n\nSession start: the project outbox has ${n} draft${n === 1 ? "" : "s"} waiting for review — call memory_status to see them.`
+      : SERVER_INSTRUCTIONS;
+
   const server = new McpServer(
     { name: "open-memex", version: SERVER_VERSION },
-    { instructions: SERVER_INSTRUCTIONS },
+    { instructions },
   );
 
   server.registerTool(
@@ -175,7 +194,7 @@ export async function runMcpServer() {
       description: TOOL_DESCRIPTIONS.memory_add,
       inputSchema: z.object(memoryAddArgs),
     },
-    withSync((args) => toMcp(addMemory(getScope, cfg, args))),
+    withSync((args) => toMcp(withOutboxNote(getScope().key, addMemory(getScope, cfg, args), "call memory_status to review"))),
   );
 
   server.registerTool(
@@ -204,7 +223,7 @@ export async function runMcpServer() {
       description: TOOL_DESCRIPTIONS.memory_supersede,
       inputSchema: z.object(memorySupersedeArgs),
     },
-    withSync((args) => toMcp(supersedeMemory(cfg, args))),
+    withSync((args) => toMcp(withOutboxNote(getScope().key, supersedeMemory(cfg, args), "call memory_status to review"))),
   );
 
   server.registerTool(
@@ -214,7 +233,7 @@ export async function runMcpServer() {
       inputSchema: z.object(memoryForgetArgs),
       annotations: { destructiveHint: true },
     },
-    withSync((args) => toMcp(forgetMemory(args))),
+    withSync((args) => toMcp(withOutboxNote(getScope().key, forgetMemory(args), "call memory_status to review"))),
   );
 
   server.registerTool(
@@ -233,7 +252,7 @@ export async function runMcpServer() {
       description: TOOL_DESCRIPTIONS.memory_submit,
       inputSchema: z.object(memorySubmitArgs),
     },
-    withSync((args) => toMcp(submitMemoriesOp(args))),
+    withSync((args) => toMcp(withOutboxNote(getScope().key, submitMemoriesOp(args), "call memory_status to review"))),
   );
 
   server.registerTool(
@@ -242,7 +261,7 @@ export async function runMcpServer() {
       description: TOOL_DESCRIPTIONS.memory_propose,
       inputSchema: z.object(memoryProposeArgs),
     },
-    withSync((args) => toMcp(proposeMemoriesOp(args))),
+    withSync((args) => toMcp(withOutboxNote(getScope().key, proposeMemoriesOp(args), "call memory_status to review"))),
   );
 
   server.registerTool(

package/src/paths.ts

@@ -21,6 +21,15 @@ export interface Paths {
 
 let _cached: Paths | null = null;
 
+/**
+ * Read-only data-root path — never creates the directory. For existence
+ * checks (D50 first-run detection) that must not pollute storage; contrast
+ * `paths()`, which mkdirs as a side effect.
+ */
+export function dataRootPath(): string {
+  return dataRoot();
+}
+
 export function paths(): Paths {
   if (_cached) return _cached;
   const root = dataRoot();

package/src/submit.ts

@@ -153,6 +153,22 @@ export function getSyncStatus(): SyncStatus {
   };
 }
 
+/**
+ * D53: cheap outbox draft count — one indexed query, no git I/O — for the
+ * push-not-poll note appended to mutating tool results and to the MCP
+ * session-start instructions. Same outbox definition as getSyncStatus
+ * (file under the scope's outbox dir), without the expensive parts.
+ */
+export function outboxDraftCount(scopeKey: string): number {
+  const outboxDir = memoriesDirPath(scopeKey);
+  const row = db()
+    .prepare(
+      `SELECT COUNT(*) AS n FROM memories WHERE scope_key = ? AND instr(file_path, ?) = 1`,
+    )
+    .get(scopeKey, outboxDir + path.sep) as { n: number } | undefined;
+  return row?.n ?? 0;
+}
+
 export function formatSyncStatus(st: SyncStatus): string {
   const lines: string[] = [];
   lines.push(`project: ${st.projectName} (${st.scopeKey})`);

package/src/tools/memory.ts

@@ -13,6 +13,7 @@ import {
   memorySupersedeArgs,
   memoryForgetArgs,
   TOOL_DESCRIPTIONS,
+  withOutboxNote,
 } from "./ops.ts";
 
 export function makeTools(getScope: () => Scope, cfg: MyOMemoryConfig) {
@@ -20,7 +21,7 @@ export function makeTools(getScope: () => Scope, cfg: MyOMemoryConfig) {
     description: TOOL_DESCRIPTIONS.memory_add,
     args: memoryAddArgs,
     async execute(args) {
-      return addMemory(getScope, cfg, args);
+      return withOutboxNote(getScope().key, addMemory(getScope, cfg, args));
     },
   });
 
@@ -44,7 +45,7 @@ export function makeTools(getScope: () => Scope, cfg: MyOMemoryConfig) {
     description: TOOL_DESCRIPTIONS.memory_supersede,
     args: memorySupersedeArgs,
     async execute(args) {
-      return supersedeMemory(cfg, args);
+      return withOutboxNote(getScope().key, supersedeMemory(cfg, args));
     },
   });
 
@@ -52,7 +53,7 @@ export function makeTools(getScope: () => Scope, cfg: MyOMemoryConfig) {
     description: TOOL_DESCRIPTIONS.memory_forget,
     args: memoryForgetArgs,
     async execute(args) {
-      return forgetMemory(args);
+      return withOutboxNote(getScope().key, forgetMemory(args));
     },
   });
 

package/src/tools/ops.ts

@@ -24,7 +24,7 @@ import { upsertFromFile, deleteFromIndex } from "../store/sync.ts";
 import { findDuplicates, supersede } from "../store/lifecycle.ts";
 import { db } from "../store/db.ts";
 import { redact } from "../redact.ts";
-import { getSyncStatus, formatSyncStatus, submitMemories } from "../submit.ts";
+import { getSyncStatus, formatSyncStatus, submitMemories, outboxDraftCount } from "../submit.ts";
 import { getPrStatus, formatPrStatus, applyPrStatus } from "../github.ts";
 import {
   proposeMemories,
@@ -39,6 +39,26 @@ export interface ToolResult {
   output: string;
 }
 
+/**
+ * D53: push, don't poll. Append the project-outbox pending count to mutating
+ * tool results so agents learn about drafts waiting for review without a
+ * checkpoint poll. Silent when the outbox is empty. `reviewHint` names the
+ * tool to call (MCP); transports without that tool leave it generic.
+ */
+export async function withOutboxNote(
+  scopeKey: string,
+  p: Promise<ToolResult>,
+  reviewHint?: string,
+): Promise<ToolResult> {
+  const r = await p;
+  const n = outboxDraftCount(scopeKey);
+  if (n > 0) {
+    const tail = reviewHint ? ` — ${reviewHint}` : " for review";
+    r.output += `\n[open-memex: ${n} draft${n === 1 ? "" : "s"} waiting in the project outbox${tail}]`;
+  }
+  return r;
+}
+
 /** LLM-facing tool descriptions, shared by the opencode plugin and the MCP server. */
 export const TOOL_DESCRIPTIONS = {
   memory_add: