@ghilteras/opencode-agent-memory 1.0.0 → 1.2.0

package/README.md

@@ -32,7 +32,7 @@ Add to your OpenCode config (`~/.config/opencode/opencode.json`):
 
 ```json
 {
-  "plugins": ["@ghilteras/opencode-agent-memory@1.0.0"]
+  "plugins": ["@ghilteras/opencode-agent-memory@1.1.0"]
 }
 ```
 
@@ -156,3 +156,11 @@ Originally created by Joshua David Thomas and licensed under the MIT license. Ma
 opencode-agent-memory is not built by, or affiliated with, the OpenCode team.
 
 OpenCode is ©2025 Anomaly.
+# Journal diagnostics
+
+Run `bun run journal:doctor [config-dir]` to inspect flat journal Markdown files
+and their `.embedding` sidecars without repairing or changing them. The optional
+directory is the OpenCode state/config directory (the journal is read from its
+`journal/` subdirectory); without it, the default is `~/.config/opencode`.
+The command prints a deterministic JSON report and exits 0 for a complete scan
+without errors, 1 for validation errors, or 2 for an incomplete scan/root error.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghilteras/opencode-agent-memory",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Journal-only memory plugin for OpenCode: tagged, searchable, append-only journal with semantic search.",
   "author": "Angelo Pantano <ghilteras@protonmail.com>",
   "license": "MIT",
@@ -17,8 +17,11 @@
     "src"
   ],
   "scripts": {
-    "test": "bun test",
-    "typecheck": "tsc --noEmit"
+    "test": "bun run test:core && bun run test:plugin",
+    "test:core": "bun test src/test-suite.test.ts src/doctor.test.ts src/embeddings.test.ts src/tools.test.ts src/journal.test.ts",
+    "test:plugin": "HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 HOME=$(mktemp -d) bun test src/plugin.test.ts src/plugin-disabled.test.ts",
+    "typecheck": "tsc --noEmit",
+    "journal:doctor": "bun run src/journal-doctor.ts"
   },
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",

package/src/doctor.test.ts

