open-memex 0.3.0-alpha → 0.3.0-alpha.3

package/dist/store/sync.js

@@ -0,0 +1,88 @@
+import fs from "node:fs";
+import { db } from "./db.js";
+import { cjkIndexText } from "../retrieve/cjk.js";
+import { contentHash, repairChain } from "./lifecycle.js";
+import { iterMemoryFiles, readMemoryFile, timeToMs, } from "./markdown.js";
+const UPSERT_SQL = `
+  INSERT INTO memories (id, scope_key, scope, visibility, project_name, type, role, importance, status, tags, content, cjk, content_hash, superseded_by, source, file_path, mtime_ms, created_at, updated_at)
+  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  ON CONFLICT(id) DO UPDATE SET
+    scope_key    = excluded.scope_key,
+    scope        = excluded.scope,
+    visibility   = excluded.visibility,
+    project_name = excluded.project_name,
+    type         = excluded.type,
+    role         = excluded.role,
+    importance   = excluded.importance,
+    status       = excluded.status,
+    tags         = excluded.tags,
+    content      = excluded.content,
+    cjk          = excluded.cjk,
+    content_hash = excluded.content_hash,
+    superseded_by = excluded.superseded_by,
+    source       = excluded.source,
+    file_path    = excluded.file_path,
+    mtime_ms     = excluded.mtime_ms,
+    updated_at   = excluded.updated_at
+`;
+export function upsertFromFile(mf) {
+    // Chain integrity (§3.3): every write path through Core validates the
+    // supersedes/superseded_by pair and auto-completes a missing side.
+    const { warnings, repaired } = repairChain(mf);
+    for (const w of warnings)
+        console.warn(`[open-memex] chain: ${w}`);
+    const mtimeOf = (m) => {
+        try {
+            return fs.statSync(m.filePath).mtimeMs;
+        }
+        catch {
+            return m.mtimeMs; // file vanished mid-repair; keep the old mtime
+        }
+    };
+    writeRow(mf, repaired.some((r) => r.filePath === mf.filePath) ? mtimeOf(mf) : mf.mtimeMs);
+    for (const r of repaired) {
+        if (r.filePath === mf.filePath)
+            continue;
+        writeRow(r, mtimeOf(r));
+    }
+}
+function writeRow(mf, mtimeMs) {
+    const { fm, body, filePath } = mf;
+    const tags = (fm.tags ?? []).join(",");
+    db().prepare(UPSERT_SQL).run(fm.id, fm.scope_key, fm.scope, fm.visibility, fm.project_name, fm.type, fm.role, fm.importance, fm.status, tags, body, cjkIndexText(body + "\n" + tags), contentHash(body), fm.superseded_by ?? null, fm.source ?? "", filePath, mtimeMs, timeToMs(fm.created_at), timeToMs(fm.updated_at));
+}
+export function deleteFromIndex(id) {
+    db().prepare(`DELETE FROM memories WHERE id = ?`).run(id);
+}
+export function syncScope(scopeKey) {
+    const d = db();
+    const stats = { added: 0, updated: 0, removed: 0, scanned: 0 };
+    const existing = d
+        .prepare(`SELECT id, file_path, mtime_ms FROM memories WHERE scope_key = ?`)
+        .all(scopeKey);
+    const existingById = new Map(existing.map((r) => [r.id, r]));
+    const seen = new Set();
+    for (const fp of iterMemoryFiles(scopeKey)) {
+        const mf = readMemoryFile(fp);
+        if (!mf)
+            continue;
+        stats.scanned++;
+        seen.add(mf.fm.id);
+        const prev = existingById.get(mf.fm.id);
+        if (!prev) {
+            upsertFromFile(mf);
+            stats.added++;
+        }
+        else if (prev.mtime_ms !== mf.mtimeMs || prev.file_path !== mf.filePath) {
+            upsertFromFile(mf);
+            stats.updated++;
+        }
+    }
+    for (const row of existing) {
+        if (!seen.has(row.id) || !fs.existsSync(row.file_path)) {
+            deleteFromIndex(row.id);
+            stats.removed++;
+        }
+    }
+    return stats;
+}

