open-memex 0.1.0 → 0.2.0-alpha

package/src/store/v2migrate.ts

@@ -0,0 +1,190 @@
+import fs from "node:fs";
+import path from "node:path";
+import { paths } from "../paths.ts";
+import {
+  parseRawFrontmatter,
+  normalizeFrontmatter,
+  isTaxonomyType,
+  serialize,
+  type Frontmatter,
+} from "./markdown.ts";
+
+/**
+ * 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: string): boolean {
+  return V2_MARKER.test(raw);
+}
+
+export interface ConversionPlan {
+  fm: Frontmatter;
+  body: string;
+  fromPath: string;
+  toPath: string;
+  changes: string[];
+}
+
+/**
+ * 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: string,
+  memoriesRoot: string,
+): ConversionPlan | null {
+  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: string[] = [];
+
+  // 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 };
+}
+
+export interface MigrateV2Result {
+  scanned: number;
+  converted: number;
+  skippedV2: number;
+  plans: ConversionPlan[];
+  legacyBackup: string | null;
+}
+
+/**
+ * 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: boolean): string | null {
+  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: { dryRun: boolean }): MigrateV2Result {
+  const { memories: memoriesRoot } = paths();
+  const result: MigrateV2Result = {
+    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/src/tools/memory.ts

@@ -1,41 +1,37 @@
 import { tool } from "@opencode-ai/plugin/tool";
 import type { Scope } from "../scope.ts";
 import type { MyOMemoryConfig } from "../config.ts";
-import { USER_SCOPE } from "../scope.ts";
+import { PERSONAL_SCOPE } from "../scope.ts";
 import { search, list } from "../retrieve/search.ts";
 import {
   writeMemoryFile,
   deleteMemoryFile,
   readMemoryFile,
   ulid,
+  msToRfc3339,
+  MEMORY_TYPE_TAXONOMY,
   type Frontmatter,
 } from "../store/markdown.ts";
 import { upsertFromFile, deleteFromIndex } from "../store/sync.ts";
+import { findDuplicates, supersede } from "../store/lifecycle.ts";
 import { db } from "../store/db.ts";
 import { redact } from "../redact.ts";
 
 const z = tool.schema;
 
-const MEMORY_TYPES = [
-  "note",
-  "preference",
-  "project-config",
-  "architecture",
-  "error-solution",
-  "learned-pattern",
-  "conversation",
-] as const;
+/** v2 content-kind taxonomy (V2-DESIGN §3.1). */
+const MEMORY_TYPES = MEMORY_TYPE_TAXONOMY;
 
 export function makeTools(getScope: () => Scope, cfg: MyOMemoryConfig) {
   const scopeArg = z
-    .enum(["project", "user"])
+    .enum(["project", "personal", "user"])
     .optional()
     .describe(
-      "Memory scope. `project` = tied to this repo. `user` = global across all your projects. Default: project.",
+      "Memory scope. `project` = tied to this repo. `personal` = global across all your projects. `user` is a deprecated alias of `personal`. Default: project.",
     );
 
-  function resolveScope(kind?: "project" | "user"): Scope {
-    return kind === "user" ? USER_SCOPE : getScope();
+  function resolveScope(kind?: "project" | "personal" | "user"): Scope {
+    return kind === "personal" || kind === "user" ? PERSONAL_SCOPE : getScope();
   }
 
   const memory_add = tool({
@@ -62,38 +58,58 @@ export function makeTools(getScope: () => Scope, cfg: MyOMemoryConfig) {
         };
       }
       const s = resolveScope(args.scope);
-      const now = Date.now();
+      // 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 rfc = msToRfc3339(Date.now());
       const fm: Frontmatter = {
         id: ulid(),
+        schema_version: 2,
         scope_key: s.key,
-        scope_kind: s.kind,
+        scope: s.kind === "project" ? "project" : "personal",
+        visibility: s.kind === "project" ? "internal" : "private",
         project_name: s.projectName,
-        type: args.type ?? "note",
+        type: args.type ?? "fact",
+        role: "knowledge",
+        importance: "normal",
+        status: "active",
         tags: args.tags ?? [],
         source: "tool",
-        created_at: now,
-        updated_at: now,
+        created_at: rfc,
+        updated_at: rfc,
+        supersedes: null,
+        superseded_by: null,
       };
       const { filePath } = writeMemoryFile(fm, redacted);
       const mf = readMemoryFile(filePath);
       if (mf) upsertFromFile(mf);
+      let output = `Saved to ${s.key} as ${fm.type}. id=${fm.id}`;
+      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: `Saved to ${s.key} as ${fm.type}. id=${fm.id}`,
+        output,
       };
     },
   });
 
   const memory_search = tool({
     description:
-      "Search persistent memory by keyword (BM25 full-text). Returns matching memories from the current project and/or user scope. Use before asking the user something they may have told you before.",
+      "Search persistent memory by keyword (BM25 full-text). Returns matching memories from the current project and/or personal scope. Use before asking the user something they may have told you before.",
     args: {
       query: z
         .string()
         .min(1)
         .describe("Free-text query. File paths, error strings, identifiers work well."),
       scope: z
-        .enum(["project", "user", "both"])
+        .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."),
@@ -102,11 +118,11 @@ export function makeTools(getScope: () => Scope, cfg: MyOMemoryConfig) {
     async execute(args) {
       const project = getScope();
       const scopeKeys =
-        args.scope === "user"
-          ? [USER_SCOPE.key]
+        args.scope === "personal" || args.scope === "user"
+          ? [PERSONAL_SCOPE.key]
           : args.scope === "project"
             ? [project.key]
-            : [project.key, USER_SCOPE.key];
+            : [project.key, PERSONAL_SCOPE.key];
       const hits = search(args.query, {
         scopeKeys,
         limit: args.limit,
@@ -120,7 +136,7 @@ export function makeTools(getScope: () => Scope, cfg: MyOMemoryConfig) {
       }
       const lines = hits.map(
         (h) =>
-          `- [${h.scope_key === USER_SCOPE.key ? "user" : "project"}/${h.type}] id=${h.id}\n  ${h.snippet.replace(/\s+/g, " ").trim()}`,
+          `- [${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)`,
@@ -152,6 +168,51 @@ export function makeTools(getScope: () => Scope, cfg: MyOMemoryConfig) {
     },
   });
 
+  const memory_supersede = tool({
+    description:
+      "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.",
+    args: {
+      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_TYPES)
+        .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."),
+    },
+    async execute(args) {
+      const { content: redacted, hadSecret, matchedPattern } = redact(
+        args.content,
+        cfg.redactPatterns,
+      );
+      if (hadSecret) {
+        return {
+          title: "memory: rejected (secret detected)",
+          output: `Refused to save: content matched a secret pattern (${matchedPattern}). Wrap the sensitive part in <private>...</private> tags or paraphrase, then try again.`,
+        };
+      }
+      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).`,
+        };
+      } catch (e) {
+        return {
+          title: "memory: supersede failed",
+          output: (e as Error).message,
+        };
+      }
+    },
+  });
+
   const memory_forget = tool({
     description: "Delete a memory by id. Use when the user asks to forget something.",
     args: {
@@ -170,5 +231,5 @@ export function makeTools(getScope: () => Scope, cfg: MyOMemoryConfig) {
     },
   });
 
-  return { memory_add, memory_search, memory_list, memory_forget };
+  return { memory_add, memory_search, memory_list, memory_forget, memory_supersede };
 }