open-memex 0.4.0-alpha.5 → 0.4.0

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,28 @@
  */
 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, 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";
+// 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
@@ -53,6 +69,15 @@ propose, promote, resolve, 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
   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
@@ -79,6 +104,20 @@ export async function runMcpServer() {
     syncScope(scope.key, "session");
     syncScope(PERSONAL_SCOPE.key, "session");
     console.error(`[open-memex] MCP server up. scope=${scope.key}`);
+    // 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.

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/store/markdown.js

@@ -3,19 +3,21 @@ import path from "node:path";
 import { randomBytes } from "node:crypto";
 import yaml from "js-yaml";
 import { memoriesDirFor, memoriesDirPath, inRepoMemoriesDirPath, } from "../paths.js";
-/** v2 content-kind taxonomy (V2-DESIGN §3.1). `type` = what the memory IS. */
+/** v2 content-kind taxonomy (V2-DESIGN §3.1). `type` = what the memory IS
+ *  (single-valued, drives behavior). D41: 11 types; `warning`→`gotcha`,
+ *  `workflow`→`howto`, `incident`→`lesson`, `architecture`→`knowledge`. */
 export const MEMORY_TYPE_TAXONOMY = [
-    "preference",
     "fact",
+    "preference",
     "decision",
-    "lesson",
-    "warning",
-    "workflow",
-    "architecture",
     "constraint",
     "todo",
     "knowledge",
+    "howto",
+    "gotcha",
+    "lesson",
     "observation",
+    "reference",
 ];
 const TAXONOMY = new Set(MEMORY_TYPE_TAXONOMY);
 /** Defensive parse: malformed entries are dropped, never fatal. */

package/dist/tools/ops.js

@@ -42,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
@@ -161,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);

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/TEST-PLAN.md

@@ -0,0 +1,72 @@
+# OpenMemex 测试计划（v0.4.0-alpha.10）
+
+> 自动化部分：`node --experimental-strip-types scripts/test-full.ts`
+> 62 项全过（26 个 CLI 命令 + 11 个 MCP tool），隔离环境运行，不碰真实数据。
+> 下面是机器/账号相关的部分，需要 Stone 在真机上过一遍。
+
+## A. Windows 真机 + VS Code Copilot
+
+- [ ] `npm i -g open-memex@alpha` 全局安装，`open-memex --version` 显示正确版本
+- [ ] 在一个真实项目目录跑 `open-memex init`（不加 `--yes`，走一遍交互）
+  - 确认 `.vscode/mcp.json` 生成，`~/.copilot/copilot-instructions.md` 合并写入（不覆盖已有内容）
+- [ ] 重启 VS Code，Copilot Chat 里问 "what do you remember about this project?"
+  - 预期：MCP 连接成功，能调用 memory_search
+- [ ] `open-memex add "windows 真机测试" --type fact`，再让 Copilot 搜出来
+- [ ] 中文路径项目、中文记忆内容各试一条（CJK 索引）
+
+## B. 真实 GitHub PR 全流程（review 工作流）
+
+在一个真实 repo 里：
+
+- [ ] `open-memex add "PR流程测试" --scope personal` → `propose --to project` → `sync-status` 看到 outbox draft
+- [ ] `open-memex submit <id>`（留在当前分支，本地 commit）
+- [ ] 手动 `git push` + 开 PR
+- [ ] 在 PR 里点 Approve → 回来跑 `open-memex pr-status`（先看 report），再 `pr-status --apply`
+  - 预期：memory 变成 approved，`approved_by` 是 reviewer
+- [ ] 找一条让 reviewer 点 "Request changes" → `pr-status --apply`
+  - 预期：只给 suggestion，**不**自动 reject（D32）
+- [ ] Merge PR → `pr-status --apply`
+  - 预期：memory 变成 published
+- [ ] `open-memex resolve` 无冲突时输出 "(no conflicted memory files)"
+
+## C. 其他编辑器 MCP 集成
+
+- [ ] Cursor：`open-memex mcp --print-config cursor` → 贴到 Cursor MCP 配置 → 能连上
+- [ ] opencode：`open-memex init --client opencode` → `opencode.jsonc` 生效
+- [ ] Claude Code：`open-memex mcp --print-config claude` 给出的 `claude mcp add` 命令能跑通
+
+## D. 跨机迁移（export/import 真实场景）
+
+- [ ] 本机：`open-memex export --all -o migration.tar.gz`（含 private 的全量）
+- [ ] 本机：`open-memex export -o share.tar.gz`（默认排除 private）→ 解包检查 manifest，确认没有 visibility:private 的条目
+- [ ] 另一台机器：`open-memex import migration.tar.gz --dry-run` 先看预览，再正式 import
+  - 预期：project memory re-key 到新机器的 project scope，进 outbox 当 draft；personal 进 personal
+- [ ] 同一个 bundle 导两次 → 第二次 "skipped N identical"
+
+## E. Agent 会话行为（D42 / §3.5）
+
+- [ ] 新开一个 agent 会话（MCP 已接），看 initialize 返回的 instructions 里有没有 session-start 同步指引
+- [ ] 对 agent 说 "sync memory" / "同步记忆"
+  - 预期：agent 走 memory_status → 摘要 → 问你要同步哪条（而不是直接翻 appdata）
+- [ ] 长对话中 agent 是否在检查点提议蒸馏（§3.5），提议后是否等你批准才保存（D42）
+
+## F. 冲突解决（3-way merge）
+
+- [ ] 两台机器（或两个 clone）同时改同一条 project memory，各自 submit + push，一边 pull 制造 diverged
+  - 预期：`open-memex pull` 明确报错退出，不自动 merge
+- [ ] 手动 merge 后 `open-memex resolve <id>` 看 3-way 展示（base/outbox/repo），手动解决
+
+## G. 同事 pilot（1–2 人，Stone 私下选）
+
+- [ ] 对方 `npx open-memex@alpha init` 走通
+- [ ] 对方能 propose → 你这边能看到 PR → promote 流程走通
+- [ ] 收集反馈：哪里卡、哪里不符合直觉
+
+## H. 已知问题观察
+
+- [ ] better-sqlite3 在 Node 24 退出时偶发 crash（exit 134）：注意是否丢数据（预期：不丢，只影响退出码）
+- [ ] `memory_list` 默认只列 project scope 是否符合预期（Stone 已定保持现状）
+
+---
+
+测试中发现的 bug 直接记到 GitHub issue；改完后更新本文档的复选框。