package/dist/store/v2migrate.js

@@ -0,0 +1,158 @@
+import fs from "node:fs";
+import path from "node:path";
+import { paths } from "../paths.js";
+import { parseRawFrontmatter, normalizeFrontmatter, isTaxonomyType, serialize, } from "./markdown.js";
+/**
+ * v1 → v2 file migration (V2-DESIGN §19). Explicit only — run via
+ * `open-memex migrate --to-v2`. Converts frontmatter in place:
+ *
+ *   - scope rename: v1 `user` → v2 `personal` (scope, scope_key, and the
+ *     storage dir `memories/user/` → `memories/personal/`)
+ *   - times: epoch ms → RFC 3339
+ *   - `priority: N` → `importance: low|normal|high`
+ *   - `type: instruction` → `type: knowledge` + `role: instruction`
+ *   - unknown v1 types → `knowledge` (v2 taxonomy, §3.1)
+ *   - adds `schema_version: 2`, `visibility`, `role`, `status`
+ *
+ * Legacy `my-o-memory` data roots (§19/D13: `.my-o-memory/` →
+ * `.open-memex/`, `~/.my-o-memory/` → `~/.open-memex/`) are merged into the
+ * current root; the old dir is kept as a dated backup.
+ */
+const V2_MARKER = /^schema_version:\s*2(\s|$)/m;
+export function isV2File(raw) {
+    return V2_MARKER.test(raw);
+}
+/**
+ * Plan the v1 → v2 conversion of one file. Returns null when the file is
+ * already v2 (nothing to do). Pure — no disk writes.
+ */
+export function planConversion(filePath, memoriesRoot) {
+    const raw = fs.readFileSync(filePath, "utf8");
+    if (isV2File(raw))
+        return null;
+    const parsed = parseRawFrontmatter(raw);
+    if (!parsed)
+        return null;
+    const { rawFm, body } = parsed;
+    const fm = normalizeFrontmatter(rawFm);
+    const changes = [];
+    // scope rename
+    if (rawFm.scope_kind === "user" || rawFm.scope_key === "user") {
+        changes.push("scope user → personal");
+    }
+    else if (!rawFm.scope) {
+        changes.push(`scope → ${fm.scope} (default)`);
+    }
+    // storage dir move follows scope_key
+    const toPath = path.join(memoriesRoot, fm.scope_key, path.basename(filePath));
+    if (toPath !== filePath) {
+        changes.push(`file moved: ${path.basename(path.dirname(filePath))}/ → ${fm.scope_key}/`);
+    }
+    // visibility default
+    if (!rawFm.visibility) {
+        changes.push(`visibility → ${fm.visibility} (default)`);
+    }
+    // type taxonomy
+    const rawType = rawFm.type;
+    if (rawType === "instruction") {
+        changes.push("type instruction → knowledge, role → instruction (D11)");
+    }
+    else if (typeof rawType === "string" && rawType && !isTaxonomyType(rawType)) {
+        changes.push(`type "${rawType}" → knowledge (not in v2 taxonomy)`);
+        fm.type = "knowledge";
+    }
+    else if (!rawType) {
+        changes.push(`type → ${fm.type} (default)`);
+    }
+    // priority → importance
+    if (typeof rawFm.priority === "number") {
+        changes.push(`priority ${rawFm.priority} → importance ${fm.importance}`);
+    }
+    else if (!rawFm.importance) {
+        changes.push(`importance → ${fm.importance} (default)`);
+    }
+    // times
+    if (typeof rawFm.created_at === "number") {
+        changes.push("created_at/updated_at: epoch ms → RFC 3339");
+    }
+    // status default
+    if (!rawFm.status) {
+        changes.push(`status → ${fm.status} (default)`);
+    }
+    changes.push("schema_version → 2");
+    return { fm, body, fromPath: filePath, toPath, changes };
+}
+/**
+ * Merge a legacy `my-o-memory` data root into the current `open-memex` root.
+ * The old dir is renamed to a dated backup — never deleted. Returns the
+ * backup path, or null when no legacy dir exists.
+ */
+function migrateLegacyDataRoot(dryRun) {
+    const { root } = paths();
+    const legacy = path.join(path.dirname(root), "my-o-memory");
+    if (!fs.existsSync(legacy) || !fs.statSync(legacy).isDirectory())
+        return null;
+    const stamp = new Date().toISOString().slice(0, 10);
+    const backup = `${legacy}.backup-${stamp}`;
+    if (!dryRun) {
+        const legacyMem = path.join(legacy, "memories");
+        if (fs.existsSync(legacyMem)) {
+            for (const entry of fs.readdirSync(legacyMem)) {
+                const src = path.join(legacyMem, entry);
+                const dst = path.join(root, "memories", entry);
+                if (!fs.existsSync(dst)) {
+                    fs.renameSync(src, dst);
+                }
+                else {
+                    // merge file-by-file, never overwrite
+                    for (const name of fs.readdirSync(src)) {
+                        const s = path.join(src, name);
+                        const d = path.join(dst, name);
+                        if (!fs.existsSync(d))
+                            fs.renameSync(s, d);
+                    }
+                }
+            }
+        }
+        fs.renameSync(legacy, backup);
+    }
+    return backup;
+}
+export function migrateV2(opts) {
+    const { memories: memoriesRoot } = paths();
+    const result = {
+        scanned: 0,
+        converted: 0,
+        skippedV2: 0,
+        plans: [],
+        legacyBackup: null,
+    };
+    result.legacyBackup = migrateLegacyDataRoot(opts.dryRun);
+    if (!fs.existsSync(memoriesRoot))
+        return result;
+    for (const entry of fs.readdirSync(memoriesRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(memoriesRoot, entry.name);
+        for (const name of fs.readdirSync(dir)) {
+            if (!name.endsWith(".md"))
+                continue;
+            const filePath = path.join(dir, name);
+            result.scanned++;
+            const plan = planConversion(filePath, memoriesRoot);
+            if (!plan) {
+                result.skippedV2++;
+                continue;
+            }
+            if (!opts.dryRun) {
+                fs.mkdirSync(path.dirname(plan.toPath), { recursive: true });
+                fs.writeFileSync(plan.toPath, serialize(plan.fm, plan.body), "utf8");
+                if (plan.toPath !== plan.fromPath)
+                    fs.unlinkSync(plan.fromPath);
+            }
+            result.converted++;
+            result.plans.push(plan);
+        }
+    }
+    return result;
+}

package/dist/tools/memory.js

@@ -0,0 +1,40 @@
+import { tool } from "@opencode-ai/plugin/tool";
+import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, TOOL_DESCRIPTIONS, } from "./ops.js";
+export function makeTools(getScope, cfg) {
+    const memory_add = tool({
+        description: TOOL_DESCRIPTIONS.memory_add,
+        args: memoryAddArgs,
+        async execute(args) {
+            return addMemory(getScope, cfg, args);
+        },
+    });
+    const memory_search = tool({
+        description: TOOL_DESCRIPTIONS.memory_search,
+        args: memorySearchArgs,
+        async execute(args) {
+            return searchMemories(getScope, args);
+        },
+    });
+    const memory_list = tool({
+        description: TOOL_DESCRIPTIONS.memory_list,
+        args: memoryListArgs,
+        async execute(args) {
+            return listMemories(getScope, args);
+        },
+    });
+    const memory_supersede = tool({
+        description: TOOL_DESCRIPTIONS.memory_supersede,
+        args: memorySupersedeArgs,
+        async execute(args) {
+            return supersedeMemory(cfg, args);
+        },
+    });
+    const memory_forget = tool({
+        description: TOOL_DESCRIPTIONS.memory_forget,
+        args: memoryForgetArgs,
+        async execute(args) {
+            return forgetMemory(args);
+        },
+    });
+    return { memory_add, memory_search, memory_list, memory_forget, memory_supersede };
+}