@@ -0,0 +1,183 @@
+import { afterEach, expect, test } from "bun:test";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { diagnoseJournal } from "./doctor";
+
+const roots: string[] = [];
+async function fixture() {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "journal-doctor-"));
+  roots.push(root);
+  await fs.mkdir(path.join(root, "journal"));
+  return path.join(root, "journal");
+}
+async function entry(dir: string, name: string, yamlText?: string, sidecar?: string) {
+  await fs.writeFile(path.join(dir, `${name}.md`), yamlText === undefined ? "plain text" : `---\n${yamlText}\n---\nbody\n`);
+  if (sidecar !== undefined) await fs.writeFile(path.join(dir, `${name}.embedding`), sidecar);
+}
+afterEach(async () => { await Promise.all(roots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true }))); });
+
+test("classifies frontmatter, created values, sidecars and multiple findings deterministically", async () => {
+  const dir = await fixture();
+  const valid = 'title: Good\ncreated: "2025-01-01T00:00:00Z"';
+  await entry(dir, "00-valid", valid, JSON.stringify({ v: 2, model: "wrong-model", dimension: 2, vector: [0.1, 0.2] }));
+  await entry(dir, "01-missing-title", "created: \"2025-01-01\"");
+  await entry(dir, "02-empty-title", 'title: ""');
+  await entry(dir, "03-wrong-title", "title: 42");
+  await entry(dir, "04-missing-created", "title: Present", "[1,2]");
+  await entry(dir, "05-date-only", "title: Present\ndate: \"2025-01-01\"");
+  await entry(dir, "06-invalid-created", 'title: Present\ncreated: "not a date"');
+  await entry(dir, "07-wrong-created", "title: Present\ncreated: 42");
+  await entry(dir, "08-yaml-timestamp", "title: Present\ncreated: 2025-01-01T00:00:00Z");
+  await entry(dir, "09-bad-yaml", "title: [broken");
+  await entry(dir, "10-no-frontmatter");
+  await entry(dir, "11-malformed-json", valid, "{");
+  await entry(dir, "12-vector-type", valid, '{"v":2,"model":"m","dimension":1,"vector":["x"]}');
+  await entry(dir, "13-empty-vector", valid, '{"v":2,"model":"m","dimension":0,"vector":[]}');
+  await entry(dir, "14-vector-dimension", valid, '{"v":2,"model":"m","dimension":3,"vector":[1,2]}');
+  await entry(dir, "15-legacy", valid, "[1,2]");
+  await entry(dir, "16-legacy-invalid", valid, '[1,"x"]');
+  await entry(dir, "17-missing-sidecar", valid);
+
+  const inventory = async () => Promise.all((await fs.readdir(dir)).sort().map(async (f) => [f, await fs.readFile(path.join(dir, f)), (await fs.stat(path.join(dir, f))).mtimeMs] as const));
+  const before = await inventory();
+  const report = await diagnoseJournal(path.dirname(dir));
+  expect(await diagnoseJournal(path.dirname(dir))).toEqual(report);
+  expect(report.counts.files).toBe(18);
+  const codes = (name: string) => report.findings.filter((f) => f.path.startsWith(name)).map((f) => f.code);
+  expect(codes("01-missing-title")).toContain("frontmatter_title_invalid");
+  expect(codes("02-empty-title")).toContain("frontmatter_title_invalid");
+  expect(codes("03-wrong-title")).toContain("frontmatter_title_invalid");
+  expect(codes("04-missing-created")).toContain("created_missing");
+  expect(codes("05-date-only")).toContain("created_missing");
+  expect(codes("06-invalid-created")).toContain("created_invalid");
+  expect(codes("07-wrong-created")).toContain("frontmatter_created_invalid");
+  expect(codes("08-yaml-timestamp")).toContain("frontmatter_created_invalid");
+  expect(codes("09-bad-yaml")).toContain("yaml_malformed");
+  expect(codes("10-no-frontmatter")).toContain("frontmatter_missing_or_malformed");
+  expect(codes("11-malformed-json")).toContain("embedding_json_malformed");
+  for (const name of ["12-vector-type", "13-empty-vector", "14-vector-dimension", "16-legacy-invalid"]) expect(codes(name)).toContain("embedding_invalid");
+  expect(codes("00-valid")).toContain("embedding_incompatible");
+  expect(codes("15-legacy")).toContain("embedding_model_unknown");
+  expect(codes("17-missing-sidecar")).toContain("embedding_missing");
+  expect(codes("04-missing-created")).toEqual(expect.arrayContaining(["created_missing", "embedding_model_unknown"]));
+  expect(report.findings).toEqual([...report.findings].sort((a, b) => a.path.localeCompare(b.path) || a.code.localeCompare(b.code) || a.severity.localeCompare(b.severity)));
+  expect(report.findings.some((f) => /broken|Good|Present|not a date/.test(JSON.stringify(f)))).toBe(false);
+  expect(await inventory()).toEqual(before);
+});
+
+test("empty, missing, and injected unreadable roots/files have explicit incomplete semantics", async () => {
+  const missing = await diagnoseJournal("/path/that/does/not/exist");
+  expect(missing.complete).toBe(false);
+  expect(missing.findings[0]?.code).toBe("root_unreadable");
+  const dir = await fixture();
+  expect((await diagnoseJournal(path.dirname(dir))).complete).toBe(true);
+  await entry(dir, "a", "title: A"); await entry(dir, "b", "title: B");
+  const failingRead = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
+    if (String(p).endsWith("a.md")) throw new Error("injected");
+    return fs.readFile(p, ...(args as [any]));
+  } } as unknown as typeof fs;
+  const report = await diagnoseJournal(path.dirname(dir), failingRead);
+  expect(report.complete).toBe(false);
+  expect(report.findings.some((f) => f.path === "a.md" && f.code === "file_unreadable")).toBe(true);
+  expect(report.findings.some((f) => f.path === "b.md" && f.code === "created_missing")).toBe(true);
+});
+
+test("CLI emits exact bytes and exit codes for clean, warning, error, incomplete and bad invocation", async () => {
+  const dir = await fixture();
+  const cli = path.resolve(import.meta.dir, "journal-doctor.ts");
+  const invoke = (...args: string[]) => Bun.spawnSync([process.execPath, "run", cli, ...args], { stdout: "pipe", stderr: "pipe" });
+  const assertCli = (result: ReturnType<typeof invoke>, stdout: string, stderr: string, exitCode: number) =>
+    expect({ stdout: result.stdout.toString(), stderr: result.stderr.toString(), exitCode: result.exitCode }).toEqual({ stdout, stderr, exitCode });
+  assertCli(invoke(path.dirname(dir)), '{"complete":true,"counts":{"files":0,"errors":0,"warnings":0},"findings":[]}\n', "", 0);
+
+  await entry(dir, "warning", 'title: Warn\ncreated: "2025-01-01"');
+  assertCli(invoke(path.dirname(dir)), '{"complete":true,"counts":{"files":1,"errors":0,"warnings":1},"findings":[{"path":"warning.embedding","code":"embedding_missing","severity":"warning"}]}\n', "", 0);
+
+  await entry(dir, "invalid", "title: 12");
+  assertCli(invoke(path.dirname(dir)), '{"complete":true,"counts":{"files":2,"errors":1,"warnings":2},"findings":[{"path":"invalid.embedding","code":"embedding_missing","severity":"warning"},{"path":"invalid.md","code":"frontmatter_title_invalid","severity":"error"},{"path":"warning.embedding","code":"embedding_missing","severity":"warning"}]}\n', "", 1);
+
+  assertCli(invoke("/path/that/does/not/exist"), '{"complete":false,"counts":{"files":0,"errors":1,"warnings":0},"findings":[{"path":".","code":"root_unreadable","severity":"error"}]}\n', "", 2);
+  assertCli(invoke(path.dirname(dir), "extra"), "", "usage: bun run journal:doctor [config-dir]\n", 2);
+});
+
+test("inventories orphan and associated sidecars independently and emits stable full report", async () => {
+  const dir = await fixture();
+  const valid = 'title: Good\ncreated: "2025-01-01T00:00:00Z"';
+  await entry(dir, "A", valid);
+  await entry(dir, "a", valid, "{");
+  await fs.writeFile(path.join(dir, "_.embedding"), "{");
+  const expected = { complete: true, counts: { files: 2, errors: 2, warnings: 2 }, findings: [
+    { path: "A.embedding", code: "embedding_missing", severity: "warning" },
+    { path: "_.embedding", code: "embedding_json_malformed", severity: "error" },
+    { path: "_.embedding", code: "embedding_orphan", severity: "warning" },
+    { path: "a.embedding", code: "embedding_json_malformed", severity: "error" },
+  ] };
+  const report = await diagnoseJournal(path.dirname(dir));
+  expect(JSON.stringify(report)).toBe(JSON.stringify(expected));
+  const cli = path.resolve(import.meta.dir, "journal-doctor.ts");
+  const result = Bun.spawnSync([process.execPath, "run", cli, path.dirname(dir)], { stdout: "pipe", stderr: "pipe" });
+  expect({ stdout: result.stdout.toString(), stderr: result.stderr.toString(), exitCode: result.exitCode }).toEqual({ stdout: `${JSON.stringify(expected)}\n`, stderr: "", exitCode: 1 });
+});
+
+test("sidecar validation survives markdown read failure; listed sidecar disappearance is incomplete", async () => {
+  const dir = await fixture();
+  await entry(dir, "a", 'title: Good\ncreated: "2025-01-01T00:00:00Z"', "{");
+  const failingRead = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
+    if (String(p).endsWith("a.md")) throw Object.assign(new Error("denied"), { code: "EACCES" });
+    return fs.readFile(p, ...(args as [any]));
+  } } as unknown as typeof fs;
+  const failed = await diagnoseJournal(path.dirname(dir), failingRead);
+  expect(failed.complete).toBe(false);
+  expect(failed.findings.map((f) => f.code)).toEqual(expect.arrayContaining(["file_unreadable", "embedding_json_malformed"]));
+
+  let removed = false;
+  const disappearing = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
+    if (String(p).endsWith("a.embedding") && !removed) { removed = true; throw Object.assign(new Error("gone"), { code: "ENOENT" }); }
+    return fs.readFile(p, ...(args as [any]));
+  } } as unknown as typeof fs;
+  const gone = await diagnoseJournal(path.dirname(dir), disappearing);
+  expect(gone.complete).toBe(false);
+  expect(gone.findings.some((f) => f.path === "a.embedding" && f.code === "embedding_unreadable")).toBe(true);
+});
+
+test("diagnosis never initializes model pipeline or fetches, while warmup activates trap in child", async () => {
+  const dir = await fixture();
+  await entry(dir, "a", 'title: Good\ncreated: "2025-01-01T00:00:00Z"');
+  const childCode = `
+    import { mock } from "bun:test";
+    let pipelines = 0, fetches = 0;
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async (...args) => { fetches++; throw new Error("FETCH_SENTINEL"); };
+    mock.module("@huggingface/transformers", () => ({ pipeline: async () => { pipelines++; throw new Error("PIPELINE_SENTINEL"); } }));
+    const { diagnoseJournal } = await import(${JSON.stringify(path.resolve(import.meta.dir, "doctor.ts"))});
+    const { warmupEmbedder } = await import(${JSON.stringify(path.resolve(import.meta.dir, "embeddings.ts"))});
+    await diagnoseJournal(${JSON.stringify(path.dirname(dir))});
+    if (pipelines !== 0 || fetches !== 0) throw new Error("diagnosis activated model/fetch trap");
+    try { await warmupEmbedder(); throw new Error("pipeline sentinel was not caught"); } catch (error) { if (!String(error).includes("PIPELINE_SENTINEL")) throw error; }
+    if (pipelines !== 1 || fetches !== 0) throw new Error("pipeline trap count mismatch");
+    globalThis.fetch = originalFetch;
+    console.log(JSON.stringify({ pipelines, fetches }));
+  `;
+  const result = Bun.spawnSync([process.execPath, "-e", childCode], { stdout: "pipe", stderr: "pipe" });
+  expect({ stdout: result.stdout.toString(), stderr: result.stderr.toString(), exitCode: result.exitCode }).toEqual({ stdout: '{"pipelines":1,"fetches":0}\n', stderr: "", exitCode: 0 });
+});
+
+test("only flat regular inventory files are read and each sidecar is read once", async () => {
+  const dir = await fixture();
+  await entry(dir, "a", 'title: Good\ncreated: "2025-01-01T00:00:00Z"', "[1]");
+  await fs.mkdir(path.join(dir, "nested"));
+  await fs.writeFile(path.join(dir, "nested", "hidden.md"), "bad");
+  await fs.writeFile(path.join(dir, "nested", "hidden.embedding"), "{");
+  await fs.writeFile(path.join(dir, "ignored.txt"), "bad");
+  await fs.symlink(path.join(dir, "a.md"), path.join(dir, "linked.md"));
+  const reads = new Map<string, number>();
+  const counting = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
+    const name = path.basename(String(p)); reads.set(name, (reads.get(name) ?? 0) + 1);
+    return fs.readFile(p, ...(args as [any]));
+  } } as unknown as typeof fs;
+  const report = await diagnoseJournal(path.dirname(dir), counting);
+  expect(report.counts.files).toBe(1);
+  expect([...reads.entries()].sort()).toEqual([["a.embedding", 1], ["a.md", 1]]);
+  expect(report.findings.map((f) => f.path)).toEqual(["a.embedding", "a.embedding"]);
+});

