@ghilteras/opencode-agent-memory 1.0.0 → 2.0.0

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({
@@ -98,7 +99,7 @@ export type JournalTag = {
   description: string;
 };
 
-const EntryFrontmatterSchema = z.looseObject({
+export const EntryFrontmatterSchema = z.looseObject({
   title: z.string().min(1),
   project: z.string().optional(),
   model: z.string().optional(),
@@ -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/plugin-disabled.test.ts

@@ -1,15 +1,25 @@
-import { afterEach, expect, mock, test } from "bun:test";
+import { expect, mock, test } from "bun:test";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as realEmbeddings from "./embeddings";
 
-mock.module("./journal", () => ({
-  loadConfig: async () => ({ config: { journal: { enabled: false } }, status: "ok", configPath: "/tmp/disabled/agent-memory.json" }),
-  createJournalStore: () => ({}),
+if (process.env.HOME === undefined || !process.env.HOME.startsWith("/tmp/")) {
+  throw new Error("plugin tests require HOME pointed at a /tmp fixture directory; run via `bun run test:plugin`");
+}
+
+const configDir = path.join(process.env.HOME, ".config", "opencode");
+
+mock.module("./embeddings", () => ({
+  ...realEmbeddings,
+  generateEmbedding: async () => Array.from({ length: 384 }, (_, i) => Math.sin(i) * 0.5),
+  warmupEmbedder: async () => {},
 }));
-mock.module("./embeddings", () => ({ warmupEmbedder: async () => {} }));
-import plugin from "./plugin";
 
-afterEach(() => mock.restore());
+import plugin from "./plugin";
 
 test("explicit opt-out registers no tools and emits no warning", async () => {
+  await fs.mkdir(configDir, { recursive: true });
+  await fs.writeFile(path.join(configDir, "agent-memory.json"), JSON.stringify({ journal: { enabled: false } }), "utf-8");
   const definitions: unknown[] = [];
   const warn = console.warn;
   let warnings = 0;
@@ -18,9 +28,12 @@ test("explicit opt-out registers no tools and emits no warning", async () => {
     await plugin.setup({
       location: { directory: "/tmp" },
       session: { hook: async () => {} },
-      tool: { transform: async (callback: (editor: { add: (tool: unknown) => void }) => void) => callback({ add: (tool) => definitions.push(tool) }) },
+      tool: { transform: async (callback: (editor: { add: (tool: unknown) => void; list: () => unknown[] }) => void) => callback({ add: (tool) => definitions.push(tool), list: () => [] }) },
     } as any);
     expect(definitions).toEqual([]);
     expect(warnings).toBe(0);
-  } finally { console.warn = warn; }
+  } finally {
+    console.warn = warn;
+    await fs.rm(configDir, { recursive: true, force: true });
+  }
 });

package/src/plugin.test.ts

@@ -1,66 +1,77 @@
 import { afterEach, describe, expect, mock, test } from "bun:test";
-import type { LoadedConfig, JournalEntry } from "./journal";
-
-let loadedConfig: LoadedConfig = { config: {}, status: "missing", configPath: "/tmp/test/agent-memory.json", reason: "file is missing" };
-const writes: Array<Record<string, unknown>> = [];
-mock.module("./journal", () => ({
-  loadConfig: async () => loadedConfig,
-  createJournalStore: () => ({
-    write: async (entry: Record<string, unknown>) => {
-      writes.push(entry);
-      return { id: "id-1", title: entry.title, created: new Date("2026-01-01T00:00:00.000Z") } as JournalEntry;
-    },
-    read: async () => { throw new Error("unused"); },
-    search: async () => ({ entries: [], total: 0, allTags: [] }),
-  }),
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as realEmbeddings from "./embeddings";
+
+// These tests run in their own bun process (package.json "test:plugin") with
+// HOME pointed at a throwaway fixture directory, so the real loadConfig and
+// createJournalStore exercise real fixture files. Refuse to run against the
+// real home directory. Only the model-loading surface of ./embeddings is
+// stubbed, spreading the real module so other exports keep real values.
+if (process.env.HOME === undefined || !process.env.HOME.startsWith("/tmp/")) {
+  throw new Error("plugin tests require HOME pointed at a /tmp fixture directory; run via `bun run test:plugin`");
+}
+
+const fixtureHome = process.env.HOME;
+const configDir = path.join(fixtureHome, ".config", "opencode");
+const configPath = path.join(configDir, "agent-memory.json");
+const journalDir = path.join(configDir, "journal");
+
+mock.module("./embeddings", () => ({
+  ...realEmbeddings,
+  generateEmbedding: async () => Array.from({ length: 384 }, (_, i) => Math.sin(i) * 0.5),
+  warmupEmbedder: async () => {},
 }));
-mock.module("./embeddings", () => ({ warmupEmbedder: async () => {} }));
 
 import plugin from "./plugin";
 
-function harness() {
+// value === undefined creates a DIRECTORY at the config path (unreadable);
+// a string is written raw (malformed JSON); an object is JSON-encoded.
+async function writeConfig(value: unknown): Promise<void> {
+  await fs.mkdir(configDir, { recursive: true });
+  if (value === undefined) {
+    await fs.mkdir(configPath, { recursive: true });
+  } else if (typeof value === "string") {
+    await fs.writeFile(configPath, value, "utf-8");
+  } else {
+    await fs.writeFile(configPath, JSON.stringify(value), "utf-8");
+  }
+}
+
+function harness(directory = "/tmp/project") {
   const definitions = new Map<string, any>();
   let contextHook: ((event: any) => void) | undefined;
   let transform: ((editor: { add: (definition: any) => void; list: () => any[] }) => void) | undefined;
   const context = {
-    location: { directory: "/tmp/project" },
+    location: { directory },
     session: { hook: async (name: string, callback: (event: any) => void) => { expect(name).toBe("context"); contextHook = callback; } },
     tool: { transform: async (callback: typeof transform) => { transform = callback; callback!({ add: (definition) => definitions.set(definition.name, definition), list: () => [...definitions.values()] }); } },
   } as any;
   return { definitions, contextHook: () => contextHook, replay: () => transform!({ add: (definition) => definitions.set(definition.name, definition), list: () => [...definitions.values()] }), start: () => plugin.setup(context) };
 }
 
-afterEach(() => {
-  loadedConfig = { config: {}, status: "missing", configPath: "/tmp/test/agent-memory.json", reason: "file is missing" };
-  writes.length = 0;
+afterEach(async () => {
+  await fs.rm(configDir, { recursive: true, force: true });
 });
 
 describe("v2 plugin registration", () => {
   test("has a stable id and default-registers exactly the three journal tools", async () => {
     expect(plugin.id).toBe("opencode-agent-memory");
+    await fs.rm(configDir, { recursive: true, force: true }); // absent config: default-on journal tools
     const h = harness();
     await h.start();
     expect([...h.definitions.keys()].sort()).toEqual(["journal_read", "journal_search", "journal_write"]);
   });
 
   test("registered write description suggests configured tag names without their descriptions", async () => {
-    loadedConfig = {
-      config: {
-        journal: {
-          tags: [
-            { name: "owner_approved", description: "Use for a choice made and its rationale." },
-            { name: "incident_followup", description: "Use for investigation notes and findings." },
-          ],
-        },
-      },
-      status: "ok",
-      configPath: "/tmp/test/agent-memory.json",
-    };
-
+    await writeConfig({ journal: { tags: [
+      { name: "owner_approved", description: "Use for a choice made and its rationale." },
+      { name: "incident_followup", description: "Use for investigation notes and findings." },
+    ] } });
     const h = harness();
     await h.start();
     const description = h.definitions.get("journal_write").description as string;
-
     expect(description).toContain("Suggested tags: owner_approved, incident_followup.");
     expect(description).not.toContain("Use for a choice made and its rationale.");
     expect(description).not.toContain("Use for investigation notes and findings.");
@@ -73,36 +84,58 @@ describe("v2 plugin registration", () => {
   });
 
   test("explicit false opts out without tools", async () => {
-    loadedConfig = { config: { journal: { enabled: false } }, status: "ok", configPath: "/tmp/test/agent-memory.json" };
+    await writeConfig({ journal: { enabled: false } });
     const h = harness(); await h.start();
     expect([...h.definitions.keys()]).toEqual([]);
   });
 
   test("invalid journal typo fails closed and warns", async () => {
-    loadedConfig = { config: {}, status: "invalid", configPath: "/tmp/test/agent-memory.json", reason: "schema validation failed" };
+    await writeConfig({ journal: { enabled_: false } });
     const warnings: unknown[][] = [];
     const originalWarn = console.warn;
     console.warn = (...args) => warnings.push(args);
     try {
       const h = harness(); await h.start();
       expect([...h.definitions.keys()]).toEqual([]);
-      expect(warnings).toEqual([["[agent-memory] journal config /tmp/test/agent-memory.json: schema validation failed; journal tools will NOT be registered"]]);
+      expect(warnings).toEqual([[`[agent-memory] journal config ${configPath}: schema validation failed; journal tools will NOT be registered`]]);
     } finally { console.warn = originalWarn; }
   });
 
-  for (const status of ["unreadable", "malformed", "invalid"] as const) {
-    test(`fails closed on ${status} config`, async () => {
-      loadedConfig = { config: { journal: { enabled: true } }, status, configPath: "/tmp/test/agent-memory.json", reason: "bad config" };
-      const warnings: unknown[][] = [];
-      const originalWarn = console.warn;
-      console.warn = (...args) => warnings.push(args);
-      try {
-        const h = harness(); await h.start();
-        expect([...h.definitions.keys()]).toEqual([]);
-        expect(warnings).toEqual([["[agent-memory] journal config /tmp/test/agent-memory.json: bad config; journal tools will NOT be registered"]]);
-      } finally { console.warn = originalWarn; }
-    });
-  }
+  test("fails closed on unreadable config", async () => {
+    await writeConfig(undefined);
+    const warnings: unknown[][] = [];
+    const originalWarn = console.warn;
+    console.warn = (...args) => warnings.push(args);
+    try {
+      const h = harness(); await h.start();
+      expect([...h.definitions.keys()]).toEqual([]);
+      expect(warnings).toEqual([[`[agent-memory] journal config ${configPath}: read failed (EISDIR); journal tools will NOT be registered`]]);
+    } finally { console.warn = originalWarn; }
+  });
+
+  test("fails closed on malformed config", async () => {
+    await writeConfig("not json{{{");
+    const warnings: unknown[][] = [];
+    const originalWarn = console.warn;
+    console.warn = (...args) => warnings.push(args);
+    try {
+      const h = harness(); await h.start();
+      expect([...h.definitions.keys()]).toEqual([]);
+      expect(warnings).toEqual([[`[agent-memory] journal config ${configPath}: malformed JSON; journal tools will NOT be registered`]]);
+    } finally { console.warn = originalWarn; }
+  });
+
+  test("fails closed on invalid config", async () => {
+    await writeConfig({ journal: { enabled: "yes" } });
+    const warnings: unknown[][] = [];
+    const originalWarn = console.warn;
+    console.warn = (...args) => warnings.push(args);
+    try {
+      const h = harness(); await h.start();
+      expect([...h.definitions.keys()]).toEqual([]);
+      expect(warnings).toEqual([[`[agent-memory] journal config ${configPath}: schema validation failed; journal tools will NOT be registered`]]);
+    } finally { console.warn = originalWarn; }
+  });
 
   test("default absent config emits no warning", async () => {
     const warnings: unknown[][] = [];
@@ -119,6 +152,69 @@ describe("v2 plugin registration", () => {
     hook({ sessionID: "session-b", model: { id: "model-b", providerID: "provider-b" } });
     hook({ sessionID: "session-a", model: { id: "model-a2", providerID: "provider-a2" } });
     await h.definitions.get("journal_write").execute({ title: "Title", body: "Body" }, { agent: "agent", sessionID: "session-b" });
-    expect(writes[0]).toMatchObject({ model: "model-b", provider: "provider-b", sessionId: "session-b" });
+    const files = (await fs.readdir(journalDir)).filter((f) => f.endsWith(".md"));
+    expect(files).toHaveLength(1);
+    const text = await fs.readFile(path.join(journalDir, files[0]!), "utf-8");
+    expect(text).toContain("model: model-b");
+    expect(text).toContain("provider: provider-b");
+    expect(text).toContain("session_id: session-b");
+  });
+});
+
+describe("project journal index injection", () => {
+  const event = () => ({ sessionID: "s", model: { id: "m", providerID: "p" }, system: [] as Array<{ type: "text"; text: string }> });
+  async function project(body?: string) {
+    const directory = await fs.mkdtemp(path.join(os.tmpdir(), "memory-index-"));
+    if (body !== undefined) await fs.writeFile(path.join(directory, "MEMORY.md"), body);
+    return directory;
+  }
+
+  test("injects a byte-stable rendered index at exact word fit", async () => {
+    const directory = await project(Array(330).fill("pointer").join(" "));
+    try {
+      const h = harness(directory); await h.start();
+      const first = event(); const second = event();
+      await h.contextHook()!(first); await h.contextHook()!(second);
+      expect(first.system).toEqual(second.system);
+      expect(first.system).toHaveLength(1);
+      expect(first.system[0]!.text).toBe(`This is the project's journal-pointer index (MEMORY.md at the repository root). Retrieve entries with journal_search/journal_read; older lines remain relevant.\n\n${Array(330).fill("pointer").join(" ")}`);
+    } finally { await fs.rm(directory, { recursive: true, force: true }); }
+  });
+
+  test("331 words injects only the fixed notice", async () => {
+    const directory = await project(Array(331).fill("pointer").join(" "));
+    try { const h = harness(directory); await h.start(); const e = event(); await h.contextHook()!(e); expect(e.system).toEqual([{ type: "text", text: "Project journal index (MEMORY.md) exceeds the injection cap; read the file at the repository root directly for the pointer list." }]); }
+    finally { await fs.rm(directory, { recursive: true, force: true }); }
+  });
+
+  test("empty, missing, and unreadable indexes inject nothing", async () => {
+    const empty = await project("  \n\t");
+    const missing = await project();
+    const unreadable = path.join(os.tmpdir(), `memory-index-file-${Date.now()}`);
+    await fs.writeFile(unreadable, "not a directory");
+    try {
+      for (const directory of [empty, missing, unreadable]) {
+        const h = harness(directory); await h.start(); const e = event(); await h.contextHook()!(e); expect(e.system).toEqual([]);
+      }
+    } finally {
+      await fs.rm(empty, { recursive: true, force: true });
+      await fs.rm(missing, { recursive: true, force: true });
+      await fs.rm(unreadable, { force: true });
+    }
+  });
+
+  test("strips frontmatter; enforces UTF-8 byte cap for long Unicode tokens", async () => {
+    const directory = await project(`---\ntitle: hidden\n---\nvisible pointer`);
+    try { const h = harness(directory); await h.start(); const e = event(); await h.contextHook()!(e); expect(e.system[0]!.text).toContain("\n\nvisible pointer"); expect(e.system[0]!.text).not.toContain("hidden"); }
+    finally { await fs.rm(directory, { recursive: true, force: true }); }
+    const large = await project("界".repeat(8192));
+    try { const h = harness(large); await h.start(); const e = event(); await h.contextHook()!(e); expect(e.system[0]!.text).toBe("Project journal index (MEMORY.md) exceeds the injection cap; read the file at the repository root directly for the pointer list."); }
+    finally { await fs.rm(large, { recursive: true, force: true }); }
+  });
+
+  test("disabled journal registers no hook or injection", async () => {
+    const directory = await project("pointer");
+    try { await writeConfig({ journal: { enabled: false } }); const h = harness(directory); await h.start(); expect(h.contextHook()).toBeUndefined(); }
+    finally { await fs.rm(directory, { recursive: true, force: true }); }
   });
 });

package/src/plugin.ts

@@ -3,6 +3,14 @@ import { createJournalStore, loadConfig } from "./journal";
 import { JournalRead, JournalSearch, JournalWrite } from "./tools";
 import type { JournalContext } from "./tools";
 import { warmupEmbedder } from "./embeddings";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { splitFrontmatter } from "./frontmatter";
+
+const INDEX_NOTICE = "Project journal index (MEMORY.md) exceeds the injection cap; read the file at the repository root directly for the pointer list.";
+const INDEX_WRAPPER = "This is the project's journal-pointer index (MEMORY.md at the repository root). Retrieve entries with journal_search/journal_read; older lines remain relevant.";
+const MAX_INDEX_WORDS = 330;
+const MAX_INDEX_BYTES = 8192;
 
 export default Plugin.define({
   id: "opencode-agent-memory",
@@ -20,6 +28,7 @@ export default Plugin.define({
     const journalStore = createJournalStore(undefined, config.cacheDir);
     void warmupEmbedder(config.cacheDir).catch(() => {});
     const contexts = new Map<string, JournalContext>();
+    // Location.Info.directory is the project directory (there is no separate root field).
     const directory = ctx.location.directory;
     const tools = [
       JournalWrite(journalStore, {
@@ -44,12 +53,22 @@ export default Plugin.define({
       return contextual.execute(input, toolCtx);
     };
 
-    await ctx.session.hook("context", (input) => {
+    await ctx.session.hook("context", async (input) => {
       contexts.set(input.sessionID, {
         directory,
         model: input.model.id,
         provider: input.model.providerID,
       });
+      try {
+        const source = await fs.readFile(path.join(directory, "MEMORY.md"), "utf8");
+        const body = splitFrontmatter(source).body;
+        if (body.trim().length === 0) return;
+        const rendered = `${INDEX_WRAPPER}\n\n${body}`;
+        const words = body.trim().split(/\s+/).length;
+        input.system.push({ type: "text", text: words <= MAX_INDEX_WORDS && Buffer.byteLength(rendered, "utf8") <= MAX_INDEX_BYTES ? rendered : INDEX_NOTICE });
+      } catch {
+        // Missing and unreadable project indexes are intentionally silent.
+      }
     });
     await ctx.tool.transform((editor) => {
       // Transforms may be replayed; avoid duplicate registrations by effective tool name.