package/dist/tools/ops.js

@@ -0,0 +1,186 @@
+/**
+ * Framework-agnostic memory operations.
+ *
+ * The same functions back both the opencode plugin tools
+ * (`src/tools/memory.ts`) and the generic MCP server (`src/mcp.ts`).
+ * They take plain validated args and return a plain { title, output }
+ * result; each host adapts that to its own tool-result shape.
+ */
+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 { upsertFromFile, deleteFromIndex } from "../store/sync.js";
+import { findDuplicates, supersede } from "../store/lifecycle.js";
+import { db } from "../store/db.js";
+import { redact } from "../redact.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.",
+    memory_search: "Search persistent memory by keyword (BM25 full-text). Returns matching memories from the current project and/or personal scope. Call before asking the user about past decisions, conventions, or preferences they may have told you before — try a few keyword variants, including the user's own language, when the first search comes up empty.",
+    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.",
+};
+/** Shared zod input shapes (raw shape, not z.object — hosts wrap as needed). */
+export const scopeArg = z
+    .enum(["project", "personal", "user"])
+    .optional()
+    .describe("Memory scope. `project` = tied to this repo. `personal` = global across all your projects. `user` is a deprecated alias of `personal`. Default: project.");
+export const memoryAddArgs = {
+    content: z.string().min(1).describe("The fact to remember. One idea per memory."),
+    type: z
+        .enum(MEMORY_TYPE_TAXONOMY)
+        .optional()
+        .describe("Category of memory. Default: note."),
+    scope: scopeArg,
+    tags: z.array(z.string()).optional().describe("Optional tags for filtering."),
+};
+export const memorySearchArgs = {
+    query: z
+        .string()
+        .min(1)
+        .describe("Free-text query. File paths, error strings, identifiers work well."),
+    scope: z
+        .enum(["project", "personal", "user", "both"])
+        .optional()
+        .describe("Which scope(s) to search. Default: both."),
+    type: z.string().optional().describe("Restrict to memories of this type."),
+    limit: z.number().int().min(1).max(50).optional(),
+};
+export const memoryListArgs = {
+    scope: scopeArg,
+    type: z.string().optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+};
+export const memorySupersedeArgs = {
+    id: z.string().min(1).describe("ID of the memory being replaced."),
+    content: z.string().min(1).describe("The new, corrected content."),
+    type: z
+        .enum(MEMORY_TYPE_TAXONOMY)
+        .optional()
+        .describe("Category of the new memory. Defaults to the old memory's type."),
+    tags: z.array(z.string()).optional().describe("Optional tags for the new memory."),
+};
+export const memoryForgetArgs = {
+    id: z.string().min(1),
+};
+function resolveScope(getScope, kind) {
+    return kind === "personal" || kind === "user" ? PERSONAL_SCOPE : getScope();
+}
+function buildFrontmatter(s, body) {
+    const rfc = msToRfc3339(Date.now());
+    return {
+        id: ulid(),
+        schema_version: 2,
+        scope_key: s.key,
+        scope: s.kind === "project" ? "project" : "personal",
+        visibility: s.kind === "project" ? "internal" : "private",
+        project_name: s.projectName,
+        type: body.type,
+        role: "knowledge",
+        importance: "normal",
+        status: "active",
+        tags: body.tags,
+        source: body.source,
+        created_at: rfc,
+        updated_at: rfc,
+        supersedes: null,
+        superseded_by: null,
+    };
+}
+export async function addMemory(getScope, cfg, args) {
+    const { content: redacted, hadSecret, matchedPattern } = redact(args.content, cfg.redactPatterns);
+    const secretNote = hadSecret
+        ? `\nNote: content matched a secret pattern (${matchedPattern}); it was saved with the secret masked (first 4 chars kept, rest replaced with x).`
+        : "";
+    const s = resolveScope(getScope, args.scope);
+    // Dedup on write (§3.4): identical content is idempotent; near-duplicates
+    // are reported so the caller can supersede instead of duplicating.
+    const dups = findDuplicates(s.key, redacted);
+    if (dups.exact) {
+        return {
+            title: "memory: already exists",
+            output: `Identical memory already exists: id=${dups.exact.id}. Not duplicated.`,
+        };
+    }
+    const fm = buildFrontmatter(s, {
+        type: args.type ?? "fact",
+        tags: args.tags ?? [],
+        source: "tool",
+    });
+    const { filePath } = writeMemoryFile(fm, redacted);
+    const mf = readMemoryFile(filePath);
+    if (mf)
+        upsertFromFile(mf);
+    let output = `Saved to ${s.kind} scope (${s.key}) as ${fm.type}. id=${fm.id}${secretNote}`;
+    for (const n of dups.near) {
+        output += `\nNote: similar memory exists (score ${n.score.toFixed(2)}): id=${n.id} — ${n.snippet}. Use memory_supersede if this replaces it.`;
+    }
+    return { title: `memory: saved ${fm.id}`, output };
+}
+export async function searchMemories(getScope, args) {
+    const project = getScope();
+    const scopeKeys = args.scope === "personal" || args.scope === "user"
+        ? [PERSONAL_SCOPE.key]
+        : args.scope === "project"
+            ? [project.key]
+            : [project.key, PERSONAL_SCOPE.key];
+    const hits = search(args.query, {
+        scopeKeys,
+        limit: args.limit,
+        type: args.type,
+    });
+    if (hits.length === 0) {
+        return {
+            title: "memory: 0 results",
+            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()}`);
+    return { title: `memory: ${hits.length} result(s)`, output: lines.join("\n") };
+}
+export async function listMemories(getScope, args) {
+    const s = resolveScope(getScope, args.scope);
+    const hits = list(s.key, { type: args.type, limit: args.limit });
+    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()}`);
+    return { title: `memory: ${hits.length} in ${s.key}`, output: lines.join("\n") };
+}
+export async function supersedeMemory(cfg, args) {
+    const { content: redacted, hadSecret, matchedPattern } = redact(args.content, cfg.redactPatterns);
+    const secretNote = hadSecret ? ` (secret masked: ${matchedPattern})` : "";
+    try {
+        const { oldMf, newMf } = supersede(args.id, {
+            body: redacted,
+            type: args.type,
+            tags: args.tags,
+            source: "tool",
+        });
+        upsertFromFile(oldMf);
+        upsertFromFile(newMf);
+        return {
+            title: `memory: superseded ${oldMf.fm.id}`,
+            output: `Replaced ${oldMf.fm.id} with ${newMf.fm.id} (old kept as history).${secretNote}`,
+        };
+    }
+    catch (e) {
+        return {
+            title: "memory: supersede failed",
+            output: e.message,
+        };
+    }
+}
+export async function forgetMemory(args) {
+    const row = db()
+        .prepare(`SELECT scope_key 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);
+    deleteFromIndex(args.id);
+    return { title: "memory: forgotten", output: `Deleted ${args.id}.` };
+}

package/docs/V2-DESIGN.md

@@ -578,6 +578,25 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   auto-discovers `.vscode/mcp.json` and `.cursor/mcp.json`, so repos already set up for
   VS Code get VS support for free; the explicit `.mcp.json` is the source-controllable
   option. 2026-09-27.*
+- **D21** — The published npm package ships pre-compiled JS (`tsc -p tsconfig.build.json`
+  → `dist/`, via `prepublishOnly`; bin points at `dist/cli.js`). *Rationale: Node's
+  `--experimental-strip-types` refuses files under `node_modules`
+  (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), so the old launcher
+  (`bin/open-memex.js` re-execing `src/cli.ts`) crashed on every global install —
+  reported 2026-09-27 on Node v22.12.0. Development stays build-free (`npm run cli`
+  / `npm run mcp` run `src/` directly); `doctor`'s MCP self-check resolves its server
+  entry the same way it is running (`dist/mcp.js` vs `src/mcp.ts`). The opencode
+  native plugin still loads `src/index.ts` (Bun strips types anywhere). 2026-09-27.*
+- **D22** — `init` writes the Copilot memory instructions to the **user level** by
+  default (`~/.copilot/copilot-instructions.md`; `%USERPROFILE%\copilot-
+  instructions.md` for Visual Studio 2026) instead of the repo-level
+  `.github/copilot-instructions.md`. *Rationale: the repo-level file is checked in,
+  so teammates without open-memex get Copilot errors about missing `memory_*`
+  tools. The user-level location is GitHub's official personal-instructions slot
+  (highest priority, all projects, never in a repo). `--instructions project`
+  keeps the old repo-level behavior for teams where everyone uses open-memex.
+  The instructions carry a guard clause ("ignore this section when the
+  `open-memex` MCP server is not available") as cheap insurance. 2026-09-27.*
 
 ## Open Questions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.3.0-alpha",
+  "version": "0.3.0-alpha.3",
   "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",
@@ -16,7 +16,9 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "cli": "node --experimental-strip-types src/cli.ts",
-    "mcp": "node --experimental-strip-types src/mcp.ts"
+    "mcp": "node --experimental-strip-types src/mcp.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.1",
@@ -32,7 +34,7 @@
     "typescript": "^5.6.0"
   },
   "bin": {
-    "open-memex": "bin/open-memex.js"
+    "open-memex": "dist/cli.js"
   },
   "engines": {
     "node": ">=22.6"

package/src/cli.ts

@@ -20,33 +20,39 @@ import { paths } from "./paths.ts";
 import { redact } from "./redact.ts";
 import { resolveMcpCommand } from "./init.ts";
 import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 
-function usage(): never {
+function usage(exitCode = 1): never {
   console.log(`open-memex CLI
 
 Usage:
-  node --experimental-strip-types src/cli.ts where
-  node --experimental-strip-types src/cli.ts list [--scope project|personal] [--type T] [--limit N]
-  node --experimental-strip-types src/cli.ts search "query" [--scope project|personal|both] [--type T] [--limit N]
-  node --experimental-strip-types src/cli.ts add "content" [--scope project|personal] [--type T] [--tag t1,t2]
-  node --experimental-strip-types src/cli.ts supersede <id> "new content" [--type T] [--tag t1,t2]
-  node --experimental-strip-types src/cli.ts status <id> active|deprecated|retracted|archived
-  node --experimental-strip-types src/cli.ts forget <id>
-  node --experimental-strip-types src/cli.ts reindex
-  node --experimental-strip-types src/cli.ts scopes
-  node --experimental-strip-types src/cli.ts migrate [--from <key>] [--to <key>]
+  open-memex where
+  open-memex list [--scope project|personal] [--type T] [--limit N]
+  open-memex search "query" [--scope project|personal|both] [--type T] [--limit N]
+  open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
+  open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
+  open-memex status <id> active|deprecated|retracted|archived
+  open-memex forget <id>
+  open-memex reindex
+  open-memex scopes
+  open-memex migrate [--from <key>] [--to <key>]
                                           [--dry-run] [--on-conflict newer|overwrite|skip]
-  node --experimental-strip-types src/cli.ts migrate --to-v2 [--dry-run]
-  node --experimental-strip-types src/cli.ts mcp [--print-config vscode|cursor|claude|opencode|visualstudio]
-  node --experimental-strip-types src/cli.ts init [--client vscode|cursor|opencode|visualstudio] [--force] [--yes]
-  node --experimental-strip-types src/cli.ts config [set <key> <value>]
-  node --experimental-strip-types src/cli.ts capture --dry-run "text"
-  node --experimental-strip-types src/cli.ts doctor
+  open-memex migrate --to-v2 [--dry-run]
+  open-memex mcp [--print-config vscode|cursor|claude|opencode|visualstudio]
+  open-memex init [--client vscode|cursor|opencode|visualstudio]
+              [--instructions personal|project] [--force] [--yes]
+  open-memex config [set <key> <value>]
+  open-memex capture --dry-run "text"
+  open-memex doctor
 
 One-command project setup: \`open-memex init\` (or \`npx open-memex@alpha init\`) writes
 the MCP config for your editor (\`.vscode/mcp.json\`, \`.cursor/mcp.json\`,
-\`opencode.jsonc\`, or Visual Studio's solution-level \`.mcp.json\`) plus
-\`.github/copilot-instructions.md\` — no copy-paste needed.
+\`opencode.jsonc\`, or Visual Studio's solution-level \`.mcp.json\`) — no copy-paste
+needed. The Copilot memory instructions default to your user-level
+\`~/.copilot/copilot-instructions.md\` (all projects, never checked into a repo);
+\`--instructions project\` writes \`.github/copilot-instructions.md\` instead for
+teams where everyone uses open-memex.
 Existing files are merged, never clobbered; re-running is safe. On a terminal it
 asks which editor to set up and a couple of settings (keyword capture, first-turn
 injection); \`--yes\` accepts all defaults, and non-terminal runs never prompt.
@@ -66,7 +72,7 @@ git remote after memories were already stored under the cwd-based key.
 \`migrate --to-v2\` converts v1 memory files to the v2 format (§19):
 user→personal scope rename, epoch→RFC 3339 times, priority→importance,
 type: instruction→role split. Always preview with --dry-run first.`);
-  process.exit(1);
+  process.exit(exitCode);
 }
 
 function parseFlags(argv: string[]): Record<string, string> {
@@ -179,7 +185,16 @@ function printMcpConfig(client: string): never {
 
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
-  if (!cmd) usage();
+  if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") usage(0);
+
+  if (cmd === "--version" || cmd === "-v") {
+    // package.json sits two levels above this file in both layouts
+    // (src/cli.ts and dist/cli.js).
+    const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+    console.log(`open-memex ${pkg.version}`);
+    return;
+  }
 
   const cfg = loadConfig();
   const project = resolveProjectScope(process.cwd());
@@ -225,6 +240,7 @@ async function main() {
       client: flags["client"],
       force: flags["force"] === "true",
       yes: flags["yes"] === "true",
+      instructions: flags["instructions"],
     });
     return;
   }