package/src/doctor.ts

@@ -0,0 +1,87 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import { z } from "zod";
+import { EMBEDDING_DIMENSION, embeddingModelName } from "./embeddings";
+import { splitFrontmatter } from "./frontmatter";
+import { EntryFrontmatterSchema } from "./journal";
+
+export type JournalFinding = { path: string; code: string; severity: "error" | "warning" };
+export type JournalDiagnosticReport = {
+  complete: boolean;
+  counts: { files: number; errors: number; warnings: number };
+  findings: JournalFinding[];
+};
+type FileSystem = Pick<typeof fs, "readdir" | "readFile" | "stat">;
+
+export async function diagnoseJournal(configDir?: string, fileSystem: FileSystem = fs): Promise<JournalDiagnosticReport> {
+  const root = path.resolve(configDir ?? path.join(os.homedir(), ".config", "opencode"), "journal");
+  const findings: JournalFinding[] = [];
+  let complete = true;
+  const add = (file: string, code: string, severity: JournalFinding["severity"]) => findings.push({ path: file, code, severity });
+  let entries: import("node:fs").Dirent[];
+  try { entries = await fileSystem.readdir(root, { withFileTypes: true }); }
+  catch { add(".", "root_unreadable", "error"); complete = false; entries = []; }
+
+  const inventory = entries.filter((entry) => entry.isFile() && (entry.name.endsWith(".md") || entry.name.endsWith(".embedding"))).map((entry) => entry.name).sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+  const files = inventory.filter((name) => name.endsWith(".md"));
+  const sidecars = inventory.filter((name) => name.endsWith(".embedding"));
+  const sidecarSet = new Set(sidecars);
+  for (const name of files) {
+    const relative = name;
+    let raw: string | undefined;
+    try { raw = await fileSystem.readFile(path.join(root, name), "utf8"); }
+    catch { add(relative, "file_unreadable", "error"); complete = false; }
+    if (raw !== undefined) {
+      const { frontmatterText } = splitFrontmatter(raw);
+      if (frontmatterText === undefined) add(relative, "frontmatter_missing_or_malformed", "error");
+      else {
+        let value: unknown;
+        try { value = yaml.load(frontmatterText); }
+        catch { add(relative, "yaml_malformed", "error"); value = undefined; }
+        {
+          const parsed = EntryFrontmatterSchema.safeParse(value);
+          if (!parsed.success) {
+            const fields = [...new Set(parsed.error.issues.map((issue) => String(issue.path[0] ?? "document")))].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+            for (const field of fields) add(relative, `frontmatter_${field}_invalid`, "error");
+          } else {
+            if (parsed.data.created === undefined) add(relative, "created_missing", "warning");
+            else if (!Number.isFinite(new Date(parsed.data.created).getTime())) add(relative, "created_invalid", "error");
+          }
+        }
+      }
+    }
+  }
+
+  for (const sidecar of sidecars) {
+    const associatedMarkdown = `${sidecar.slice(0, -".embedding".length)}.md`;
+    if (!files.includes(associatedMarkdown)) add(sidecar, "embedding_orphan", "warning");
+    try {
+      const content = await fileSystem.readFile(path.join(root, sidecar), "utf8");
+      let value: unknown;
+      try { value = JSON.parse(content); } catch { add(sidecar, "embedding_json_malformed", "error"); continue; }
+      let vector: unknown; let dimension: unknown; let model: unknown; let legacy = false;
+      if (Array.isArray(value)) { vector = value; dimension = value.length; legacy = true; }
+      else if (value && typeof value === "object") {
+        const envelope = z.object({ v: z.literal(2), model: z.string(), dimension: z.number().int().positive(), vector: z.array(z.number().finite()).min(1) }).safeParse(value);
+        if (!envelope.success) { add(sidecar, "embedding_invalid", "error"); continue; }
+        ({ vector, dimension, model } = envelope.data);
+      } else { add(sidecar, "embedding_invalid", "error"); continue; }
+      if (!Array.isArray(vector) || vector.length === 0 || !vector.every((n) => typeof n === "number" && Number.isFinite(n)) || vector.length !== dimension) {
+        add(sidecar, "embedding_invalid", "error"); continue;
+      }
+      if (legacy) add(sidecar, "embedding_model_unknown", "warning");
+      if (vector.length !== EMBEDDING_DIMENSION || (!legacy && model !== embeddingModelName())) add(sidecar, "embedding_incompatible", "warning");
+    } catch (error) {
+      add(sidecar, "embedding_unreadable", "error"); complete = false;
+    }
+  }
+  for (const name of files) {
+    const expectedSidecar = `${name.slice(0, -".md".length)}.embedding`;
+    if (!sidecarSet.has(expectedSidecar)) add(expectedSidecar, "embedding_missing", "warning");
+  }
+  const compare = (a: string, b: string) => a < b ? -1 : a > b ? 1 : 0;
+  findings.sort((a, b) => compare(a.path, b.path) || compare(a.code, b.code) || compare(a.severity, b.severity));
+  return { complete, counts: { files: files.length, errors: findings.filter((f) => f.severity === "error").length, warnings: findings.filter((f) => f.severity === "warning").length }, findings };
+}

