@ghilteras/opencode-agent-memory 0.4.0 → 0.4.2

package/README.md

@@ -1,13 +1,13 @@
 # opencode-agent-memory
 
-> **Fork notice**: This is the maintained fork `@ghilteras/opencode-agent-memory` v0.4.0 of
+> **Fork notice**: This is the maintained fork `@ghilteras/opencode-agent-memory` v0.4.2 of
 > [opencode-agent-memory](https://github.com/joshuadavidthomas/opencode-agent-memory)
-> (joshuadavidthomas, MIT). This release adopts the "proper timestamps without cache
+> (joshuadavidthomas, MIT). v0.4.2 adds a title-anchor floor so title queries are not diluted by long bodies. This release adopts the "proper timestamps without cache
 > busting" design (per-block `modified_at` frontmatter, remove the volatile
 > `memory_metadata` block, append memory XML at the end of the system prompt) derived
 > from the Annakan/draxxris fork plan. Upstream PR #20 (freeze metadata timestamps) is
 > superseded by the stronger per-block design and remains open upstream. v0.4.0 swaps
-> the embedding model to a multilingual one and adds a versioned embedding format.
+> the embedding model to a multilingual one and adds a versioned embedding format. v0.4.1 makes journal search fast (in-memory per-store index, embedding-model warmup at init) and fixes the js-yaml import for ESM runtimes.
 
 [Letta](https://letta.com)-style editable [memory blocks](https://docs.letta.com/guides/agents/memory-blocks/) for [OpenCode](https://opencode.ai).
 
@@ -37,7 +37,7 @@ Add to your OpenCode config (`~/.config/opencode/opencode.json`):
 
 ```json
 {
-  "plugin": ["opencode-agent-memory"]
+  "plugin": ["@ghilteras/opencode-agent-memory"]
 }
 ```
 
@@ -47,7 +47,7 @@ Optionally, pin to a specific version for stability:
 
 ```json
 {
-  "plugin": ["opencode-agent-memory@0.2.0"]
+  "plugin": ["@ghilteras/opencode-agent-memory@0.4.1"]
 }
 ```
 
@@ -58,7 +58,7 @@ OpenCode fetches unpinned plugins from npm on each startup; pinned versions are
 If you want to customize or contribute:
 
 ```bash
-git clone https://github.com/joshuadavidthomas/opencode-agent-memory ~/.config/opencode/opencode-agent-memory
+git clone https://github.com/Ghilteras/opencode-agent-memory ~/.config/opencode/opencode-agent-memory
 mkdir -p ~/.config/opencode/plugin
 ln -sf ~/.config/opencode/opencode-agent-memory/src/plugin.ts ~/.config/opencode/plugin/memory.ts
 ```
@@ -91,6 +91,8 @@ Journal entries are append-only markdown files with YAML frontmatter, stored in
 
 Embedding files (`.embedding`, written alongside each entry) use a versioned format (`{ v: 2, model, dimension, vector }`) so that stale or mismatched embeddings are detected: if the stored dimension doesn't match the current model, the entry falls back to text matching instead of failing the search. Legacy bare-array embeddings from v0.3.x remain readable.
 
+**Search performance (v0.4.1–v0.4.2)**: `journal_search` keeps an in-memory index per store instance. Entries are re-read only when their file changed — fingerprinted on both the entry `.md` and its `.embedding` sidecar (mtime + size), so regenerating or deleting a sidecar is picked up on the next search without a restart. The embedding model is warmed up in the background at plugin init when the journal is enabled (respecting `cacheDir`), so the first search after a restart doesn't pay the cold model-load cost. Since v0.4.2, a query whose text matches an entry's title (in either direction, case-insensitive) is guaranteed a high score floor (0.75), so title-based pointers remain retrievable even for entries with long bodies.
+
 ### cacheDir Configuration
 
 By default the transformers.js model cache lives in the default location (`~/.cache/huggingface`). You can relocate it by setting `cacheDir` at the top level of `~/.config/opencode/agent-memory.json`:
@@ -173,7 +175,7 @@ Also worth exploring: [private-journal-mcp](https://github.com/obra/private-jour
 Contributions are welcome! Here's how to set up for development:
 
 ```bash
-git clone https://github.com/joshuadavidthomas/opencode-agent-memory
+git clone https://github.com/Ghilteras/opencode-agent-memory
 cd opencode-agent-memory
 bun install
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghilteras/opencode-agent-memory",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Letta-style editable memory blocks + journal for OpenCode (maintained fork of opencode-agent-memory).",
   "author": "Angelo Pantano <ghilteras@protonmail.com>",
   "license": "MIT",

package/src/embeddings.ts

@@ -25,6 +25,10 @@ async function getPipeline(cacheDir?: string) {
   return pipelinePromise;
 }
 
+export async function warmupEmbedder(cacheDir?: string): Promise<void> {
+  await getPipeline(cacheDir);
+}
+
 export async function generateEmbedding(
   text: string,
   cacheDir?: string,

package/src/frontmatter.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 
-import yaml from "js-yaml";
+import * as yaml from "js-yaml";
 
 export function splitFrontmatter(text: string): {
   frontmatterText: string | undefined;

package/src/journal.test.ts

@@ -392,6 +392,27 @@ describe("journal store", () => {
     expect(result.total).toBeGreaterThan(0);
   });
 
+  test("title query surfaces long-body entry despite diluted embedding", async () => {
+    tmpDir = await mkTmpDir();
+    const store = createJournalStore(tmpDir);
+    const entry = await store.write({
+      title: "Agent-memory release delivery channel",
+      body: "Unrelated topics include coastal erosion, orbital mechanics, ceramic glazing, " +
+        "database indexing, ancient trade routes, orchard irrigation, keyboard switches, " +
+        "bird migration, public transit planning, and archival paper chemistry. These notes " +
+        "continue across varied subjects so the long body dilutes its mean-pooled embedding. " +
+        "Further unrelated details cover weather instruments, typography, fermentation, " +
+        "geology, woodworking, astronomy, logistics, and museum conservation. The entry is " +
+        "deliberately verbose and semantically unrelated to a fresh exact-title query, while " +
+        "its title remains the searchable anchor for this regression case.",
+    });
+
+    // The deterministic mock embeddings produce an unrelated query vector here;
+    // the title-anchor floor guarantees presence regardless of cosine score.
+    const result = await store.search({ text: "Agent-memory release delivery channel" });
+    expect(result.entries.some((candidate) => candidate.id === entry.id)).toBe(true);
+  });
+
   test("search skips stale-dimension embedding and falls back to text match", async () => {
     tmpDir = await mkTmpDir();
     const store = createJournalStore(tmpDir);
@@ -401,6 +422,9 @@ describe("journal store", () => {
       body: "unique-stale-dim-content",
     });
 
+    // First search: caches the entry with the correct mock embedding.
+    await store.search({ text: "unique-stale-dim-content" });
+
     // Simulate a v2 embedding with a WRONG dimension (e.g. from a 768d model).
     // Search must not throw: it should skip the embedding and fall back to
     // text matching for this entry.
@@ -424,6 +448,64 @@ describe("journal store", () => {
     // No throw above is the assertion: mismatched dimension degrades to text.
   });
 
+  test("sidecar rewrite after cache warm is picked up by second search", async () => {
+    tmpDir = await mkTmpDir();
+    const store = createJournalStore(tmpDir);
+
+    const entry = await store.write({
+      title: "Sidecar invalidation",
+      body: "unique-sidecar-invalidation-content",
+    });
+
+    // First search: caches the entry + correct sidecar fingerprint.
+    const r1 = await store.search({ text: "unique-sidecar-invalidation-content" });
+    expect(r1.entries.some((e) => e.title === "Sidecar invalidation")).toBe(true);
+
+    // Rewrite the sidecar with a wrong-dimension embedding (simulating
+    // sidecar regeneration without touching the .md).
+    const embeddingFile = entry.filePath.replace(/\.md$/, ".embedding");
+    await fs.writeFile(
+      embeddingFile,
+      JSON.stringify({
+        v: 2,
+        model: "some-768d-model",
+        dimension: 768,
+        vector: Array.from({ length: 768 }, () => 0.1),
+      }),
+      "utf-8",
+    );
+
+    // Second search must invalidate the cache (sidecar mtime changed) and
+    // pick up the stale-dimension embedding, falling back to text match.
+    const r2 = await store.search({ text: "unique-sidecar-invalidation-content" });
+    expect(r2.entries.some((e) => e.title === "Sidecar invalidation")).toBe(true);
+  });
+
+  test("sidecar deleted between searches falls back to text match", async () => {
+    tmpDir = await mkTmpDir();
+    const store = createJournalStore(tmpDir);
+
+    const entry = await store.write({
+      title: "Sidecar deleted entry",
+      body: "unique-sidecar-deleted-content",
+    });
+
+    // First search: caches the entry + sidecar fingerprint.
+    const r1 = await store.search({ text: "unique-sidecar-deleted-content" });
+    expect(r1.entries.some((e) => e.title === "Sidecar deleted entry")).toBe(true);
+
+    // Delete the sidecar file.
+    const embeddingFile = entry.filePath.replace(/\.md$/, ".embedding");
+    await fs.unlink(embeddingFile);
+
+    // Second search: cache miss (sidecar gone), falls back to text match
+    // (score 0.5) rather than using the stale cached embedding.
+    const r2 = await store.search({ text: "unique-sidecar-deleted-content" });
+    const found = r2.entries.find((e) => e.title === "Sidecar deleted entry");
+    expect(found).toBeDefined();
+    // Score is 0.5 (text fallback), not a cosine score
+  });
+
   test("search skips corrupt v2 embedding (empty vector) without throwing", async () => {
     tmpDir = await mkTmpDir();
     const store = createJournalStore(tmpDir);

package/src/journal.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import yaml from "js-yaml";
+import * as yaml from "js-yaml";
 import { z } from "zod";
 
 import { cosineSimilarity, EMBEDDING_DIMENSION, embeddingModelName, generateEmbedding } from "./embeddings";
@@ -86,6 +86,13 @@ function embeddingPath(entryPath: string): string {
   return entryPath.replace(/\.md$/, ".embedding");
 }
 
+function titleMatches(queryText: string, title: string): boolean {
+  const q = queryText.trim().toLowerCase();
+  if (!q) return false;
+  const t = title.trim().toLowerCase();
+  return t.includes(q) || q.includes(t);
+}
+
 async function readEntryFile(filePath: string): Promise<JournalEntry> {
   const raw = await fs.readFile(filePath, "utf-8");
   const { frontmatterText, body } = splitFrontmatter(raw);
@@ -122,6 +129,15 @@ type ParsedEmbedding =
   | { vector: number[]; model: string; dimension: number }
   | undefined;
 
+type CachedEntry = {
+  entryMtimeMs: number;
+  entrySize: number;
+  embMtimeMs: number;
+  embSize: number;
+  entry: JournalEntry;
+  embedding: ParsedEmbedding;
+};
+
 async function loadEmbedding(entryPath: string): Promise<ParsedEmbedding> {
   const ePath = embeddingPath(entryPath);
   try {
@@ -197,6 +213,11 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
     "journal",
   );
 
+  // Per-store cache: each store instance owns its entries, so stores with
+  // different (including nested or ephemeral) journal directories never
+  // interfere and no foreign keys can accumulate.
+  const entryCache = new Map<string, CachedEntry>();
+
   return {
     async write(entry) {
       await fs.mkdir(journalDir, { recursive: true });
@@ -288,6 +309,12 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
         return { entries: [], total: 0, allTags: [] };
       }
 
+      // Prune cache entries for files that no longer exist
+      const alive = new Set(files.map((f) => path.join(journalDir, f)));
+      for (const key of entryCache.keys()) {
+        if (!alive.has(key)) entryCache.delete(key);
+      }
+
       // If a text query is provided, try semantic search first
       let queryEmbedding: number[] | undefined;
       if (query.text) {
@@ -301,14 +328,46 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
       // Collect all tags across every entry (before filtering)
       const tagSet = new Set<string>();
 
-      for (const file of files) {
+      const indexed = await Promise.all(files.map(async (file) => {
         const filePath = path.join(journalDir, file);
-        let entry: JournalEntry;
         try {
-          entry = await readEntryFile(filePath);
+          const ePath = embeddingPath(filePath);
+          const [entryStat, embStat] = await Promise.all([
+            fs.stat(filePath),
+            fs.stat(ePath).catch(() => ({ mtimeMs: -1, size: -1 } as const)),
+          ]);
+          const cached = entryCache.get(filePath);
+          if (
+            cached &&
+            cached.entryMtimeMs === entryStat.mtimeMs &&
+            cached.entrySize === entryStat.size &&
+            cached.embMtimeMs === embStat.mtimeMs &&
+            cached.embSize === embStat.size
+          ) {
+            return cached;
+          }
+          const [entry, embedding] = await Promise.all([
+            readEntryFile(filePath),
+            loadEmbedding(filePath),
+          ]);
+          const value: CachedEntry = {
+            entryMtimeMs: entryStat.mtimeMs,
+            entrySize: entryStat.size,
+            embMtimeMs: embStat.mtimeMs,
+            embSize: embStat.size,
+            entry,
+            embedding,
+          };
+          entryCache.set(filePath, value);
+          return value;
         } catch {
-          continue;
+          return undefined;
         }
+      }));
+
+      for (const cached of indexed) {
+        if (!cached) continue;
+        const { entry } = cached;
 
         // Collect tags before applying filters
         for (const tag of entry.tags) {
@@ -333,7 +392,7 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
         if (query.text) {
           if (queryEmbedding) {
             // Semantic search
-            const storedEmbedding = await loadEmbedding(filePath);
+            const storedEmbedding = cached.embedding;
             if (storedEmbedding) {
               // Hard gate: dimension must match, or the embedding is stale
               // (different model) and cannot be compared with cosine.
@@ -360,6 +419,13 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
             score = haystack.includes(query.text.toLowerCase()) ? 1 : 0;
           }
 
+          // Title-anchor floor: a query that matches the entry title (either
+          // direction, case-insensitive) must not be diluted below the top
+          // ranks by long-body mean pooling (see 20260905-171239-533).
+          if (titleMatches(query.text, entry.title)) {
+            score = Math.max(score, 0.75);
+          }
+
           if (score <= 0) continue;
         } else {
           // No text query - chronological order (score by recency)

package/src/memory.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import yaml from "js-yaml";
+import * as yaml from "js-yaml";
 import { z } from "zod";
 
 import { atomicWriteFile, buildFrontmatterDocument, splitFrontmatter } from "./frontmatter";

package/src/plugin.ts

@@ -16,6 +16,7 @@ import {
   MemorySet,
 } from "./tools";
 import type { JournalContext } from "./tools";
+import { warmupEmbedder } from "./embeddings";
 
 export const MemoryPlugin: Plugin = async ({ directory }) => {
   const store = createMemoryStore(directory);
@@ -37,6 +38,9 @@ export const MemoryPlugin: Plugin = async ({ directory }) => {
 
   if (journalEnabled) {
     const journalStore = createJournalStore(undefined, config.cacheDir);
+    // Warmup the embedder in the background; pass configured cacheDir so the
+    // first-init-wins singleton caches to the correct directory.
+    void warmupEmbedder(config.cacheDir).catch(() => {});
     journalTools = {
       journal_write: JournalWrite(journalStore, journalCtx),
       journal_read: JournalRead(journalStore),