package/src/doctor.ts

@@ -73,15 +73,26 @@ function storageCheck(): Check {
 function mcpCheck(): Promise<Check> {
   const name = "mcp";
   return new Promise((resolve) => {
-    const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
-    const server = path.join(root, "src", "mcp.ts");
+    // D21: the installed package runs compiled JS from dist/ (Node refuses
+    // --experimental-strip-types for files under node_modules), while a source
+    // checkout runs src/ directly. Resolve the server entry the same way this
+    // file itself is running.
+    const here = fileURLToPath(import.meta.url);
+    const fromDist = here.endsWith(`dist${path.sep}doctor.js`);
+    const server = fromDist
+      ? path.join(path.dirname(here), "mcp.js")
+      : path.join(path.dirname(path.dirname(here)), "src", "mcp.ts");
     if (!fs.existsSync(server)) {
       resolve({ name, ok: false, detail: `server entry not found: ${server}` });
       return;
     }
-    const child = spawn(process.execPath, ["--experimental-strip-types", server], {
-      stdio: ["pipe", "pipe", "pipe"],
-    });
+    const child = spawn(
+      process.execPath,
+      fromDist ? [server] : ["--experimental-strip-types", server],
+      {
+        stdio: ["pipe", "pipe", "pipe"],
+      },
+    );
     const done = (c: Check) => {
       clearTimeout(timer);
       try {