package/docs/V2-DESIGN.md

@@ -25,6 +25,12 @@ Decisions log; Prior Art; solo-dev adoption path.
 6. **Adapters translate; they never implement memory logic.** All memory logic lives in Core.
 7. **Memory is the entrance of knowledge, not its final form.** Terminal states are docs / ADRs /
    AGENTS.md instructions — memory is how knowledge gets captured and found.
+8. **Distill conversations; do not archive them.** The default unit of memory is the useful
+   conclusion from a conversation, not the full transcript: what was learned, how it was resolved,
+   and where the authoritative source lives.
+9. **Portable second brain, not a walled garden.** Long-form personal notes are valid memories when
+   the user explicitly saves them; Markdown keeps them readable, exportable, and movable to other
+   tools or machines.
 
 ---
 
@@ -40,6 +46,9 @@ Decisions log; Prior Art; solo-dev adoption path.
 - **MCP is an interface, not the identity.** MCP / CLI / REST / SDK are access layers over the protocol,
   so the project is never locked to one transport or one agent tool (opencode, VS Code Copilot, Cursor,
   Claude Code, Windsurf, …).
+- **Second-brain lens:** for individuals, OpenMemex can also be a local Markdown second brain for
+  AI-assisted work — similar in spirit to users asking AI to save notes into Obsidian or Notion, but
+  with agent recall, scopes, review, and redaction built in from the start.
 - **Company lens:** at organizational scale the same pain is tribal knowledge — senior engineers'
   hard-won experience evaporates when they move on, and every incident gets re-debugged by someone
   new. The current phase therefore prioritizes *capture*: valuable knowledge must land in memory
@@ -132,13 +141,37 @@ canonical_ref: docs/adr-003.md       # memory holds a SUMMARY; the doc is canoni
 
 ### 3.1 Type taxonomy (content kind)
 
-`preference` `fact` `decision` `lesson` `warning` `workflow` `architecture` `constraint`
-`todo` `knowledge` `observation`
+`fact` `preference` `decision` `constraint` `todo` `knowledge` `howto` `gotcha`
+`lesson` `observation` `reference`
 
