open-memex 0.3.0 → 0.4.0-alpha.10

package/dist/tools/ops.js

@@ -6,14 +6,18 @@
  * They take plain validated args and return a plain { title, output }
  * result; each host adapts that to its own tool-result shape.
  */
+import fs from "node:fs";
 import { z } from "zod";
 import { PERSONAL_SCOPE } from "../scope.js";
-import { search, list } from "../retrieve/search.js";
-import { writeMemoryFile, deleteMemoryFile, readMemoryFile, ulid, msToRfc3339, MEMORY_TYPE_TAXONOMY, } from "../store/markdown.js";
+import { search, list, hitStateLabel } from "../retrieve/search.js";
+import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, MEMORY_TYPE_TAXONOMY, } from "../store/markdown.js";
 import { upsertFromFile, deleteFromIndex } from "../store/sync.js";
 import { findDuplicates, supersede } from "../store/lifecycle.js";
 import { db } from "../store/db.js";
 import { redact } from "../redact.js";
+import { getSyncStatus, formatSyncStatus, submitMemories } from "../submit.js";
+import { getPrStatus, formatPrStatus, applyPrStatus } from "../github.js";
+import { proposeMemories, promoteMemory, listConflicts, resolveConflict, formatReviewHistory, } from "../review.js";
 /** LLM-facing tool descriptions, shared by the opencode plugin and the MCP server. */
 export const TOOL_DESCRIPTIONS = {
     memory_add: "Save a fact, preference, decision, or note to persistent local memory. Call this PROACTIVELY whenever the user shares something worth remembering across sessions — project conventions, tool choices, personal preferences, decisions made, error fixes and their causes. Do not wait to be asked. Keep each memory to one self-contained statement. Default scope is the current project; use the personal scope for facts about the user that apply across all projects.",
@@ -21,6 +25,12 @@ export const TOOL_DESCRIPTIONS = {
     memory_list: "List memories in a scope, newest first. Useful for browsing what is remembered, or verifying that a save landed.",
     memory_supersede: "Replace an existing memory with a newer version. The old memory is kept as history (status: superseded) and retrieval returns the new one. Use when a saved fact becomes outdated and should be replaced rather than duplicated.",
     memory_forget: "Delete a memory by id. Use when the user asks to forget something.",
+    memory_status: "Show the project memory sync pipeline: drafts waiting in the outbox (appdata), memories in the repo awaiting review or published, and any repo files not yet committed. Call this at session start and at task checkpoints, then ask the user which drafts to sync. The user may also trigger this flow by saying 'sync memory' (or '同步记忆').",
+    memory_submit: "Move outbox drafts into the repo memory dir for review: copies the drafts in as proposed (or keeps a local approval), commits locally on the current branch, and moves the outbox originals out. Never creates a branch on its own — pass branch= only with the user's explicit approval for the full chain. Prints the push and PR commands — those need the user's explicit approval and are never run automatically.",
+    memory_propose: "Copy personal memories into the project outbox as review drafts. The personal originals stay put.",
+    memory_promote: "Advance a project memory one step up the review ladder (proposed → approved → published), or reject it with a note. Rejected memories are never deleted — they can be revised and resubmitted.",
+    memory_resolve: "List git-conflicted memory files, or attempt a field-level 3-way merge of one. Semantic conflicts are reported, never auto-resolved.",
+    memory_pr_status: "Read the current branch's GitHub PR and map its review state onto each in-repo memory: merged PR → published, PR approval → approved (approved_by = reviewer), changes-requested → suggestion only. Report by default; apply=true performs the mapped transitions locally (no push).",
 };
 /** Shared zod input shapes (raw shape, not z.object — hosts wrap as needed). */
 export const scopeArg = z
@@ -32,9 +42,13 @@ export const memoryAddArgs = {
     type: z
         .enum(MEMORY_TYPE_TAXONOMY)
         .optional()
-        .describe("Category of memory. Default: note."),
+        .describe("Category of memory. Default: fact."),
     scope: scopeArg,
     tags: z.array(z.string()).optional().describe("Optional tags for filtering."),
+    source: z
+        .string()
+        .optional()
+        .describe("Where this memory came from. Default: tool. Pass 'inference' for agent-proposed captures at checkpoints (V2-DESIGN §3.5)."),
 };
 export const memorySearchArgs = {
     query: z
@@ -65,6 +79,44 @@ export const memorySupersedeArgs = {
 export const memoryForgetArgs = {
     id: z.string().min(1),
 };
+export const memoryStatusArgs = {};
+export const memorySubmitArgs = {
+    ids: z.array(z.string().min(1)).min(1).describe("Outbox draft ids to submit."),
+    branch: z
+        .string()
+        .optional()
+        .describe("Create this branch and submit onto it. If omitted, submit stays on the current branch — branches are never auto-created. Only pass this when the user explicitly approved the full chain (branch + push + PR)."),
+    base: z
+        .string()
+        .optional()
+        .describe("PR base branch override. Default: the branch the submit ran on."),
+};
+export const memoryProposeArgs = {
+    ids: z.array(z.string().min(1)).min(1).describe("Personal memory ids to copy into the project outbox."),
+    localApprove: z
+        .boolean()
+        .optional()
+        .describe("Single-developer shortcut: mark the copies approved immediately."),
+};
+export const memoryPromoteArgs = {
+    id: z.string().min(1).describe("Project memory id."),
+    reject: z.boolean().optional().describe("Reject instead of advancing."),
+    resubmit: z.boolean().optional().describe("Move rejected back to proposed for another round."),
+    note: z.string().optional().describe("Review note recorded on reject."),
+    by: z.string().optional().describe("Reviewer name override."),
+};
+export const memoryResolveArgs = {
+    target: z
+        .string()
+        .optional()
+        .describe("Memory id or file path to resolve. Omit to list conflicts."),
+};
+export const memoryPrStatusArgs = {
+    apply: z
+        .boolean()
+        .optional()
+        .describe("Perform the mapped review transitions locally (no push). Default: report only."),
+};
 function resolveScope(getScope, kind) {
     return kind === "personal" || kind === "user" ? PERSONAL_SCOPE : getScope();
 }
@@ -87,6 +139,12 @@ function buildFrontmatter(s, body) {
         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: [],
     };
 }
 export async function addMemory(getScope, cfg, args) {
@@ -107,7 +165,7 @@ export async function addMemory(getScope, cfg, args) {
     const fm = buildFrontmatter(s, {
         type: args.type ?? "fact",
         tags: args.tags ?? [],
-        source: "tool",
+        source: args.source ?? "tool",
     });
     const { filePath } = writeMemoryFile(fm, redacted);
     const mf = readMemoryFile(filePath);
@@ -137,7 +195,7 @@ export async function searchMemories(getScope, args) {
             output: `No memories matched "${args.query}".`,
         };
     }
-    const lines = hits.map((h) => `- [${h.scope_key === PERSONAL_SCOPE.key ? "personal" : "project"}/${h.type}] id=${h.id}\n  ${h.snippet.replace(/\s+/g, " ").trim()}`);
+    const lines = hits.map((h) => `- [${h.scope_key === PERSONAL_SCOPE.key ? "personal" : "project"}/${h.type}]${hitStateLabel(h)} id=${h.id}\n  ${h.snippet.replace(/\s+/g, " ").trim()}`);
     return { title: `memory: ${hits.length} result(s)`, output: lines.join("\n") };
 }
 export async function listMemories(getScope, args) {
@@ -146,7 +204,7 @@ export async function listMemories(getScope, args) {
     if (hits.length === 0) {
         return { title: "memory: empty", output: `No memories in scope ${s.key}.` };
     }
-    const lines = hits.map((h) => `- [${h.type}] id=${h.id} — ${h.snippet.replace(/\s+/g, " ").trim()}`);
+    const lines = hits.map((h) => `- [${h.type}]${hitStateLabel(h)} id=${h.id} — ${h.snippet.replace(/\s+/g, " ").trim()}`);
     return { title: `memory: ${hits.length} in ${s.key}`, output: lines.join("\n") };
 }
 export async function supersedeMemory(cfg, args) {
@@ -175,12 +233,117 @@ export async function supersedeMemory(cfg, args) {
 }
 export async function forgetMemory(args) {
     const row = db()
-        .prepare(`SELECT scope_key FROM memories WHERE id = ?`)
+        .prepare(`SELECT file_path FROM memories WHERE id = ?`)
         .get(args.id);
     if (!row) {
         return { title: "memory: not found", output: `No memory with id ${args.id}.` };
     }
-    deleteMemoryFile(row.scope_key, args.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(args.id);
     return { title: "memory: forgotten", output: `Deleted ${args.id}.` };
 }
+// ---------------------------------------------------------------------------
+// 2B/D26: review workflow ops (also exposed over MCP so agents can drive the
+// sync loop: status → ask user → submit → push/PR on approval).
+// ---------------------------------------------------------------------------
+export async function statusMemories() {
+    const st = getSyncStatus();
+    const n = st.outbox.length +
+        st.inRepo.filter((e) => e.reviewState === "proposed" || e.reviewState === "approved").length;
+    return {
+        title: `memory: sync status (${n} pending)`,
+        output: formatSyncStatus(st),
+    };
+}
+export async function submitMemoriesOp(args) {
+    const r = submitMemories(args.ids, { branch: args.branch, base: args.base });
+    const lines = [];
+    for (const s of r.submitted)
+        lines.push(`submitted ${s.id} [${s.reviewState}]`);
+    for (const id of r.skippedIdentical)
+        lines.push(`already on branch: ${id} (outbox copy removed)`);
+    lines.push(r.committed ? `committed on ${r.branch} (you are still on this branch).` : `nothing new to commit on ${r.branch}.`);
+    lines.push(`Next — ask the user: "want me to create a branch + push + open the PR, or will you handle it yourself?"`);
+    lines.push(`Never create branches, push, or open PRs without their explicit approval. If they handle it themselves, hand them these:`);
+    lines.push(`  ${r.pushCommand}`);
+    for (const l of r.prCommand.split("\n"))
+        lines.push(`  ${l}`);
+    return { title: `memory: submitted ${r.submitted.length}`, output: lines.join("\n") };
+}
+export async function proposeMemoriesOp(args) {
+    const batch = proposeMemories(args.ids, { localApprove: args.localApprove });
+    const lines = batch.map(({ sourceId, result: r }) => `proposed ${sourceId} → ${r.id} [${r.reviewState}] (outbox draft)`);
+    lines.push(`Next: open-memex sync-status, then submit the new ids to move them into a branch.`);
+    return { title: `memory: proposed ${batch.length}`, output: lines.join("\n") };
+}
+export async function promoteMemoryOp(args) {
+    const r = promoteMemory(args.id, {
+        reject: args.reject,
+        resubmit: args.resubmit,
+        note: args.note,
+        by: args.by,
+    });
+    const lines = [`promote ${r.id}: ${r.from} → ${r.to}`];
+    if (r.to === "rejected") {
+        lines.push(`not deleted — the file stays on the branch. Accept (close the PR), revise + resubmit, or keep as a [rejected] record.`);
+    }
+    if (r.history.length > 0) {
+        lines.push(`history (${r.history.length}):`);
+        lines.push(...formatReviewHistory(r.history));
+    }
+    return { title: `memory: ${r.id} → ${r.to}`, output: lines.join("\n") };
+}
+export async function resolveMemoryOp(args) {
+    if (!args.target) {
+        const conflicts = listConflicts();
+        if (conflicts.length === 0) {
+            return { title: "memory: no conflicts", output: "(no conflicted memory files)" };
+        }
+        return {
+            title: `memory: ${conflicts.length} conflicted`,
+            output: conflicts.map((c) => `conflicted: ${c.id}  ${c.filePath}`).join("\n"),
+        };
+    }
+    const outcome = resolveConflict(args.target);
+    if (!outcome.ok) {
+        const lines = [
+            `cannot auto-resolve ${outcome.filePath} — semantic conflicts need a human:`,
+            ...outcome.conflicts.flatMap((c) => [
+                `  ${c.field}:`,
+                `    base:   ${c.base}`,
+                `    ours:   ${c.ours}`,
+                `    theirs: ${c.theirs}`,
+            ]),
+            `Edit the file manually, then \`git add\` it. Nothing was written.`,
+        ];
+        return { title: "memory: resolve blocked", output: lines.join("\n") };
+    }
+    const lines = [`resolved ${outcome.filePath}`];
+    if (outcome.autoMerged.length > 0)
+        lines.push(`  auto-merged: ${outcome.autoMerged.join(", ")}`);
+    return { title: "memory: resolved", output: lines.join("\n") };
+}
+export async function prStatusOp(args) {
+    const st = getPrStatus();
+    const lines = [formatPrStatus(st)];
+    if (args.apply) {
+        const applied = applyPrStatus(st);
+        if (applied.length === 0) {
+            lines.push(`nothing to apply.`);
+        }
+        else {
+            for (const a of applied) {
+                lines.push(`applied ${a.memoryId.slice(0, 8)}: ${a.from} → ${a.to} (by ${a.by})`);
+            }
+        }
+    }
+    return { title: "memory: pr-status", output: lines.join("\n") };
+}

package/docs/CURATOR.md

@@ -0,0 +1,59 @@
+# Curator Convention
+
+The **curator** is the human who tends a project's shared memory. It is a
+documented convention, not a permission system — anyone on the team can act
+as curator; the tool records *who* did *what* (the audit trail), it doesn't
+decide who is *allowed* to.
+
+## What the curator does
+
+1. **Triage proposals.** `open-memex propose` puts memories up for review.
+   The curator reads them, then `open-memex promote <id>` to approve or
+   `open-memex promote <id> --reject` to send back, with `--note` saying why.
+2. **Resolve conflicts.** `open-memex resolve` lists file-level and semantic
+   conflicts. The curator merges or picks a winner — Core never silently
+   resolves a semantic conflict; both sides stay `active` until a human
+   decides.
+3. **Keep the garden.** Deprecate what's stale (`open-memex status <id>
+   deprecated`), supersede what's been replaced, forget what's noise.
+   Shared memory rots without pruning.
+4. **Watch the pipeline.** `open-memex sync-status` shows the outbox, review
+   states, and uncommitted files; `open-memex pr-status --apply` maps the
+   GitHub PR state back onto `review_state`.
+
+## Admission bar
+
+Approve a memory when it is:
+
+- **True** — you believe it, or it cites something verifiable.
+- **Durable** — it will still matter in a month. Chat logs are not memories.
+- **Scoped right** — project knowledge in project scope; personal stuff stays
+  personal (personal memories are never the curator's business).
+- **Well-typed** — `type` says what it IS (`decision`, `gotcha`, `lesson`…),
+  `tags` say what it's ABOUT.
+
+Send back (don't silently fix) when it's vague, duplicated, or belongs in
+`docs/` as formal documentation instead — memory is the fast-changing long
+tail, `docs/` is the slow-changing core.
+
+## What the curator does NOT do
+
+- **Never rewrite someone else's memory in place.** Propose a superseding
+  memory instead — the chain (`supersedes` / `superseded_by`) is the audit
+  trail.
+- **Never approve their own proposals silently in team mode.** That's what
+  `--local-approve` is for — solo projects only.
+- **Never pull rank with the tool.** If the team disagrees with a call, the
+  disagreement itself is worth a memory.
+
+## Cadence
+
+There is no required cadence. A workable default: triage proposals at the
+end of each work chunk (the same checkpoint where §3.5 distillation runs),
+and do a pruning pass when `sync-status` starts feeling noisy.
+
+## Solo mode
+
+No team, no curator needed. `open-memex propose --local-approve` records
+`approved_by: self` and skips the PR. You are the curator, the proposer,
+and the gardener — the same hygiene rules apply, just faster.

package/docs/USER-GUIDE.md

@@ -0,0 +1,197 @@
+# OpenMemex User Guide
+
+> This document describes open-memex's **mental model**: where your memories live,
+> how they flow, and who can see them. The in-repo directory (§2, §6 write path)
+> and the propose → promote → resolve workflow (§5) are implemented on the
+> `V2-dev-p2b` branch; features marked **2B** are still to be built;
+> everything else is 0.3.0 behavior.
+
+## In one sentence
+
+open-memex is a local-first memory layer: **Markdown is the source of truth;
+SQLite is just a rebuildable index.** Lose the index and you rebuild it.
+Lose the Markdown and it's really gone.
+
+## 1. Two scopes: personal vs project
+
+Every memory belongs to a scope, which decides **how far it may travel**:
+
+| | personal | project |
+|---|---|---|
+| Holds | Facts about you: preferences, habits, cross-project info | Facts about the project: stack, conventions, decisions, gotchas |
+| Lives | Only on your machine (see §2) | Local + eligible for team sharing (see §2, §6) |
+| Rule | **Never leaves this machine** | Can be promoted to team knowledge |
+
+Keywords route automatically (D18): "remember… / I think… / I like…" (I) → personal;
+"we decided… / we think… / remember for us…" (we) → project.
+
+## 2. Two homes: appdata vs the repo directory
+
+| | appdata (the desk) | repo `.ai/open-memex/` (the shelf) |
+|---|---|---|
+| Location | Windows `%APPDATA%/open-memex`, Linux `~/.local/share/open-memex` | Project root, default `.ai/open-memex/` (D23, configurable via `memoryDir`) |
+| Holds | `memories/personal/` personal memories; project-scope **draft outbox**; `index.db` local index | Submitted project memories (`proposed` and up) |
+| In git? | No | Yes — git is its courier |
+| The index? | `index.db` is rebuildable, **never committed** | No index stored; rebuilt from Markdown on demand |
+
+The private notebook (personal) never goes on the shelf. That's an iron rule, not a setting.
+
+Project memories start life as **drafts in the appdata outbox** — git-invisible,
+branch-independent. Only drafts you explicitly name move to the shelf, via
+`open-memex submit` (§5). One stage, one home: after a successful submit the
+outbox original is gone; before it, the repo knows nothing.
+
+## 3. First-turn injection: how the 8 and 5 are chosen
+
+Before the agent's first turn, open-memex injects an `[OPEN-MEMEX]` context block so it
+doesn't need a search call just to get oriented. Defaults: **8 project + 5 personal**
+memories (`maxProjectMemories` / `maxProfileItems`, tunable).
+
+Selection has exactly one criterion: **most recently updated first**
+(`ORDER BY updated_at DESC`), minus retracted/archived items, with superseded
+versions resolved away. Not "the N most important" — "the N most recently touched".
+What you just updated is most likely relevant to what you're doing now.
+
+Token budget: each item is squeezed to one line (≤240 chars, ~60 tokens), so 8 items
+cost ≈ 500 tokens worst case. Beyond that, diminishing returns — the long tail is what
+`memory_search` is for; stuffing everything into the first turn buries the signal.
+
+Raise it: `open-memex config set maxProjectMemories 12`
+
+## 4. Later turns: when memory gets searched again
+
+First-turn injection happens once. After that there is **no automatic re-search** —
+MCP is request/response; the server cannot push. Whether `memory_search` gets called
+is entirely the model's judgment, guided by two things:
+
+- The injected block's footer: "Use the `memory_search` tool to look up more."
+- The Copilot instructions written by `init`: "before asking the user about something
+  they may have told you before, call `memory_search` first — try a few keyword
+  variants before giving up."
+
+So: when the conversation touches past decisions, preferences, or conventions, the
+model *should* search first — but nothing enforces it. This is a known gap in the
+current version; Phase 2C's native plugin hooks (e.g. Claude Code's
+`UserPromptSubmit`) are meant to close it.
+
+## 5. Promotion workflow: how a memory becomes team knowledge
+
+A personal observation becomes team knowledge by exactly one road —
+**explicit promotion, never automatic sync**:
+
+```
+personal idea ──propose──▶ outbox draft ──submit──▶ proposed ──┬──promote──▶ approved ──promote──▶ published/shared
+                                                              │                        │
+                                                           --reject                 --reject
+                                                              │                        │  (approval withdrawn
+                                                              ▼                        │   before merge)
+                                                           rejected ──resubmit──▶ proposed
+```
+
+- `open-memex propose <id...> --to project`: **copies** one or more personal
+  memories into the **appdata outbox** as review candidates (`review_state:
+  draft`, each with its own new id, `derived_from` pointing back at the
+  personal original). **Copy, not move — the personal original stays.**
+  All-or-nothing: a bad id aborts the whole batch. Nothing touches the repo
+  yet — the outbox is git-invisible and branch-independent.
+  Solo devs can use `--local-approve` to self-approve.
+- `open-memex sync-status`: shows **when the index was last synced** (and
+  what triggered it — session start, a request, a CLI run, a submit), the
+  outbox (pending sync), the repo review states
+  (`draft / proposed / approved / published / rejected`), and any uncommitted
+  repo memory files. Your agent calls this at session start, at meaningful
+  checkpoints, after you commit, and after memory actions — then asks which
+  drafts (if any) you want synced. You can also just say "sync memory".
+- `open-memex submit <id...>`: moves **your named drafts** into
+  `<repo>/.ai/open-memex/` as `proposed`. It copies the files, flips
+  `review_state`, and makes a **local** git commit **on your current branch** —
+  it never creates a branch on its own (branch creation is your call, or your
+  agent's with your explicit approval via `--branch <name>`).
+  All-or-nothing, idempotent, crash-safe. It prints the `git push` +
+  `gh pr create` commands; if your agent already has your Yes for this sync,
+  it carries through push and PR itself. The PR base defaults to the current
+  branch; `--base` redirects to `main` or your integration branch.
+  Same id with different content on the branch **aborts** — a human decides,
+  never auto-overwrite.
+  - Keep the four jobs straight: **propose crosses the boundary**
+    (personal → project outbox, the only step that copies across);
+    **submit moves drafts into the repo** (outbox → `.ai/open-memex/`,
+    `draft → proposed`); **promote only flips the status label** on a file
+    already in `.ai/open-memex/` (`proposed → approved → published`) — it
+    never moves files between directories; **git does the transport**
+    (push, PR, merge).
+- A standalone memory PR contains **only memory files, no code**, reviewed and
+  audited separately from code PRs. Reviewers check "is this true? is it safe
+  to share? any secrets?" — things a code PR's CI never checks. You create the
+  branch yourself when you want one (or your agent does, with your approval).
+- "Request changes" needs no command: while the PR is open, the author edits
+  the same file (directly, or by asking their agent in chat), commits, and
+  pushes. The state stays `proposed`; the PR is the review mechanism.
+- `open-memex promote <id>`: advances the memory one step up the ladder
+  (`proposed → approved → published`). `--reject --note "..."` rejects with a
+  reason (also allowed from `approved`, before merge — withdrawing approval).
+  Every transition is appended to the memory's `review_history` — who moved it,
+  when, from what to what, and why — so the review trail survives long after
+  the PR is closed.
+  After the PR merges, run `promote <id>` once more to mark it `published`
+  — or let `pr-status --apply` do it for you (below).
+  (Lifting project memories to org level is Phase 4.)
+- **A rejection never deletes anything.** The file stays on your branch; what
+  happens next is the human's call:
+  1. **Accept**: close the PR and delete the branch — the file goes with it
+     (the local index cleans itself up on the next sync);
+  2. **Revise and resubmit**: edit the file, run
+     `open-memex promote <id> --resubmit`, commit, push — review continues on
+     the same PR;
+  3. **Keep as a record**: leave it; it stays visible with a `[rejected]` tag
+     and your note, so the team can see what was considered and why not.
+- `open-memex pr-status [--apply]`: reads the current branch's GitHub PR
+  and maps its state onto each in-repo memory's review state — merged PR →
+  `published`, PR approval → `approved` (`approved_by` = the reviewer), review
+  "request changes" → a suggestion for you to act on (never auto-rejects).
+  Each memory keeps its own state: a human `rejected` is never overridden by
+  a PR signal. Report by default; `--apply` performs the mapped transitions
+  locally (no push). This is how a team review on GitHub closes the loop back
+  into the memory index without new review UI.
+- `open-memex resolve [id]`: with no argument, lists conflicted memory files;
+  with an id, attempts a **field-level 3-way merge** of the YAML frontmatter
+  (`tags` union, `updated_at` takes latest, body merged when only one side
+  changed). Semantic conflicts — both sides changed the same field or the
+  body differently — are **reported, never auto-resolved**: the file is left
+  untouched for a human to decide.
+- `list` / `search` show a `[draft]` / `[proposed]` / `[approved]` /
+  `[published]` / `[rejected]` tag next to project memories in review, and
+  retrieval ranks reviewed knowledge (`approved` / `published`) above
+  unreviewed outbox drafts — drafts stay findable but never pose as vetted.
+
+## 6. Sync: git is the courier, not the brain
+
+- **Write**: `memory_add` (project scope) → writes the **appdata outbox** and
+  updates the local index. **Never touches the repo, never auto-commits,
+  never auto-pushes.**
+- **Submit** (explicit, your call): `open-memex submit <id...>` → local branch
+  + local commit into `.ai/open-memex/`; push/PR are printed for you (or done
+  by your agent on your Yes).
+- **Pull** **2B**: `open-memex pull` (always explicit, never automatic) → git fetch +
+  fast-forward → scans `.ai/open-memex/*.md` → merges into the local `index.db` by
+  file mtime. Retrieval always goes through SQLite, never walks git.
+- **personal scope**: never syncs (§1 iron rule).
+- **Projects without git**: keep working; project scope degrades to local-only with
+  a clear notice. Nothing breaks.
+
+## 7. Security baseline
+
+- Memory is **data** by default, never instructions — external content (pulled from
+  sync, promoted by others) passes an admission check before it lands; the
+  prompt-injection screen on shared files is heuristic, the real boundary is the
+  data/instruction separation.
+- Every memory carries provenance: `source` + `confidence` + `via` + author.
+  Shared-scope writes go into an audit log.
+- A pre-commit hook scans shared scopes for secrets and guards against history
+  rewrites.
+- `<private>…</private>` sections are stripped at write time; detected secret
+  patterns are masked in place and the write proceeds.
+
+---
+
+*Companion design record: `docs/V2-DESIGN.md` (decisions D1–D24).*