package/src/journal-doctor.ts

@@ -0,0 +1,11 @@
+import { diagnoseJournal } from "./doctor";
+
+const args = process.argv.slice(2);
+if (args.length > 1 || args.some((arg) => arg.startsWith("-"))) {
+  console.error("usage: bun run journal:doctor [config-dir]");
+  process.exitCode = 2;
+} else {
+  const report = await diagnoseJournal(args[0]);
+  console.log(JSON.stringify(report));
+  process.exitCode = !report.complete ? 2 : report.counts.errors > 0 ? 1 : 0;
+}

package/src/journal.test.ts

@@ -1,11 +1,13 @@
-import { afterEach, describe, expect, mock, test } from "bun:test";
+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 { createJournalStore, loadConfig } from "./journal";
-
-// Mock the embeddings module to avoid downloading a real model in tests
+// 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(
@@ -40,6 +42,16 @@ async function mkTmpDir(): Promise<string> {
   return fs.mkdtemp(path.join("/tmp/", "opencode-journal-"));
 }
 
+// Bind the journal module AFTER the embeddings mock registration (above) via
+// dynamic import, so the store uses the fake embeddings regardless of bun's
+// module-mock rewiring semantics; a static import would be hoisted above it.
+let createJournalStore!: (typeof import("./journal"))["createJournalStore"];
+let loadConfig!: (typeof import("./journal"))["loadConfig"];
+
+beforeAll(async () => {
+  ({ createJournalStore, loadConfig } = await import("./journal"));
+});
+
 describe("loadConfig", () => {
   test("classifies a missing file and returns an empty config", async () => {
     const dir = await mkTmpDir();
@@ -521,8 +533,9 @@ describe("journal store", () => {
       body: "unique-sidecar-deleted-content",
     });
 
-    // First search: caches the entry + sidecar fingerprint.
-    const r1 = await store.search({ text: "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.

package/src/journal.ts

@@ -98,7 +98,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(),

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.

package/src/test-suite.test.ts

@@ -0,0 +1,15 @@
+import { expect, test } from "bun:test";
+import * as fs from "node:fs/promises";
+
+// Guards the two-process test split in package.json: every test file in
+// src/ must be listed in exactly one group, or it silently never runs.
+const CORE = ["doctor.test.ts", "embeddings.test.ts", "journal.test.ts", "test-suite.test.ts", "tools.test.ts"];
+const PLUGIN = ["plugin-disabled.test.ts", "plugin.test.ts"];
+
+test("every test file is covered by the test:core/test:plugin split", async () => {
+  const files = (await fs.readdir(import.meta.dir))
+    .filter((f) => f.endsWith(".test.ts"))
+    .sort();
+  const covered = [...CORE, ...PLUGIN].sort();
+  expect(files).toEqual(covered);
+});