-`type` describes **what the content is**. `role` describes **how it may be used**.
+`type` describes **what the content is** — single-valued, and it drives behavior
+(lifecycle, review, rendering, retrieval). `role` describes **how it may be used**.
 A `decision` with `role: knowledge` is retrievable history. Only `role: instruction` may enter
 instruction context. (Separation adopted from review: mixing usage semantics into `type` was a design smell.)
 
+One-line definitions:
+
+- `fact` — a verifiable atomic statement (timezone, version number, path, account).
+- `preference` — user likes, dislikes, working style.
+- `decision` — a choice made + why; participates in supersede chains.
+- `constraint` — a hard rule that must not be violated (release process, permission boundaries).
+- `todo` — an actionable item with completion state.
+- `knowledge` — declarative knowledge (how a system works, concept explanations).
+- `howto` — steps to accomplish X.
+- `gotcha` — a pitfall: don't do X because Y.
+- `lesson` — a takeaway from experience, including incident postmortems (the incident id goes in `tags`).
+- `observation` — noticed but not yet distilled.
+- `reference` — a pointer to the authoritative doc via `canonical_ref`; the memory holds the summary.
+
+A type earns its place only if the system treats it differently. If two candidates
+share lifecycle, retrieval, and rendering, the loser becomes a tag. (D41 merged
+`warning`→`gotcha`, `workflow`→`howto`, `incident`→`lesson`, `architecture`→`knowledge`.)
+
+`tags` are retrieval hints, not a second type system: `type` says what the memory is, while tags say
+which topics, tools, subsystems, paths, or incidents it relates to. Write paths should preserve
+human-provided tags and may suggest simple normalized tags (for example `vscode`, `mcp`, `windows`,
+`auth`, `onboarding`) to improve search without changing memory semantics.
+
 ### 3.2 Iron rules
 
 - **Iron rule 1 — the instruction gate:** only memories with `role: instruction`
@@ -170,6 +203,34 @@ Content hash + fuzzy match against existing memories. A superseding write does *
 the old memory becomes `status: superseded` with `superseded_by` pointing forward. History preserved;
 queries rank `active` first.
 
+### 3.5 Conversation distillation
+
+OpenMemex does **not** store raw AI chat transcripts by default. A captured memory should usually be
+a short, human-approved artifact distilled from the conversation: the final conclusion, important
+facts, why the answer matters later, and how the issue was resolved. Good distilled memory candidates
+answer some combination of:
+
+- What did we learn or decide?
+- What solved the problem, including key commands, files, links, or steps?
+- What mistake or gotcha should the next developer avoid?
+- Which scope owns it: `personal`, `project`, or future `org`?
+- If the information already exists in project docs, where is the authoritative doc?
+
+If stable knowledge already lives in a project document, prefer a `type: reference` memory with
+`canonical_ref` pointing at that document over duplicating the full content. Memory should help the
+agent find and apply authoritative docs, not become an outdated second copy of them.
+
+Model-suggested captures use `source: inference` and should default to reviewable draft state. The
+agent may propose 1-3 distilled memories at checkpoints or task end, but humans decide whether to
+save them and which scope they belong to. The product goal is remembering the right conclusion at
+the right scope, not remembering everything.
+
+Long-form notes are still valid when the user explicitly asks to save a long note, write-up, meeting
+summary, research log, or troubleshooting record. In that case OpenMemex behaves like a Markdown
+second-brain target: store the note as user-authored content, preserve the body, tag it for retrieval,
+and keep the same scope/privacy rules. The distinction is intent: implicit/model-suggested capture
+distills; explicit "save this note" may preserve long-form text.
+
 ---
 
 ## 4. Scopes, Visibility & Namespaces
@@ -294,11 +355,21 @@ instructions are never candidates.)
 | Implicit (opt-in) | end-of-session "should I remember X?"; implicit captures default to `confidence: low` and appear in a separate list view for batch cleanup (regret window). |
 | Redaction (hard) | `<private>…</private>` stripped; secret patterns are **masked in place** (first 4 chars kept, rest → `x`) and the write proceeds (D14); pre-commit hook scans shared scopes. |
 
