@ghilteras/opencode-agent-memory 1.2.0 → 2.0.0

package/README.md

@@ -6,7 +6,7 @@
 >
 > Originally created by Joshua David Thomas and licensed under the MIT license. Attribution preserved below; see License section.
 
-A journal-only memory plugin for [OpenCode](https://opencode.ai): an append-only, tagged journal with local semantic search.
+A journal-only memory plugin for [OpenCode](https://opencode.ai): an append-only, tagged journal with local lexical search.
 
 ## Experimental
 
@@ -17,7 +17,7 @@ Think of it as a searchable sidecar to `AGENTS.md`. OpenCode supports [rules](ht
 ## Features
 
 - **Append-only journal** - Entries survive across sessions and context compaction
-- **Local semantic search** - Find entries by meaning, not just keywords
+- **Local lexical search** - Find candidate entries by matching query words in titles and bodies
 - **Metadata on every entry** - Project, model, provider, agent, session, timestamp, tags
 - **Guidance in tool descriptions** - Journal usage guidance lives in the descriptions of the journal tools, so an agent sees it only when it is allowed to call them
 - **No data leaves the machine** - Embeddings run locally
@@ -32,7 +32,7 @@ Add to your OpenCode config (`~/.config/opencode/opencode.json`):
 
 ```json
 {
-  "plugins": ["@ghilteras/opencode-agent-memory@1.1.0"]
+  "plugins": ["@ghilteras/opencode-agent-memory@2.0.0"]
 }
 ```
 
@@ -63,7 +63,7 @@ The agent gets 3 tools:
 | Tool | Description |
 |------|-------------|
 | `journal_write` | Write a new append-only entry (title, body, optional tags) |
-| `journal_search` | Search entries semantically, filter by project or tags, with pagination |
+| `journal_search` | Find lexical candidates by matching query words in titles and bodies; filter by project or tags, with pagination |
 | `journal_read` | Read a specific journal entry by ID |
 
 ### Entry format
@@ -85,9 +85,9 @@ tags: [plugin, wiring]
 Body text...
 ```
 
-### Semantic search
+### Text search
 
-Search uses local embeddings ([paraphrase-multilingual-MiniLM-L12-v2](https://huggingface.co/Xenova/paraphrase-multilingual-MiniLM-L12-v2), 384d, multilingual EN/IT) - no data leaves your machine. An `.embedding` sidecar is written next to each entry in a versioned format (`{ v: 2, model, dimension, vector }`). The search gate is a **dimension** check: an entry whose recorded `dimension` differs from the plugin's expected dimension is not cosine-compared - it falls back to text matching instead of failing the search. Legacy bare-array embeddings from v0.3.x remain readable.
+Text search runs one MiniSearch BM25+ pass over title and body. Query terms are OR-matched, with native score order and a deterministic tie-break by creation time and ID. This is keyword matching, not a claim of semantic relevance: results are candidates for the agent to inspect. Matching works across languages by matching literal words, not by meaning. When a query has no tokenizable terms (for example, `!!!`), search falls back to case-insensitive exact-substring matching over title and body. The retained index is reused while the ordered candidate-entry ID list is unchanged, avoiding repeated index construction. Embedding sidecars are still written in the versioned `{ v: 2, model, dimension, vector }` format for compatibility, but search does not read them.
 
 ### Suggested tags
 
@@ -129,6 +129,12 @@ Two behaviour changes:
 - **The journal tools are registered by default.** Previously you had to opt in through `agent-memory.json`; now an absent config means the tools are on, and you turn them off with `"enabled": false`.
 - **Storage is unchanged.** Existing entries under `~/.config/opencode/journal/` and their `.embedding` sidecars stay readable; nothing is migrated or rewritten.
 
+## Upgrading to lexical candidate search
+
+- Text search now ranks entries with lexical OR matching: a candidate may match any query term in its title or body.
+- Results are candidates, not relevance claims. `Found N` reports the candidate count before pagination and will usually be large.
+- A punctuation-only query falls back to case-insensitive substring matching over title and body.
+
 ## Upgrading from 0.4.x
 
 Memory blocks and their tools (`memory_list`, `memory_set`, `memory_replace`) are **removed**. Blocks are no longer read, written, or injected into the system prompt; the plugin ships only the journal.
@@ -140,7 +146,7 @@ Existing `~/.config/opencode/memory/` and `.opencode/memory/` directories are **
 - **Requires OpenCode v2.** This release uses the OpenCode v2 plugin API and does not run on v1.
 - **Restart after config changes.** Plugin config changes require a full OpenCode restart to take effect; editing the config file alone is not sufficient.
 - **Journal is on by default.** Turn it off with `"enabled": false`; an explicit disable is silent, while a config that exists but is unreadable, malformed, or schema-invalid logs a warning and registers no tools (fail-closed).
-- **Local embeddings, no data leaves the machine.** Semantic search uses a locally cached transformers.js model; no external API calls are made for search or embedding.
+- **Embedding sidecars remain compatible.** They are written locally for the existing format contract, diagnostics, and future consumers; text search is lexical and does not read embeddings.
 - **Known limitation (since 0.5.1): guidance-in-descriptions depends on an unverified premise.** 0.5.1 moved journal guidance from the injected system-prompt note into the three journal tool descriptions, so only agents allowed to call those tools should see it. That relies on opencode omitting a permission-denied tool from the definitions sent to the model. This is **unverified**: a `tool.definition` probe on the isolated instance fires before permission filtering, so it cannot confirm what the model actually receives. If the premise does not hold, an agent denied `journal_*` may still read the description text; `deny` still blocks execution, so there is no capability escalation and no data disclosure — the blast radius is the three tools' description strings.
 
 ## Inspiration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghilteras/opencode-agent-memory",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Journal-only memory plugin for OpenCode: tagged, searchable, append-only journal with semantic search.",
   "author": "Angelo Pantano <ghilteras@protonmail.com>",
   "license": "MIT",
@@ -27,6 +27,7 @@
     "@huggingface/transformers": "^3.8.1",
     "@opencode/plugin": "^2.0.18",
     "js-yaml": "^4.1.0",
+    "minisearch": "^7.2.0",
     "zod": "^4.1.13"
   },
   "overrides": {

package/src/journal.test.ts

@@ -2,40 +2,31 @@ import { afterEach, beforeAll, describe, expect, mock, test } from "bun:test";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import * as realEmbeddings from "./embeddings";
+import NativeMiniSearch from "minisearch";
+
+let embeddingGenerationCalls = 0;
+let lexicalIndexConstructions = 0;
+
+class CountingMiniSearch extends (NativeMiniSearch as any) {
+  constructor(...args: any[]) {
+    super(...args);
+    lexicalIndexConstructions++;
+  }
+}
+
+mock.module("minisearch", () => ({ default: CountingMiniSearch }));
 
 // Mock the embeddings module to avoid downloading a real model in tests.
 // Spread the real module so every export not overridden here keeps its real
 // value regardless of test-file discovery order.
 mock.module("./embeddings", () => ({
   ...realEmbeddings,
-  generateEmbedding: async (text: string) => {
-    // Deterministic fake embedding based on text content
-    const hash = Array.from(text).reduce(
-      (acc, c) => ((acc << 5) - acc + c.charCodeAt(0)) | 0,
-      0,
-    );
-    return Array.from({ length: 8 }, (_, i) => Math.sin(hash + i));
+  generateEmbedding: async () => {
+    embeddingGenerationCalls++;
+    return Array.from({ length: 8 }, (_, i) => i / 8);
   },
   EMBEDDING_DIMENSION: 8,
   embeddingModelName: () => "test-model",
-  cosineSimilarity: (a: number[], b: number[]) => {
-    if (a.length !== b.length)
-      throw new Error(
-        `Embedding dimension mismatch: ${a.length} vs ${b.length}`,
-      );
-    let dot = 0;
-    let normA = 0;
-    let normB = 0;
-    for (let i = 0; i < a.length; i++) {
-      const ai = a[i]!;
-      const bi = b[i]!;
-      dot += ai * bi;
-      normA += ai * ai;
-      normB += bi * bi;
-    }
-    const denom = Math.sqrt(normA) * Math.sqrt(normB);
-    return denom === 0 ? 0 : dot / denom;
-  },
 }));
 
 async function mkTmpDir(): Promise<string> {
@@ -143,6 +134,8 @@ describe("journal store", () => {
   let tmpDir: string;
 
   afterEach(async () => {
+    embeddingGenerationCalls = 0;
+    lexicalIndexConstructions = 0;
     if (tmpDir) {
       await fs.rm(tmpDir, { recursive: true, force: true });
     }
@@ -415,7 +408,7 @@ describe("journal store", () => {
     expect(result.allTags).toEqual(["debugging", "perf", "rust"]);
   });
 
-  test("search by text uses semantic matching", async () => {
+  test("search by text uses lexical OR matching", async () => {
     tmpDir = await mkTmpDir();
     const store = createJournalStore(tmpDir);
 
@@ -429,13 +422,11 @@ describe("journal store", () => {
       body: "Set up pytest with coverage reporting.",
     });
 
-    // With mock embeddings, text search falls through to semantic matching
-    const result = await store.search({ text: "Rust performance" });
-    // Should find at least the matching entry
-    expect(result.total).toBeGreaterThan(0);
+    const result = await store.search({ text: "Rust absentterm" });
+    expect(result.entries.map((entry) => entry.title)).toEqual(["Rust performance"]);
   });
 
-  test("title query surfaces long-body entry despite diluted embedding", async () => {
+  test("title query matches terms from the title", async () => {
     tmpDir = await mkTmpDir();
     const store = createJournalStore(tmpDir);
     const entry = await store.write({
@@ -443,192 +434,205 @@ describe("journal store", () => {
       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. " +
+        "continue across varied subjects in this deliberately long journal entry. " +
         "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 " +
+        "deliberately verbose and does not repeat the title terms in its body, 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 () => {
+  test("lexical matching finds a rare exact token", async () => {
     tmpDir = await mkTmpDir();
     const store = createJournalStore(tmpDir);
+    const entry = await store.write({ title: "Unrelated note", body: "The rarelexicaltoken appears here." });
+    const query = "rarelexicaltoken";
 
-    const entry = await store.write({
-      title: "Stale dims entry",
-      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.
-    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",
-    );
-
-    // Query whose embedding would collide with the stale one if cosine were
-    // attempted (dimension mismatch would throw inside cosineSimilarity).
-    const result = await store.search({ text: "unique-stale-dim-content" });
-    const titles = result.entries.map((e) => e.title);
-    expect(titles).toContain("Stale dims entry");
-    // No throw above is the assertion: mismatched dimension degrades to text.
+    const result = await store.search({ text: query });
+    expect(result.total).toBe(1);
+    expect(result.entries.map((e) => e.id)).toEqual([entry.id]);
   });
 
-  test("sidecar rewrite after cache warm is picked up by second search", async () => {
+  test("OR matching returns unique matches and stable pagination across identical calls", async () => {
     tmpDir = await mkTmpDir();
     const store = createJournalStore(tmpDir);
+    for (let i = 0; i < 4; i++) {
+      await store.write({ title: `Stable ${i}`, body: "sharedtoken searchable" });
+      await new Promise((r) => setTimeout(r, 5));
+    }
 
-    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);
+    const first = await store.search({ text: "sharedtoken", limit: 2 });
+    const second = await store.search({ text: "sharedtoken", limit: 2 });
+    expect(first.total).toBe(4);
+    expect(second.total).toBe(4);
+    expect(first.entries.map((e) => e.id)).toEqual(second.entries.map((e) => e.id));
+    const next = await store.search({ text: "sharedtoken", limit: 2, offset: 2 });
+    expect([...first.entries, ...next.entries].map((e) => e.id)).toHaveLength(4);
+    expect(new Set([...first.entries, ...next.entries].map((e) => e.id)).size).toBe(4);
   });
 
-  test("sidecar deleted between searches falls back to text match", async () => {
+  test("identical text searches reuse the lexical index snapshot", async () => {
     tmpDir = await mkTmpDir();
     const store = createJournalStore(tmpDir);
-
-    const entry = await store.write({
-      title: "Sidecar deleted entry",
-      body: "unique-sidecar-deleted-content",
-    });
-
-    // Warm the cache chronologically (loads and caches the sidecar
-    // fingerprint) without depending on a synthetic semantic score.
-    const r1 = await store.search({});
-    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
+    await store.write({ title: "Cache token", body: "repeated searchable material" });
+    const before = lexicalIndexConstructions;
+    await store.search({ text: "cache" });
+    expect(lexicalIndexConstructions).toBe(before + 1);
+    await store.search({ text: "cache" });
+    expect(lexicalIndexConstructions).toBe(before + 1);
   });
 
-  test("search skips corrupt v2 embedding (empty vector) without throwing", async () => {
+  test("adding an entry rebuilds the index and makes it searchable", async () => {
     tmpDir = await mkTmpDir();
     const store = createJournalStore(tmpDir);
+    await store.write({ title: "Before", body: "ordinary content" });
+    const before = lexicalIndexConstructions;
+    await store.search({ text: "newlyaddedtoken" });
+    await store.write({ title: "New entry", body: "newlyaddedtoken appears here" });
+    const result = await store.search({ text: "newlyaddedtoken" });
+    expect(lexicalIndexConstructions).toBe(before + 2);
+    expect(result.entries.map((entry) => entry.title)).toEqual(["New entry"]);
+  });
 
-    const entry = await store.write({
-      title: "Corrupt embedding entry",
-      body: "unique-corrupt-embedding-content",
-    });
-
-    // Simulate a corrupt-but-well-formed v2 embedding: dimension claims 384
-    // but the vector is empty. Search must NOT throw — it should skip the
-    // embedding and fall back to text matching for this entry.
-    const embeddingFile = entry.filePath.replace(/\.md$/, ".embedding");
-    await fs.writeFile(
-      embeddingFile,
-      JSON.stringify({ v: 2, model: "some-model", dimension: 8, vector: [] }),
-      "utf-8",
-    );
-
-    const result = await store.search({ text: "unique-corrupt-embedding-content" });
-    const titles = result.entries.map((e) => e.title);
-    expect(titles).toContain("Corrupt embedding entry");
-    // No throw above is the assertion: corrupt v2 embedding degrades to text.
+  test("editing entry bytes invalidates the index through the entry stat cache", async () => {
+    tmpDir = await mkTmpDir();
+    const store = createJournalStore(tmpDir);
+    const entry = await store.write({ title: "Editable", body: "old unique phrase" });
+    await store.search({ text: "old" });
+    const before = lexicalIndexConstructions;
+    const original = await fs.readFile(entry.filePath, "utf-8");
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    await fs.writeFile(entry.filePath, original.replace("old unique phrase", "replacementtoken with more bytes"));
+    const oldResult = await store.search({ text: "old" });
+    const newResult = await store.search({ text: "replacementtoken" });
+    expect(lexicalIndexConstructions).toBe(before + 1);
+    expect(oldResult.total).toBe(0);
+    expect(newResult.entries.map((candidate) => candidate.id)).toEqual([entry.id]);
+  });
+
+  test("a metadata filter changing membership rebuilds the lexical index", async () => {
+    tmpDir = await mkTmpDir();
+    const store = createJournalStore(tmpDir);
+    await store.write({ title: "Alpha", body: "sharedfiltertoken", project: "/proj/a" });
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    await store.write({ title: "Beta", body: "sharedfiltertoken", project: "/proj/b" });
+    const before = lexicalIndexConstructions;
+    const a = await store.search({ text: "sharedfiltertoken", project: "/proj/a" });
+    const b = await store.search({ text: "sharedfiltertoken", project: "/proj/b" });
+    expect(lexicalIndexConstructions).toBe(before + 2);
+    expect(a.entries.map((entry) => entry.title)).toEqual(["Alpha"]);
+    expect(b.entries.map((entry) => entry.title)).toEqual(["Beta"]);
+  });
+
+  test("interleaved searches with different filters retain their own index", async () => {
+    tmpDir = await mkTmpDir();
+    const store = createJournalStore(tmpDir);
+    const a = await store.write({ title: "Filtered A", body: "shared interleaved token", project: "/proj/a" });
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    const b = await store.write({ title: "Filtered B", body: "shared interleaved token", project: "/proj/b" });
+    const [resultA, resultB] = await Promise.all([
+      store.search({ text: "interleaved", project: "/proj/a" }),
+      store.search({ text: "interleaved", project: "/proj/b" }),
+    ]);
+    expect(resultA.entries.map((entry) => entry.id)).toEqual([a.id]);
+    expect(resultB.entries.map((entry) => entry.id)).toEqual([b.id]);
+    expect(resultA.total).toBe(1);
+    expect(resultB.total).toBe(1);
   });
 
-  test("search skips corrupt v2 embedding (missing vector) without throwing", async () => {
+  test("OR rankings and totals match an uncached MiniSearch fixture", async () => {
     tmpDir = await mkTmpDir();
     const store = createJournalStore(tmpDir);
+    const docs = [
+      ["Alpha systems", "blue green systems reliability"],
+      ["Green garden", "green plants bloom in spring"],
+      ["Blue ocean", "blue water and marine life"],
+      ["Reliable storage", "systems store durable records"],
+      ["Spring systems", "green systems launch in spring"],
+      ["Marine records", "ocean blue records and data"],
+      ["Durable garden", "plants grow with reliable soil"],
+      ["Data storage", "durable systems for data"],
+      ["Blooming ocean", "spring marine bloom"],
+      ["Record reliability", "reliable records stay durable"],
+    ];
+    const entries = [] as Awaited<ReturnType<typeof store.write>>[];
+    for (const [title, body] of docs) {
+      entries.push(await store.write({ title: title!, body: body! }));
+      await new Promise((resolve) => setTimeout(resolve, 2));
+    }
+    const queries = ["green systems", "blue records", "durable reliable", "spring ocean", "plants data"];
+    for (const text of queries) {
+      const uncached = new NativeMiniSearch({ fields: ["title", "body"], storeFields: ["id"] });
+      uncached.addAll(entries.map((entry) => ({ id: entry.id, title: entry.title, body: entry.body })));
+      const expected = uncached.search(text, { combineWith: "OR" })
+        .map((match) => ({ entry: entries.find((entry) => entry.id === String(match.id))!, score: match.score }))
+        .sort((a, b) => b.score - a.score || b.entry.created.getTime() - a.entry.created.getTime() || (a.entry.id < b.entry.id ? 1 : a.entry.id > b.entry.id ? -1 : 0));
+      const actual = await store.search({ text });
+      expect({ ids: actual.entries.map((entry) => entry.id), total: actual.total }).toEqual({
+        ids: expected.map(({ entry }) => entry.id),
+        total: expected.length,
+      });
+    }
+  });
 
-    const entry = await store.write({
-      title: "Missing vector entry",
-      body: "unique-missing-vector-content",
-    });
+  test("punctuation-only query falls back to case-insensitive title/body substring matches", async () => {
+    tmpDir = await mkTmpDir();
+    const store = createJournalStore(tmpDir);
+    const titleMatch = await store.write({ title: "!!!", body: "older" });
+    await new Promise((r) => setTimeout(r, 5));
+    const bodyMatch = await store.write({ title: "Other", body: "A marker !!! appears here." });
+    await new Promise((r) => setTimeout(r, 5));
+    await store.write({ title: "No match", body: "ordinary text" });
+    const result = await store.search({ text: "!!!" });
+    expect(result.total).toBe(2);
+    expect(result.entries.map((entry) => entry.id)).toEqual([bodyMatch.id, titleMatch.id]);
+  });
 
-    // v2 file that omits the vector field entirely. Search must not throw.
-    const embeddingFile = entry.filePath.replace(/\.md$/, ".embedding");
-    await fs.writeFile(
-      embeddingFile,
-      JSON.stringify({ v: 2, model: "some-model", dimension: 8 }),
-      "utf-8",
-    );
+  test("text search does not generate embeddings", async () => {
+    tmpDir = await mkTmpDir();
+    const store = createJournalStore(tmpDir);
+    const entry = await store.write({ title: "Keyword note", body: "the lexicalneedle is here" });
+    const callsBeforeSearch = embeddingGenerationCalls;
 
-    const result = await store.search({ text: "unique-missing-vector-content" });
-    const titles = result.entries.map((e) => e.title);
-    expect(titles).toContain("Missing vector entry");
+    const result = await store.search({ text: "lexicalneedle" });
+    expect(result.entries.map((candidate) => candidate.id)).toEqual([entry.id]);
+    expect(embeddingGenerationCalls - callsBeforeSearch).toBe(0);
   });
 
-  test("legacy bare-array embedding is still usable for semantic search", async () => {
+  test("text search matches query terms with OR and orders score, creation time, then id descending", async () => {
     tmpDir = await mkTmpDir();
     const store = createJournalStore(tmpDir);
+    const low = await store.write({ title: "Tie", body: "alpha" });
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    const highId = await store.write({ title: "Tie", body: "alpha" });
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    const newest = await store.write({ title: "Tie", body: "beta alpha" });
+    const tiedCreated = "2026-01-01T00:00:00.000Z";
+    for (const entry of [low, highId]) {
+      const original = await fs.readFile(entry.filePath, "utf-8");
+      await fs.writeFile(entry.filePath, original.replace(/^created: .+$/m, `created: '${tiedCreated}'`));
+    }
 
-    const entry = await store.write({
-      title: "Legacy embedding",
-      body: "legacy-vector-body",
-    });
+    const result = await store.search({ text: "alpha beta" });
+    expect(result.entries.map((entry) => entry.id)).toEqual([newest.id, highId.id, low.id]);
+    expect(result.total).toBe(3);
+  });
 
-    // Overwrite with a legacy v1 bare-array embedding (from all-MiniLM-L6-v2,
-    // which also produces 8-dim vectors under the test mock). Use the same
-    // mock formula as generateEmbedding so the cosine is positive and the
-    // entry is actually matched via semantic search.
-    const hash = Array.from("legacy-vector-body").reduce(
-      (acc, c) => ((acc << 5) - acc + c.charCodeAt(0)) | 0,
-      0,
-    );
-    const legacyVector = Array.from(
-      { length: 8 },
-      (_, i) => Math.sin(hash + i),
-    );
-    const embeddingFile = entry.filePath.replace(/\.md$/, ".embedding");
-    await fs.writeFile(
-      embeddingFile,
-      JSON.stringify(legacyVector),
-      "utf-8",
-    );
+  test("search without text remains chronological and does not generate embeddings", async () => {
+    tmpDir = await mkTmpDir();
+    const store = createJournalStore(tmpDir);
+    await store.write({ title: "Older", body: "first" });
+    await new Promise((r) => setTimeout(r, 5));
+    await store.write({ title: "Newer", body: "second" });
+    const callsBeforeSearch = embeddingGenerationCalls;
+    const indexesBeforeSearch = lexicalIndexConstructions;
 
-    // Legacy array must be treated as { vector, model: "unknown-legacy",
-    // dimension: length }; with a matching dimension it stays usable.
-    const result = await store.search({ text: "legacy-vector-body" });
-    const titles = result.entries.map((e) => e.title);
-    expect(titles).toContain("Legacy embedding");
+    const result = await store.search({});
+    expect(result.entries.map((entry) => entry.title)).toEqual(["Newer", "Older"]);
+    expect(embeddingGenerationCalls).toBe(callsBeforeSearch);
+    expect(lexicalIndexConstructions).toBe(indexesBeforeSearch);
   });
 });

package/src/journal.ts

@@ -3,9 +3,10 @@ import * as os from "node:os";
 import * as path from "node:path";
 
 import * as yaml from "js-yaml";
+import MiniSearch from "minisearch";
 import { z } from "zod";
 
-import { cosineSimilarity, EMBEDDING_DIMENSION, embeddingModelName, generateEmbedding } from "./embeddings";
+import { EMBEDDING_DIMENSION, embeddingModelName, generateEmbedding } from "./embeddings";
 import { atomicWriteFile, buildFrontmatterDocument, splitFrontmatter } from "./frontmatter";
 
 const TagSchema = z.looseObject({
@@ -139,11 +140,20 @@ 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);
+function hasLexicalTerms(text: string): boolean {
+  return /[\p{L}\p{N}]+/u.test(text);
+}
+
+function substringMatches(
+  entries: CachedEntry[],
+  query: string,
+): { entry: JournalEntry; score: number }[] {
+  const needle = query.toLowerCase();
+  return entries.flatMap(({ entry }) =>
+    `${entry.title}\n${entry.body}`.toLowerCase().includes(needle)
+      ? [{ entry, score: 0 }]
+      : [],
+  );
 }
 
 async function readEntryFile(filePath: string): Promise<JournalEntry> {
@@ -178,55 +188,12 @@ async function readEntryFile(filePath: string): Promise<JournalEntry> {
   };
 }
 
-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 {
-    const raw = await fs.readFile(ePath, "utf-8");
-    const parsed = JSON.parse(raw);
-    if (Array.isArray(parsed)) {
-      // Legacy v1 (bare array from all-MiniLM-L6-v2)
-      return {
-        vector: parsed as number[],
-        model: "unknown-legacy",
-        dimension: parsed.length,
-      };
-    }
-    if (parsed && typeof parsed === "object" && parsed.v === 2) {
-      const vector = Array.isArray(parsed.vector)
-        ? parsed.vector
-        : undefined;
-      if (
-        vector &&
-        vector.length === (parsed.dimension as number) &&
-        vector.length > 0
-      ) {
-        return {
-          vector,
-          model: parsed.model as string,
-          dimension: parsed.dimension as number,
-        };
-      }
-      return undefined;
-    }
-    return undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 const SAFE_ID = /^[a-zA-Z0-9_-]+$/;
 
 function validateId(id: string): string {
@@ -270,6 +237,7 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
   // different (including nested or ephemeral) journal directories never
   // interfere and no foreign keys can accumulate.
   const entryCache = new Map<string, CachedEntry>();
+  let lexicalIndexSnapshot: { ids: string[]; index: MiniSearch } | undefined;
 
   return {
     async write(entry) {
@@ -294,7 +262,7 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
       const content = buildFrontmatterDocument(frontmatter, entry.body);
       await atomicWriteFile(filePath, content);
 
-      // Generate and save embedding for semantic search
+      // Keep the sidecar for compatibility with doctor, the format contract, and future consumers; search does not read it.
       const searchableText = `${entry.title}\n${entry.body}`;
       try {
         const embedding = await generateEmbedding(searchableText, cacheDir);
@@ -345,8 +313,6 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
       const limit = Math.min(Math.max(query.limit ?? 20, 1), 50);
       const offset = Math.max(query.offset ?? 0, 0);
 
-      let entries: { entry: JournalEntry; score: number }[] = [];
-
       // Read all entry files
       let files: string[];
       try {
@@ -368,48 +334,28 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
         if (!alive.has(key)) entryCache.delete(key);
       }
 
-      // If a text query is provided, try semantic search first
-      let queryEmbedding: number[] | undefined;
-      if (query.text) {
-        try {
-          queryEmbedding = await generateEmbedding(query.text, cacheDir);
-        } catch {
-          // Fall back to text search if embedding fails
-        }
-      }
-
       // Collect all tags across every entry (before filtering)
       const tagSet = new Set<string>();
+      let entryCacheChanged = false;
 
       const indexed = await Promise.all(files.map(async (file) => {
         const filePath = path.join(journalDir, file);
         try {
-          const ePath = embeddingPath(filePath);
-          const [entryStat, embStat] = await Promise.all([
-            fs.stat(filePath),
-            fs.stat(ePath).catch(() => ({ mtimeMs: -1, size: -1 } as const)),
-          ]);
+          const entryStat = await fs.stat(filePath);
           const cached = entryCache.get(filePath);
           if (
             cached &&
             cached.entryMtimeMs === entryStat.mtimeMs &&
-            cached.entrySize === entryStat.size &&
-            cached.embMtimeMs === embStat.mtimeMs &&
-            cached.embSize === embStat.size
+            cached.entrySize === entryStat.size
           ) {
             return cached;
           }
-          const [entry, embedding] = await Promise.all([
-            readEntryFile(filePath),
-            loadEmbedding(filePath),
-          ]);
+          const entry = await readEntryFile(filePath);
+          entryCacheChanged = true;
           const value: CachedEntry = {
             entryMtimeMs: entryStat.mtimeMs,
             entrySize: entryStat.size,
-            embMtimeMs: embStat.mtimeMs,
-            embSize: embStat.size,
             entry,
-            embedding,
           };
           entryCache.set(filePath, value);
           return value;
@@ -418,6 +364,7 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
         }
       }));
 
+      const filtered: CachedEntry[] = [];
       for (const cached of indexed) {
         if (!cached) continue;
         const { entry } = cached;
@@ -439,65 +386,62 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
           if (!allTagsMatch) continue;
         }
 
-        // Score the entry
-        let score = 0;
-
-        if (query.text) {
-          if (queryEmbedding) {
-            // Semantic search
-            const storedEmbedding = cached.embedding;
-            if (storedEmbedding) {
-              // Hard gate: dimension must match, or the embedding is stale
-              // (different model) and cannot be compared with cosine.
-              // A mismatched/stale embedding degrades gracefully to text match.
-              if (storedEmbedding.dimension !== EMBEDDING_DIMENSION) {
-                const haystack =
-                  `${entry.title}\n${entry.body}`.toLowerCase();
-                score = haystack.includes(query.text.toLowerCase()) ? 0.5 : 0;
-              } else {
-                score = cosineSimilarity(
-                  queryEmbedding,
-                  storedEmbedding.vector,
-                );
-              }
-            } else {
-              // No embedding stored; fall back to text match
-              const haystack =
-                `${entry.title}\n${entry.body}`.toLowerCase();
-              score = haystack.includes(query.text.toLowerCase()) ? 0.5 : 0;
-            }
-          } else {
-            // Text search fallback
-            const haystack = `${entry.title}\n${entry.body}`.toLowerCase();
-            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);
-          }
+        filtered.push(cached);
+      }
 
-          if (score <= 0) continue;
+      let ranked: { entry: JournalEntry; score: number }[];
+      if (!query.text) {
+        ranked = filtered.map(({ entry }) => ({
+          entry,
+          score: entry.created.getTime(),
+        }));
+        ranked.sort((a, b) => b.score - a.score || (a.entry.id < b.entry.id ? 1 : a.entry.id > b.entry.id ? -1 : 0));
+      } else {
+        const ids = filtered.map(({ entry }) => entry.id);
+        const sameEntries = !entryCacheChanged && lexicalIndexSnapshot !== undefined &&
+          lexicalIndexSnapshot.ids.length === ids.length &&
+          ids.every((id, index) => lexicalIndexSnapshot!.ids[index] === id);
+        let lexicalIndex: MiniSearch;
+        if (sameEntries) {
+          lexicalIndex = lexicalIndexSnapshot!.index;
         } else {
-          // No text query - chronological order (score by recency)
-          score = entry.created.getTime();
+          const builtIndex = new MiniSearch({
+            fields: ["title", "body"],
+            storeFields: ["id"],
+          });
+          builtIndex.addAll(filtered.map(({ entry }) => ({
+            id: entry.id,
+            title: entry.title,
+            body: entry.body,
+          })));
+          lexicalIndexSnapshot = { ids, index: builtIndex };
+          lexicalIndex = builtIndex;
         }
-
-        entries.push({ entry, score });
+        const byId = new Map(filtered.map(({ entry }) => [entry.id, entry]));
+        const lexical = lexicalIndex.search(query.text, { combineWith: "OR" });
+        if (hasLexicalTerms(query.text)) {
+          ranked = lexical.flatMap((match) => {
+            const entry = byId.get(String(match.id));
+            return entry ? [{ entry, score: match.score }] : [];
+          });
+        } else {
+          ranked = substringMatches(filtered, query.text);
+        }
+        ranked.sort((a, b) =>
+          b.score - a.score ||
+          b.entry.created.getTime() - a.entry.created.getTime() ||
+          (a.entry.id < b.entry.id ? 1 : a.entry.id > b.entry.id ? -1 : 0),
+        );
       }
 
-      const total = entries.length;
-
-      // Sort by score descending
-      entries.sort((a, b) => b.score - a.score);
+      // Count lexical candidates after metadata filtering, before paging.
+      const total = ranked.length;
 
       // Apply offset + limit
-      entries = entries.slice(offset, offset + limit);
+      ranked = ranked.slice(offset, offset + limit);
 
       return {
-        entries: entries.map((e) => e.entry),
+        entries: ranked.map((e) => e.entry),
         total,
         allTags: Array.from(tagSet).sort(),
       };

package/src/tools.test.ts

@@ -31,7 +31,7 @@ describe("v2 journal tools", () => {
     expect([JournalWrite(baseStore, context).name, JournalRead(baseStore).name, JournalSearch(baseStore).name]).toEqual(["journal_write", "journal_read", "journal_search"]);
     expect(JournalWrite(baseStore, context).description).toContain("append-only");
     expect(JournalRead(baseStore).description).toContain("by its ID");
-    expect(JournalSearch(baseStore).description).toContain("semantic similarity");
+    expect(JournalSearch(baseStore).description).toContain("lexical OR matching");
   });
 
   test("journal_write description preserves its behavioral guidance", () => {
@@ -95,7 +95,7 @@ describe("v2 journal tools", () => {
     }
     expect(writeResult.content).toContain("Journal entry created:");
     expect(readResult.content).toContain("Body");
-    expect(searchResult.content).toContain("Found 1 entries");
+    expect(searchResult.content).toContain("Found 1 candidate entries");
   });
 
   test("retains bounded tag inventory output formatting", async () => {

package/src/tools.ts

@@ -76,11 +76,11 @@ export function JournalRead(store: JournalStore): ToolDefinition {
 export function JournalSearch(store: JournalStore): ToolDefinition {
   return {
     name: "journal_search",
-    description: "Search journal entries using semantic similarity. Returns matching entries sorted by relevance. All filters are optional and combined with AND logic. Use with no arguments to list recent entries. Use offset to paginate. Before starting complex tasks, search the journal for relevant past context. The journal is global across all projects but each entry records which project it was written from.",
+    description: "Find candidate journal entries by lexical OR matching query words in titles and bodies. Candidates are not relevance claims. All filters are optional and combined with AND logic. Use with no arguments to list recent entries. Use offset to paginate. Before starting complex tasks, search the journal for relevant past context. The journal is global across all projects but each entry records which project it was written from.",
     input: {
       type: "object",
       properties: {
-        text: { type: "string", description: "Semantic search text" },
+        text: { type: "string", description: "Query words for lexical candidate matching in titles and bodies" },
         project: { type: "string", description: "Filter by project directory" },
         tags: { type: "string", description: "Comma-separated tags; all must match" },
         limit: { type: "integer", minimum: 1, description: "Maximum entries to return" },
@@ -99,7 +99,7 @@ export function JournalSearch(store: JournalStore): ToolDefinition {
       const tagsLine = formatTagsInUse(result.allTags);
       if (!result.entries.length) return { content: `No journal entries found.${tagsLine}` };
       const offset = (input.offset as number | undefined) ?? 0;
-      const header = `Found ${result.total} entries (showing ${offset + 1}–${offset + result.entries.length}):`;
+      const header = `Found ${result.total} candidate entries (showing ${offset + 1}–${offset + result.entries.length}):`;
       const lines = result.entries.map((entry) => `${entry.id}\n  ${entry.title}${entry.tags.length ? ` [${entry.tags.join(", ")}]` : ""}\n  ${entry.created.toISOString()}`);
       return { content: `${header}${tagsLine}\n\n${lines.join("\n\n")}` };
     },