open-memex 0.4.0-alpha.5 → 0.4.0-alpha.7

package/AGENTS.md

@@ -140,3 +140,6 @@ hold `V2` and `V2/…` simultaneously. Full rules: `CONTRIBUTING.md`.
   in-development version. New features on a dev branch bump the minor on the alpha
   line (`0.3.0` → `0.4.0-alpha.1`); fixes bump the patch (`-alpha.1` → `-alpha.2`).
   The bump goes in the same commit as the feature, never as an afterthought.
+  The version number serves the publish: no publish, no mandatory bump. But once a
+  version has been pushed to the remote (shared), later changes must bump — two
+  different code states must never share one version number.

package/README.md

@@ -375,10 +375,13 @@ server with cwd set to your project root (`init` handles this for you).
 **In progress — `0.4.0`:** team sync — shared memory via git: appdata draft
 outbox → `sync-status` → `submit` (local branch+commit, push/PR on your Yes)
 → `promote` / `resolve` review workflow, in-repo `.ai/open-memex/` dir, 1–2
-colleague pilot.
+colleague pilot; capture — §3.5 checkpoint distillation in MCP handshake +
+init instructions (agent proposes 1–3 captures, human decides).
 
 **Coming — `0.3.0` (stable):** org layer — org memory repo, curator convention,
-distill-to-AGENTS.md assist.
+distill-to-AGENTS.md assist, `export`/`import` archive for user portability
+(Markdown + manifest, no walled garden; private excluded by default,
+`-a`/`--all` for full migration).
 
 **Future (signal-gated, no version committed):** native agent plugins (Claude Code /
 Codex hooks as enhancement paths over the same MCP tools); local embeddings as a

package/README.zh-CN.md

@@ -365,10 +365,13 @@ project scope 从进程工作目录解析，所以配置 server 时 cwd 要指
 **进行中 —— `0.4.0`：** 团队同步——用 git 做共享记忆：appdata 草稿箱 →
 `sync-status` → `submit`（本地分支+commit，push/PR 拿你的 Yes 才做）
 → `promote` / `resolve` 评审工作流、仓库内 `.ai/open-memex/` 目录，
-找 1–2 个同事做 pilot。
+找 1–2 个同事做 pilot；捕获——§3.5 检查点蒸馏写进 MCP 握手指令和
+init 指令文件（agent 提议 1–3 条，人来定）。
 
 **Coming —— `0.3.0`（稳定版）：** 组织层——组织记忆仓库、
-curator 约定、distill-to-AGENTS.md 辅助。
+curator 约定、distill-to-AGENTS.md 辅助、`export`/`import` 归档
+（Markdown + manifest，不造围墙花园，用户可带走；
+private 默认不导出，`-a`/`--all` 全量迁移）。
 
 **未来（看信号再定，不承诺版本）：** 原生 agent 插件
 （Claude Code / Codex hooks，作为同一套 MCP tools 的增强路径）；

package/dist/doctor.js

@@ -116,7 +116,7 @@ function mcpCheck() {
                         name,
                         ok: missing.length === 0,
                         detail: missing.length === 0
-                            ? `handshake OK, 5 tools listed (${names.join(", ")})`
+                            ? `handshake OK, ${names.length} tools listed (${names.join(", ")})`
                             : `missing tools: ${missing.join(", ")}`,
                     });
                 }

package/dist/init.js

@@ -47,6 +47,14 @@ You have a local memory MCP server (\`open-memex\`) with eleven tools:
 - 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 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 — try a few keyword variants
   (including the user's own language) when the first search comes up empty.

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

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/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.
 
 ---
 
@@ -457,9 +535,10 @@ requirement: personal data never touches third-party services). Benchmarks to tr
 
 (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.
+  distill-to-AGENTS.md assist · export/import archive command for user portability.
 - **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 +811,64 @@ 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.*
+- **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-alpha.7",
   "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",

package/src/doctor.ts

@@ -134,7 +134,7 @@ function mcpCheck(): Promise<Check> {
             ok: missing.length === 0,
             detail:
               missing.length === 0
-                ? `handshake OK, 5 tools listed (${names.join(", ")})`
+                ? `handshake OK, ${names.length} tools listed (${names.join(", ")})`
                 : `missing tools: ${missing.join(", ")}`,
           });
         }

package/src/init.ts

@@ -58,6 +58,14 @@ You have a local memory MCP server (\`open-memex\`) with eleven tools:
 - 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 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 — try a few keyword variants
   (including the user's own language) when the first search comes up empty.

package/src/mcp.ts

@@ -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,6 +20,9 @@
  */
 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.ts";
 import { resolveProjectScope, PERSONAL_SCOPE, type Scope } from "./scope.ts";
@@ -51,7 +55,18 @@ import {
   type ToolResult,
 } from "./tools/ops.ts";
 
-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: string = (() => {
+  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.
@@ -80,6 +95,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

package/src/store/markdown.ts

@@ -8,19 +8,21 @@ import {
   inRepoMemoriesDirPath,
 } from "../paths.ts";
 
-/** 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",
 ] as const;
 
 const TAXONOMY = new Set<string>(MEMORY_TYPE_TAXONOMY);

package/src/tools/ops.ts

@@ -77,9 +77,15 @@ 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 type MemoryAddArgs = z.infer<z.ZodObject<typeof memoryAddArgs>>;
 
@@ -239,7 +245,7 @@ export async function addMemory(
   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);