open-memex 0.7.0-alpha.2 → 0.7.0-alpha.3

package/AGENTS.md

@@ -102,7 +102,7 @@ The published `open-memex` bin points at `dist/cli.js` (compiled at publish time
 From a source checkout, `npm run cli` / `npm run mcp` still run `src/` directly
 with type-stripping — no build step needed for development.
 
-There is **no `npm test`** and no CI. Verification loop is: `npm run typecheck` + `smoke-pure.ts` + (if touching sqlite) `npm run cli -- reindex` against a scratch `MY_O_MEMORY_HOME`.
+There is **no `npm test`** and no CI. Verification loop is: `npm run typecheck` + `smoke-pure.ts` + (if touching sqlite) `npm run cli -- reindex` against a scratch `OPEN_MEMEX_HOME`.
 
 To load the plugin in opencode locally, `~/.config/opencode/opencode.jsonc` must have:
 ```
@@ -115,7 +115,7 @@ Restart opencode after any change — the plugin is not hot-reloaded.
 Storage root:
 - Windows: `%APPDATA%\open-memex\`
 - Linux/macOS: `$XDG_DATA_HOME/open-memex/` (fallback `~/.local/share/open-memex/`)
-- Override with `MY_O_MEMORY_HOME` (use this for tests to avoid clobbering real data).
+- Override with `OPEN_MEMEX_HOME` (use this for tests to avoid clobbering real data). The pre-rename `MY_O_MEMORY_HOME` is still honored as a fallback (D62).
 
 Layout: `memories/<scope_key>/<id>.md` (YAML frontmatter + body) + `index.db` (SQLite FTS5).
 

package/CHANGELOG.md

@@ -9,6 +9,10 @@ the `@alpha` tag are development snapshots and are not listed individually.
 
 ## [Unreleased]
 
+## Environment variable names (D62)
+
+- The override variables now answer to `OPEN_MEMEX_HOME` (storage root) and `OPEN_MEMEX_CONFIG` (config path). The pre-rename `MY_O_MEMORY_HOME` / `MY_O_MEMORY_CONFIG` names keep working as fallbacks — nothing to migrate, the data root itself does not move. `doctor` notes when the storage root came from the legacy variable.
+
 ## Proactive capture: checkpoint proposals and aliases (D61)
 
 - At task checkpoints the agent now proposes instead of waiting to be asked: when a task wraps up, it offers 1–3 short candidate memories distilled from the session (decisions and their reasons, conventions, gotchas, approaches tried and abandoned) and saves only the ones you approve — approved inferences are marked `source: "inference"`. One memorability rubric and one search discipline (break the question into concepts, try several phrasings, check both scopes) are written into every guidance surface — the bundled skill, the AGENTS.md memory-hygiene footer, the MCP handshake, and the tool descriptions — so behavior is consistent across editors. Nothing is auto-drafted in the background; that posture waits on memory visibility.

package/README.md

@@ -578,8 +578,9 @@ branches and PRs like any other file.
 
 Settings live in `~/.config/opencode/open-memex.jsonc` — the `opencode` in the
 path is historical; this one file is shared by every client. Override the config
-path with `MY_O_MEMORY_CONFIG` and the storage root with `MY_O_MEMORY_HOME`
-(legacy environment names from before the rename, still honored).
+path with `OPEN_MEMEX_CONFIG` and the storage root with `OPEN_MEMEX_HOME`
+(the pre-rename `MY_O_MEMORY_CONFIG` / `MY_O_MEMORY_HOME` names are still
+honored as fallbacks).
 
 Defaults:
 

package/README.zh-CN.md

@@ -391,7 +391,7 @@ npm install -g open-memex@latest   # 或 @alpha
 
 ## 配置
 
-设置放在 `~/.config/opencode/open-memex.jsonc`——路径里的 `opencode` 是历史名；这一个文件由所有客户端共享。用 `MY_O_MEMORY_CONFIG` 覆盖配置路径，用 `MY_O_MEMORY_HOME` 覆盖存储根目录（改名之前留下的旧环境变量名，仍然有效）。
+设置放在 `~/.config/opencode/open-memex.jsonc`——路径里的 `opencode` 是历史名；这一个文件由所有客户端共享。用 `OPEN_MEMEX_CONFIG` 覆盖配置路径，用 `OPEN_MEMEX_HOME` 覆盖存储根目录（改名之前的旧变量名 `MY_O_MEMORY_CONFIG` / `MY_O_MEMORY_HOME` 仍然有效，作为回退）。
 
 默认值：
 

package/dist/config.js

@@ -46,9 +46,13 @@ function stripJsonComments(raw) {
     out = out.replace(/,(\s*[}\]])/g, "$1");
     return out;
 }
-/** Where `config set` / interactive `init` persist. Respects MY_O_MEMORY_CONFIG. */
+/**
+ * Where `config set` / interactive `init` persist. Respects OPEN_MEMEX_CONFIG
+ * (D62); MY_O_MEMORY_CONFIG is the pre-rename fallback, still honored.
+ */
 export function configFilePath() {
-    return (process.env.MY_O_MEMORY_CONFIG ??
+    return (process.env.OPEN_MEMEX_CONFIG ??
+        process.env.MY_O_MEMORY_CONFIG ??
         path.join(os.homedir(), ".config", "opencode", "open-memex.jsonc"));
 }
 function toBool(v) {
@@ -111,6 +115,7 @@ export function saveConfig(patch) {
 /** Path of the config file in effect, or null when using built-in defaults. */
 export function configSource() {
     const candidates = [
+        process.env.OPEN_MEMEX_CONFIG,
         process.env.MY_O_MEMORY_CONFIG,
         path.join(os.homedir(), ".config", "opencode", "open-memex.jsonc"),
         path.join(os.homedir(), ".config", "opencode", "open-memex.json"),

package/dist/doctor.js

@@ -8,7 +8,7 @@ import path from "node:path";
 import { spawn, execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { loadConfig, configSource, DEFAULT_CONFIG } from "./config.js";
-import { paths } from "./paths.js";
+import { paths, homeOverride } from "./paths.js";
 import { resolveCwdScope } from "./scope.js";
 import { db, backendName } from "./store/db.js";
 import { LEGACY_PACKAGE_NAME, opencodeGlobalConfigPath, userMcpConfigPath } from "./init.js";
@@ -54,7 +54,13 @@ function storageCheck() {
     try {
         const p = paths();
         fs.accessSync(p.memories, fs.constants.W_OK);
-        return { name: "storage", ok: true, detail: `${p.root} (writable)` };
+        // D62: when the root came from the legacy env var, say so (still ok —
+        // the fallback is supported, doctor just names the current one).
+        const via = homeOverride()?.via;
+        const note = via === "MY_O_MEMORY_HOME"
+            ? " (via legacy MY_O_MEMORY_HOME — OPEN_MEMEX_HOME is the current name)"
+            : "";
+        return { name: "storage", ok: true, detail: `${p.root} (writable)${note}` };
     }
     catch (err) {
         return { name: "storage", ok: false, detail: String(err) };
@@ -559,9 +565,11 @@ export async function runDoctor() {
 function legacyCheck() {
     const name = "legacy my-o-memory";
     const found = [];
-    const envHome = process.env.MY_O_MEMORY_HOME;
+    // D62: the override may arrive via either env var name; check the value
+    // in effect, not just the legacy one.
+    const envHome = homeOverride()?.dir;
     if (envHome && envHome.includes(LEGACY_PACKAGE_NAME))
-        found.push(`MY_O_MEMORY_HOME points at a pre-rename dir (${envHome}) — unset it, then merge old data with \`open-memex migrate --to-v2\``);
+        found.push(`memory home points at a pre-rename dir (${envHome}) — unset it, then merge old data with \`open-memex migrate --to-v2\``);
     const root = paths().root;
     const legacyDir = path.join(path.dirname(root), LEGACY_PACKAGE_NAME);
     if (fs.existsSync(legacyDir) && fs.statSync(legacyDir).isDirectory())