+**Scope routing on capture:** when the user says "save", "remember", or "note this" without an
+explicit scope, the agent should infer ownership from content and current context. Project-specific
+knowledge (repo commands, architecture, code paths, product decisions, team conventions) routes to
+`project`; personal preferences, private working notes, cross-project habits, or content unrelated to
+the current repo routes to `personal`. Ambiguous captures should ask one short clarification instead
+of guessing. `org` capture remains future/curated; a single user's chat never writes org memory
+directly.
+
 ---
 
 ## 9. Sync
 
-- **Git is transport; the local SQLite index is the query layer.** Retrieval never walks git.
+- **Git is a transport, not the product boundary; the local SQLite index is the query layer.**
+  Retrieval never walks git. Git/GitHub is the default sharing provider because it gives teams branch,
+  PR, review, and audit semantics they already trust, but Core must remain provider-agnostic.
 - one-memory-one-file ⇒ concurrent edits almost never conflict.
 - **Pull is explicit** (`open-memex pull`), never automatic on session start — no surprise context changes.
   `pull` = `fetch` + fast-forward only; never auto-commit/push (hard rule for enterprise environments).
@@ -314,6 +385,13 @@ instructions are never candidates.)
 - **Git unavailable:** projects without git (or with unreachable remotes) remain fully usable.
   `personal` scope works everywhere; `project` scope degrades to local-only and `open-memex status`
   annotates it as such. Sync commands fail with a clear message, never with a broken state.
+- **Portability:** because Markdown is the source of truth, memories should be exportable without
+  depending on git. A future `open-memex export` command can archive selected scopes/types/tags into a
+  portable zip/tar bundle (markdown + manifest) for moving to another computer or importing into
+  another application. Export excludes `visibility: private` memories by default; `--all` / `-a`
+  includes everything, for a full personal migration to a new machine. API-backed exporters/providers (Notion, Obsidian-compatible vaults, internal
+  knowledge systems, enterprise stores) are extension paths over the same memory files and admission
+  rules, not separate products.
 
 ---
 
@@ -456,10 +534,13 @@ requirement: personal data never touches third-party services). Benchmarks to tr
 | atlaso-labs/codex | Codex marketplace | long-term memory plugin for Codex (hooks + MCP + cloud-sync upsell) | **direct comparable** for a future Codex plugin; their cloud upsell vs our local-first |
 
 (Star counts / funding as of Sep 2026 — re-verify before quoting publicly.)
-- **Phase 3 — Org layer.** Org memory repo · curator convention · `examples/remote-server/` ·
-  distill-to-AGENTS.md assist.
+- **Phase 3 — Org layer.** Org memory repo · `examples/remote-server/` ·
+  curator convention ✅ `docs/CURATOR.md` (2026-09-29, pulled forward) ·
+  distill-to-AGENTS.md assist ✅ `open-memex distill-agents` (2026-09-29, pulled forward) ·
+  export/import archive command ✅ `open-memex export` / `import` (2026-09-29, pulled forward, D40).
 - **Phase 4 — Future, signal-gated.** Cloud `RemoteProvider` customization only on: multi-private-repo
-  sharing needs, fine-grained ACL, audit/compliance mandates.
+  sharing needs, fine-grained ACL, audit/compliance mandates · optional API-backed exporters/providers
+  for enterprise knowledge systems.
 
 ## 19. Migration v1 → v2
 
@@ -732,6 +813,71 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   fall back to the global usage. *Rationale: AI assistants discover the CLI
   through --help first — a command that silently swallows --help as a flag
   teaches the agent nothing. Approved 2026-09-28.*