package/dist/paths.js

@@ -2,9 +2,23 @@ import path from "node:path";
 import fs from "node:fs";
 import os from "node:os";
 import { execFileSync } from "node:child_process";
-function dataRoot() {
+/**
+ * D62: the data-root override env var. `OPEN_MEMEX_HOME` is the current
+ * name; `MY_O_MEMORY_HOME` (pre-rename package name) is still honored as a
+ * fallback so existing setups and scripts keep working. New name wins
+ * when both are set.
+ */
+export function homeOverride() {
+    if (process.env.OPEN_MEMEX_HOME)
+        return { dir: path.resolve(process.env.OPEN_MEMEX_HOME), via: "OPEN_MEMEX_HOME" };
     if (process.env.MY_O_MEMORY_HOME)
-        return path.resolve(process.env.MY_O_MEMORY_HOME);
+        return { dir: path.resolve(process.env.MY_O_MEMORY_HOME), via: "MY_O_MEMORY_HOME" };
+    return null;
+}
+function dataRoot() {
+    const override = homeOverride();
+    if (override)
+        return override.dir;
     if (process.platform === "win32") {
         const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
         return path.join(appData, "open-memex");

package/docs/V2-DESIGN.md

@@ -1304,13 +1304,24 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   distillation over host transcripts stays its own group; it will
   reuse this rubric.
 
+- **D62 — environment variable names grow current-name aliases.** The
+  data-root and config-path overrides predate the rename and kept the
+  old package's name (`MY_O_MEMORY_HOME`, `MY_O_MEMORY_CONFIG`) — a
+  stale-looking name is a trap for users and agents scripting against
+  the current one. `OPEN_MEMEX_HOME` / `OPEN_MEMEX_CONFIG` are now the
+  preferred names; the legacy names still work as fallbacks (new name
+  wins when both are set), so existing setups and scripts never break.
+  The data root itself does not move — only the variable names change.
+  `doctor`'s storage check notes when the root arrived via the legacy
+  variable, and its pre-rename-dir leftovers check reads whichever
+  variable is in effect.
+
 ## Open Questions
 
 _All resolved — see D10 (rename), D11 (type/role split), D12 (explicit pull)._
+- **Checkpoint proactivity for capture (open, 2026-10-02):** D53 retired checkpoint *polling* — the server pushes draft counts instead. But agent proactivity at task checkpoints genuinely helps knowledge capture (§3.5 distillation), so the open question is the degree: proactive enough to catch distillable moments, without nagging the user or burning tokens at every checkpoint. Candidate directions (server-pushed hints in tool results, client-side heuristics, or a middle setting) to be evaluated in a later version; default posture TBD. **Update (2026-10-03): decided in D61 — propose posture** (agent proposes 1–3 candidates at task checkpoints, saves only on approval; auto-draft deferred until memory visibility ships, see the MEMORY_VISIBILITY question below).
 
-- **Checkpoint proactivity for capture (open, 2026-10-02):** D53 retired checkpoint *polling* — the server pushes draft counts instead. But agent proactivity at task checkpoints genuinely helps knowledge capture (§3.5 distillation), so the open question is the degree: proactive enough to catch distillable moments, without nagging the user or burning tokens at every checkpoint. Candidate directions (server-pushed hints in tool results, client-side heuristics, or a middle setting) to be evaluated in a later version; default posture TBD.
-
-- **Retrieval robustness: phrasing, synonyms, extra words (open, 2026-10-03):** keyword search matches word forms, not meaning — the asker phrases it differently, adds a word, or uses a synonym and the memory is missed. The current FTS5 setup (porter stemming + pre-tokenized CJK bigrams) already covers morphology and substrings; it cannot bridge semantics. Layered candidate directions, cheapest first: (1) query construction — never feed a raw sentence to FTS; extract content terms, drop stopwords, OR them and let bm25 rank, so extra words hurt ranking instead of killing the match; (2) agent-side query expansion as an explicit protocol in the skill/instructions (decompose the question into concepts, generate 2–3 synonym variants per concept, run several searches before giving up — the LLM is the synonym dictionary, no embedding model needed); (3) capture-time aliasing — when a memory is written, the agent attaches keyword/synonym aliases so future phrasings can hit it. Embeddings are the design's reserved optional capability: real semantic matching, but they require a design decision and a local model to distribute, so they stay deferred unless (1)–(3) prove insufficient. Note (3) pairs naturally with the proactive-capture question below: the same capture pass that proposes a memory can attach its aliases. **Status (2026-10-03): layer (1) shipped (D56, 0.6.1)** — query construction now filters EN/CJK function words, dedupes, and caps terms. Layers (2) agent-side expansion and (3) capture-time aliasing remain open; embeddings stay deferred.
+- **Retrieval robustness: phrasing, synonyms, extra words (open, 2026-10-03):** keyword search matches word forms, not meaning — the asker phrases it differently, adds a word, or uses a synonym and the memory is missed. The current FTS5 setup (porter stemming + pre-tokenized CJK bigrams) already covers morphology and substrings; it cannot bridge semantics. Layered candidate directions, cheapest first: (1) query construction — never feed a raw sentence to FTS; extract content terms, drop stopwords, OR them and let bm25 rank, so extra words hurt ranking instead of killing the match; (2) agent-side query expansion as an explicit protocol in the skill/instructions (decompose the question into concepts, generate 2–3 synonym variants per concept, run several searches before giving up — the LLM is the synonym dictionary, no embedding model needed); (3) capture-time aliasing — when a memory is written, the agent attaches keyword/synonym aliases so future phrasings can hit it. Embeddings are the design's reserved optional capability: real semantic matching, but they require a design decision and a local model to distribute, so they stay deferred unless (1)–(3) prove insufficient. Note (3) pairs naturally with the proactive-capture question below: the same capture pass that proposes a memory can attach its aliases. **Status (2026-10-03): layer (1) shipped (D56, 0.6.1)** — query construction now filters EN/CJK function words, dedupes, and caps terms. Layers (2) agent-side expansion and (3) capture-time aliasing remain open; embeddings stay deferred. **Update (2026-10-03): layers (2) and (3) shipped in D61** — agent-side expansion as guidance text on every surface, capture-time aliases indexed in their own FTS column behind the `captureAliases` flag. Embeddings stay deferred.
 
 - **Proactive capture: agent judgment of what is worth remembering (open, 2026-10-03):** companion to the checkpoint-proactivity question above — that one asks *when* to prompt; this one asks *what qualifies*. Agent hosts with good long-term memory (e.g. Muse) get their results from explicit memorability criteria plus checkpoint consolidation, not from silent background magic; open-memex can adopt both halves. Candidate criteria to teach via the skill/instructions: decisions **and their rationale**, preferences, conventions, gotchas, and abandoned paths ("we tried X, it failed because…") are worth proposing; one-off task details and anything re-derivable from the code are not. Two postures to evaluate: propose-at-checkpoint (agent asks "worth saving?", user vetoes, then `memory_add`) versus auto-draft (agent writes outbox drafts unasked and surfaces them in a batch at the next checkpoint — drafts are git-invisible and deletable, so the cost of a wrong guess is low). Hard boundaries either way: project scope never auto-submits, and no cross-session background consolidation is possible — the plugin lives inside sessions, so consolidation happens at in-session checkpoints and wrap-up passes only. This question also decides how much aliasing (retrieval question above) the capture pass should generate.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.7.0-alpha.2",
+  "version": "0.7.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",

package/scripts/smoke-pure.ts

@@ -12,6 +12,8 @@ import { contentHash, similarity, NEAR_DUP_THRESHOLD } from "../src/store/lifecy
 import { userMcpConfigPath, mergeServerEntry, detectInstalledClients, mergePluginEntry, mergeV2PluginEntry, removeV2PluginEntry, opencodeGlobalConfigPath, printManualEntryHint, parseJsonConfig, removeServerEntry, removePluginEntry, removeInstructionsSection, LEGACY_PACKAGE_NAME, shouldInstallSkill } from "../src/init.ts";
 import { z } from "zod";
 import { memoryAddArgs } from "../src/tools/ops.ts";
+import { dataRootPath, homeOverride } from "../src/paths.ts";
+import { configFilePath } from "../src/config.ts";
 
 let fails = 0;
 function ok(name: string, cond: boolean, info?: unknown) {
@@ -423,6 +425,38 @@ ok("failed backup leaves legacy dir for retry", fs.existsSync(legacyRoot2));
 delete process.env.MY_O_MEMORY_HOME;
 fs.rmSync(tmpHome, { recursive: true, force: true });
 
+console.log("== env var names (D62) ==");
+{
+  const saved = {
+    n: process.env.OPEN_MEMEX_HOME,
+    l: process.env.MY_O_MEMORY_HOME,
+    nc: process.env.OPEN_MEMEX_CONFIG,
+    lc: process.env.MY_O_MEMORY_CONFIG,
+  };
+  const restore = () => {
+    const set = (k: string, v: string | undefined) => (v === undefined ? delete process.env[k] : (process.env[k] = v));
+    set("OPEN_MEMEX_HOME", saved.n);
+    set("MY_O_MEMORY_HOME", saved.l);
+    set("OPEN_MEMEX_CONFIG", saved.nc);
+    set("MY_O_MEMORY_CONFIG", saved.lc);
+  };
+  try {
+    delete process.env.OPEN_MEMEX_HOME;
+    delete process.env.MY_O_MEMORY_HOME;
+    ok("no override -> homeOverride null", homeOverride() === null);
+    process.env.MY_O_MEMORY_HOME = "/tmp/legacy-home";
+    ok("legacy fallback honored", dataRootPath().endsWith("legacy-home") && homeOverride()?.via === "MY_O_MEMORY_HOME");
+    process.env.OPEN_MEMEX_HOME = "/tmp/new-home";
+    ok("new name wins over legacy", dataRootPath().endsWith("new-home") && homeOverride()?.via === "OPEN_MEMEX_HOME");
+    process.env.MY_O_MEMORY_CONFIG = "/tmp/legacy.jsonc";
+    ok("config legacy fallback", configFilePath().endsWith("legacy.jsonc"));
+    process.env.OPEN_MEMEX_CONFIG = "/tmp/new.jsonc";
+    ok("config new name wins", configFilePath().endsWith("new.jsonc"));
+  } finally {
+    restore();
+  }
+}
+
 console.log("== lifecycle pure: contentHash / similarity ==");
 ok("hash deterministic + whitespace-insensitive", contentHash("hello   world\n") === contentHash("hello world"));
 ok("hash differs on content", contentHash("hello world") !== contentHash("hello mars"));

package/src/config.ts

@@ -84,9 +84,13 @@ function stripJsonComments(raw: string): string {
   return out;
 }
 
-/** Where `config set` / interactive `init` persist. Respects MY_O_MEMORY_CONFIG. */
+/**
+ * Where `config set` / interactive `init` persist. Respects OPEN_MEMEX_CONFIG
+ * (D62); MY_O_MEMORY_CONFIG is the pre-rename fallback, still honored.
+ */
 export function configFilePath(): string {
   return (
+    process.env.OPEN_MEMEX_CONFIG ??
     process.env.MY_O_MEMORY_CONFIG ??
     path.join(os.homedir(), ".config", "opencode", "open-memex.jsonc")
   );
@@ -156,6 +160,7 @@ export function saveConfig(patch: Record<string, unknown>): string {
 /** Path of the config file in effect, or null when using built-in defaults. */
 export function configSource(): string | null {
   const candidates = [
+    process.env.OPEN_MEMEX_CONFIG,
     process.env.MY_O_MEMORY_CONFIG,
     path.join(os.homedir(), ".config", "opencode", "open-memex.jsonc"),
     path.join(os.homedir(), ".config", "opencode", "open-memex.json"),

package/src/doctor.ts

@@ -8,7 +8,7 @@ import path from "node:path";
 import { spawn, execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { loadConfig, configSource, DEFAULT_CONFIG } from "./config.ts";
-import { paths } from "./paths.ts";
+import { paths, homeOverride } from "./paths.ts";
 import { resolveCwdScope } from "./scope.ts";
 import { db, backendName } from "./store/db.ts";
 import { LEGACY_PACKAGE_NAME, opencodeGlobalConfigPath, userMcpConfigPath } from "./init.ts";
@@ -66,7 +66,14 @@ function storageCheck(): Check {
   try {
     const p = paths();
     fs.accessSync(p.memories, fs.constants.W_OK);
-    return { name: "storage", ok: true, detail: `${p.root} (writable)` };
+    // D62: when the root came from the legacy env var, say so (still ok —
+    // the fallback is supported, doctor just names the current one).
+    const via = homeOverride()?.via;
+    const note =
+      via === "MY_O_MEMORY_HOME"
+        ? " (via legacy MY_O_MEMORY_HOME — OPEN_MEMEX_HOME is the current name)"
+        : "";
+    return { name: "storage", ok: true, detail: `${p.root} (writable)${note}` };
   } catch (err) {
     return { name: "storage", ok: false, detail: String(err) };
   }
@@ -579,10 +586,12 @@ export async function runDoctor(): Promise<boolean> {
 function legacyCheck(): Check {
   const name = "legacy my-o-memory";
   const found: string[] = [];
-  const envHome = process.env.MY_O_MEMORY_HOME;
+  // D62: the override may arrive via either env var name; check the value
+  // in effect, not just the legacy one.
+  const envHome = homeOverride()?.dir;
   if (envHome && envHome.includes(LEGACY_PACKAGE_NAME))
     found.push(
-      `MY_O_MEMORY_HOME points at a pre-rename dir (${envHome}) — unset it, then merge old data with \`open-memex migrate --to-v2\``,
+      `memory home points at a pre-rename dir (${envHome}) — unset it, then merge old data with \`open-memex migrate --to-v2\``,
     );
   const root = paths().root;
   const legacyDir = path.join(path.dirname(root), LEGACY_PACKAGE_NAME);

package/src/paths.ts

@@ -3,8 +3,23 @@ import fs from "node:fs";
 import os from "node:os";
 import { execFileSync } from "node:child_process";
 
+/**
+ * D62: the data-root override env var. `OPEN_MEMEX_HOME` is the current
+ * name; `MY_O_MEMORY_HOME` (pre-rename package name) is still honored as a
+ * fallback so existing setups and scripts keep working. New name wins
+ * when both are set.
+ */
+export function homeOverride(): { dir: string; via: "OPEN_MEMEX_HOME" | "MY_O_MEMORY_HOME" } | null {
+  if (process.env.OPEN_MEMEX_HOME)
+    return { dir: path.resolve(process.env.OPEN_MEMEX_HOME), via: "OPEN_MEMEX_HOME" };
+  if (process.env.MY_O_MEMORY_HOME)
+    return { dir: path.resolve(process.env.MY_O_MEMORY_HOME), via: "MY_O_MEMORY_HOME" };
+  return null;
+}
+
 function dataRoot(): string {
-  if (process.env.MY_O_MEMORY_HOME) return path.resolve(process.env.MY_O_MEMORY_HOME);
+  const override = homeOverride();
+  if (override) return override.dir;
   if (process.platform === "win32") {
     const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
     return path.join(appData, "open-memex");