+- **D37** — Conversation distillation is the memory unit; transcript storage is
+  not the default. Capture should preserve the useful conclusion from a human/AI
+  session — what was learned, what resolved the issue, what should be avoided,
+  and where the authoritative doc lives — as a short reviewable memory. If the
+  knowledge already exists in docs, store a `reference` memory with
+  `canonical_ref` instead of duplicating the doc. Tags are retrieval hints, not
+  content kinds: `type` classifies the memory, tags describe topics/tools/paths.
+  *Rationale: full chat logs are noisy, harder to review, and riskier for
+  privacy; the value is remembering the right conclusion at the right scope,
+  with enough context for the next human or AI session. Approved 2026-09-28.*
+- **D38** — OpenMemex supports a Markdown second-brain use case while keeping
+  distillation as the default for implicit/model-suggested capture. If the user
+  explicitly asks to save a long note, meeting summary, troubleshooting record,
+  or write-up, preserve it as user-authored Markdown with tags and normal
+  scope/privacy rules. Git/GitHub sync is the default team-sharing provider, not
+  the product boundary: future export/import archives and API-backed providers
+  may move the same markdown memories to other computers, applications, or
+  enterprise systems. For generic "save/remember/note this" requests, the agent
+  routes project-specific knowledge to `project`, personal or repo-unrelated
+  knowledge to `personal`, and asks one clarification if ambiguous; `org` remains
+  curated/future, never a direct single-user chat write. *Rationale: users also
+  want a local AI-assisted second brain, but portability and ownership must stay
+  explicit; sharing mechanisms should be provider choices over the same memory
+  model, not the identity of the product. Approved 2026-09-28.*
+- **D39** — `type` and `tags` are complementary axes, not alternatives. `type` is
+  single-valued: what the memory IS — it drives behavior (lifecycle, review,
+  rendering, retrieval: a `todo` can be completed, a `reference` resolves
+  `canonical_ref`, a `decision` participates in supersede chains). `tags` are
+  multi-valued: what the memory is ABOUT — pure retrieval hints
+  (topics, tools, subsystems, paths, incidents). *Rationale: without type the
+  system cannot tell "a todo I must do" from "a fact I must know" even when both
+  are tagged `auth`; without tags, cross-cutting retrieval ("everything about
+  onboarding") would need a combinatorial type explosion. Type answers "how do I
+  handle this?", tags answer "how do I find this?". Approved 2026-09-28.*
+- **D40** — `open-memex export` excludes `visibility: private` memories by
+  default; `--all` / `-a` includes everything, for a full personal migration to
+  a new machine. *Rationale: the safe default protects privacy; the escape hatch
+  keeps the "no walled garden" promise — the user can always take everything
+  with them. Approved 2026-09-28.*
+- **D42** — §3.5 checkpoint distillation is taught in the MCP handshake
+  instructions (`src/mcp.ts` `SERVER_INSTRUCTIONS`) and the `init`-written
+  instruction files (`src/init.ts` `INSTRUCTIONS`): at checkpoints the agent
+  DISTILLs the session and proposes 1–3 short memories (conclusion, not
+  transcript); nothing is saved without user approval. Approved captures are
+  saved via `memory_add` with the new optional `source` param set to
+  `"inference"` (default `"tool"`). *Rationale: closes the 0.4.0 TODO from D41 —
+  the design's capture loop now reaches the agent. Implemented 2026-09-29.*
+- **D43** — `distill-agents` output gains a "Memory hygiene (open-memex)"
+  footer carrying the §3.5 checkpoint guidance (propose 1–3 distilled captures
+  at checkpoints; save nothing without approval; prefer `reference` over
+  copying). *Rationale: double insurance for opencode users, who never see the
+  MCP handshake instructions or the `init`-written instruction files — but
+  opencode reads AGENTS.md natively, so the distilled snippet teaches the
+  checkpoint habit wherever it lands. Approved 2026-09-29.*
+- **D41** — The type taxonomy is reconciled to 11 types with one-line definitions
+  (§3.1): `fact` `preference` `decision` `constraint` `todo` `knowledge` `howto`
+  `gotcha` `lesson` `observation` `reference`. Merged away: `warning`→`gotcha`,
+  `workflow`→`howto`, `incident`→`lesson` (incident id goes in `tags`),
+  `architecture`→`knowledge` (tag `architecture`). *Rationale: a type earns its
+  place only if the system treats it differently (lifecycle, retrieval,
+  rendering); otherwise it is a tag. Fifteen types blur classification and hurt
+  agent accuracy — eleven keeps each type's behavioral slot distinct. `lesson`
+  is deliberately broader than `incident`: a postmortem's shape (timeline, root
+  cause, actions) is a template concern, not a type. Code
+  `MEMORY_TYPE_TAXONOMY` updated to match. Approved 2026-09-28.*
 
 ## Open Questions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.4.0-alpha.5",
+  "version": "0.4.0",
   "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
   "type": "module",
   "license": "Apache-2.0",