@ghilteras/opencode-agent-memory 0.5.1 → 0.5.2

package/README.md

@@ -32,7 +32,7 @@ Add to your OpenCode config (`~/.config/opencode/opencode.json`):
 
 ```json
 {
-  "plugin": ["@ghilteras/opencode-agent-memory@0.5.0"]
+  "plugin": ["@ghilteras/opencode-agent-memory@0.5.2"]
 }
 ```
 
@@ -50,7 +50,10 @@ The journal is **opt-in**. Enable it in `~/.config/opencode/agent-memory.json`:
 }
 ```
 
-With the journal disabled the plugin registers **no tools**.
+The plugin does **not** regenerate `agent-memory.json` if it is deleted; its loss otherwise silently disables the journal, which is why the fault warning exists.
+
+- Intentional disable (`"enabled": false`) is silent by design and registers **no tools**.
+- A missing, unreadable, malformed, or schema-invalid config logs `[agent-memory] journal config <resolved path>: <reason>; journal tools will NOT be registered` and registers **no tools**.
 
 ### Tools
 
@@ -126,9 +129,9 @@ Existing `~/.config/opencode/memory/` and `.opencode/memory/` directories are **
 
 - **Requires OpenCode v1.0.115+.**
 - **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 opt-in.** You must explicitly enable it in `~/.config/opencode/agent-memory.json`; with it disabled the plugin registers no tools.
+- **Journal is opt-in.** You must explicitly enable it in `~/.config/opencode/agent-memory.json`; intentional disablement is silent, while a missing, unreadable, malformed, or schema-invalid config logs a warning and registers no tools.
 - **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.
-- **Known limitation (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.
+- **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": "0.5.1",
+  "version": "0.5.2",
   "description": "Journal-only memory plugin for OpenCode: tagged, searchable, append-only journal with semantic search.",
   "author": "Angelo Pantano <ghilteras@protonmail.com>",
   "license": "MIT",

package/src/journal.test.ts

@@ -41,27 +41,60 @@ async function mkTmpDir(): Promise<string> {
 }
 
 describe("loadConfig", () => {
-  test("returns empty config when file does not exist", async () => {
+  test("classifies a missing file and returns an empty config", async () => {
     const dir = await mkTmpDir();
-    const config = await loadConfig(dir);
-    expect(config).toEqual({});
+    const loaded = await loadConfig(dir);
+    expect(loaded.status).toBe("missing");
+    expect(loaded.config).toEqual({});
   });
 
-  test("returns parsed config when file is valid", async () => {
+  test("classifies an unreadable file and returns an empty config", async () => {
+    const dir = await mkTmpDir();
+    await fs.mkdir(path.join(dir, "agent-memory.json"));
+    const loaded = await loadConfig(dir);
+    expect(loaded.status).toBe("unreadable");
+    expect(loaded.config).toEqual({});
+  });
+
+  test("classifies malformed JSON and returns an empty config", async () => {
+    const dir = await mkTmpDir();
+    await fs.writeFile(path.join(dir, "agent-memory.json"), "not json{{{");
+    const loaded = await loadConfig(dir);
+    expect(loaded.status).toBe("malformed");
+    expect(loaded.config).toEqual({});
+  });
+
+  test("classifies schema-invalid JSON and returns an empty config", async () => {
     const dir = await mkTmpDir();
     await fs.writeFile(
       path.join(dir, "agent-memory.json"),
-      JSON.stringify({ journal: { enabled: true } }),
+      JSON.stringify({ journal: { enabled: "yes" } }),
     );
-    const config = await loadConfig(dir);
-    expect(config.journal?.enabled).toBe(true);
+    const loaded = await loadConfig(dir);
+    expect(loaded.status).toBe("invalid");
+    expect(loaded.config).toEqual({});
   });
 
-  test("returns empty config when file has invalid JSON", async () => {
+  test("classifies valid disabled config without changing it", async () => {
     const dir = await mkTmpDir();
-    await fs.writeFile(path.join(dir, "agent-memory.json"), "not json{{{");
-    const config = await loadConfig(dir);
-    expect(config).toEqual({});
+    await fs.writeFile(
+      path.join(dir, "agent-memory.json"),
+      JSON.stringify({ journal: { enabled: false } }),
+    );
+    const loaded = await loadConfig(dir);
+    expect(loaded.status).toBe("ok");
+    expect(loaded.config).toEqual({ journal: { enabled: false } });
+  });
+
+  test("classifies valid enabled config without changing it", async () => {
+    const dir = await mkTmpDir();
+    await fs.writeFile(
+      path.join(dir, "agent-memory.json"),
+      JSON.stringify({ journal: { enabled: true } }),
+    );
+    const loaded = await loadConfig(dir);
+    expect(loaded.status).toBe("ok");
+    expect(loaded.config).toEqual({ journal: { enabled: true } });
   });
 
   test("returns custom tags from config", async () => {
@@ -78,22 +111,12 @@ describe("loadConfig", () => {
         },
       }),
     );
-    const config = await loadConfig(dir);
-    expect(config.journal?.tags).toEqual([
+    const loaded = await loadConfig(dir);
+    expect(loaded.config.journal?.tags).toEqual([
       { name: "perf", description: "Performance optimization work" },
       { name: "debug", description: "Debugging sessions" },
     ]);
   });
-
-  test("returns empty config when schema validation fails", async () => {
-    const dir = await mkTmpDir();
-    await fs.writeFile(
-      path.join(dir, "agent-memory.json"),
-      JSON.stringify({ journal: { enabled: "yes" } }),
-    );
-    const config = await loadConfig(dir);
-    expect(config).toEqual({});
-  });
 });
 
 describe("journal store", () => {

package/src/journal.ts

@@ -25,19 +25,72 @@ const ConfigSchema = z.looseObject({
 
 export type AgentMemoryConfig = z.infer<typeof ConfigSchema>;
 
+export type ConfigLoadStatus =
+  | "ok"
+  | "missing"
+  | "unreadable"
+  | "malformed"
+  | "invalid";
+
+export type LoadedConfig = {
+  config: AgentMemoryConfig;
+  status: ConfigLoadStatus;
+  configPath: string;
+  reason?: string;
+};
+
 export async function loadConfig(
   configDir?: string,
-): Promise<AgentMemoryConfig> {
+): Promise<LoadedConfig> {
   const dir = configDir ?? path.join(os.homedir(), ".config", "opencode");
-  const configPath = path.join(dir, "agent-memory.json");
+  const configPath = path.resolve(dir, "agent-memory.json");
+
+  let raw: string;
+  try {
+    raw = await fs.readFile(configPath, "utf-8");
+  } catch (error) {
+    const code = error instanceof Error && "code" in error
+      ? String(error.code)
+      : "unknown error";
+    if (code === "ENOENT") {
+      return {
+        config: {},
+        status: "missing",
+        configPath,
+        reason: "file is missing",
+      };
+    }
+    return {
+      config: {},
+      status: "unreadable",
+      configPath,
+      reason: `read failed (${code})`,
+    };
+  }
+
+  let value: unknown;
   try {
-    const raw = await fs.readFile(configPath, "utf-8");
-    const parsed = ConfigSchema.safeParse(JSON.parse(raw));
-    if (!parsed.success) return {};
-    return parsed.data;
+    value = JSON.parse(raw);
   } catch {
-    return {};
+    return {
+      config: {},
+      status: "malformed",
+      configPath,
+      reason: "malformed JSON",
+    };
   }
+
+  const parsed = ConfigSchema.safeParse(value);
+  if (!parsed.success) {
+    return {
+      config: {},
+      status: "invalid",
+      configPath,
+      reason: "schema validation failed",
+    };
+  }
+
+  return { config: parsed.data, status: "ok", configPath };
 }
 
 export type JournalTag = {
@@ -451,4 +504,3 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
     },
   };
 }
-

package/src/plugin-disabled.test.ts

@@ -3,7 +3,9 @@ import { describe, expect, mock, test } from "bun:test";
 // Mock journal module with journal DISABLED — the control path.
 mock.module("./journal", () => ({
   loadConfig: async () => ({
-    journal: { enabled: false },
+    config: { journal: { enabled: false } },
+    status: "ok",
+    configPath: "/tmp/test-plugin-disabled/agent-memory.json",
   }),
   createJournalStore: () => ({}),
 }));
@@ -50,4 +52,19 @@ describe("plugin disabled path", () => {
     expect(plugin["chat.message"]).toBeDefined();
     expect(typeof plugin["chat.message"]).toBe("function");
   });
+
+  test("does not warn for an intentional disabled configuration", async () => {
+    const originalWarn = console.warn;
+    let warningCount = 0;
+    console.warn = () => {
+      warningCount += 1;
+    };
+
+    try {
+      await MemoryPlugin(stubInput);
+      expect(warningCount).toBe(0);
+    } finally {
+      console.warn = originalWarn;
+    }
+  });
 });

package/src/plugin.test.ts

@@ -1,10 +1,15 @@
 import { describe, expect, mock, test } from "bun:test";
+import type { LoadedConfig } from "./journal";
+
+let loadedConfig: LoadedConfig = {
+  config: { journal: { enabled: true } },
+  status: "ok" as const,
+  configPath: "/tmp/test-plugin/agent-memory.json",
+};
 
 // Mock journal module so we don't hit the real filesystem for config/journal
 mock.module("./journal", () => ({
-  loadConfig: async () => ({
-    journal: { enabled: true },
-  }),
+  loadConfig: async () => loadedConfig,
   createJournalStore: () => ({}),
 }));
 
@@ -19,6 +24,49 @@ import type { PluginInput } from "@opencode-ai/plugin";
 // Minimal stub: the plugin only reads `directory` from the input.
 const stubInput = { directory: "/tmp/test-plugin-regression" } as unknown as PluginInput;
 
+type FaultStatus = Exclude<LoadedConfig["status"], "ok">;
+
+const faultCases: Array<{
+  status: FaultStatus;
+  reason: string;
+  config: LoadedConfig["config"];
+}> = [
+  { status: "missing", reason: "file is missing", config: {} },
+  { status: "unreadable", reason: "read failed (EACCES)", config: {} },
+  { status: "malformed", reason: "malformed JSON", config: {} },
+  {
+    // A non-ok status must win even if the mocked config is truthy.
+    status: "invalid",
+    reason: "schema validation failed",
+    config: { journal: { enabled: true } },
+  },
+];
+
+const okCases: Array<{
+  name: string;
+  config: LoadedConfig["config"];
+  expectedToolCount: number;
+}> = [
+  {
+    name: "enabled",
+    config: { journal: { enabled: true } },
+    expectedToolCount: 3,
+  },
+  {
+    name: "disabled",
+    config: { journal: { enabled: false } },
+    expectedToolCount: 0,
+  },
+];
+
+function resetLoadedConfig(): void {
+  loadedConfig = {
+    config: { journal: { enabled: true } },
+    status: "ok",
+    configPath: "/tmp/test-plugin/agent-memory.json",
+  };
+}
+
 describe("plugin structure", () => {
   test("returns chat.message hook", async () => {
     const plugin = await MemoryPlugin(stubInput);
@@ -31,11 +79,51 @@ describe("plugin structure", () => {
     expect(plugin["experimental.chat.system.transform"]).toBeUndefined();
   });
 
-  test("registers journal tools when enabled", async () => {
-    const plugin = await MemoryPlugin(stubInput);
-    expect(plugin.tool).toBeDefined();
-    expect(plugin.tool!["journal_write"]).toBeDefined();
-    expect(plugin.tool!["journal_read"]).toBeDefined();
-    expect(plugin.tool!["journal_search"]).toBeDefined();
-  });
+  for (const testCase of faultCases) {
+    test(`warns and disables tools for ${testCase.status} config`, async () => {
+      loadedConfig = {
+        config: testCase.config,
+        status: testCase.status,
+        configPath: "/tmp/test-plugin/agent-memory.json",
+        reason: testCase.reason,
+      };
+      const originalWarn = console.warn;
+      const warnings: unknown[][] = [];
+      console.warn = (...args: unknown[]) => warnings.push(args);
+
+      try {
+        const plugin = await MemoryPlugin(stubInput);
+        expect(Object.keys(plugin.tool ?? {})).toHaveLength(0);
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0]?.[0]).toBe(
+          `[agent-memory] journal config /tmp/test-plugin/agent-memory.json: ${testCase.reason}; journal tools will NOT be registered`,
+        );
+      } finally {
+        console.warn = originalWarn;
+        resetLoadedConfig();
+      }
+    });
+  }
+
+  for (const testCase of okCases) {
+    test(`does not warn for valid ${testCase.name} config`, async () => {
+      loadedConfig = {
+        config: testCase.config,
+        status: "ok",
+        configPath: "/tmp/test-plugin/agent-memory.json",
+      };
+      const originalWarn = console.warn;
+      const warnings: unknown[][] = [];
+      console.warn = (...args: unknown[]) => warnings.push(args);
+
+      try {
+        const plugin = await MemoryPlugin(stubInput);
+        expect(Object.keys(plugin.tool ?? {})).toHaveLength(testCase.expectedToolCount);
+        expect(warnings).toHaveLength(0);
+      } finally {
+        console.warn = originalWarn;
+        resetLoadedConfig();
+      }
+    });
+  }
 });

package/src/plugin.ts

@@ -14,8 +14,16 @@ import { warmupEmbedder } from "./embeddings";
 
 export const MemoryPlugin: Plugin = async ({ directory }) => {
   // Journal: opt-in via ~/.config/opencode/agent-memory.json
-  const config = await loadConfig();
-  const journalEnabled = config.journal?.enabled === true;
+  const loadedConfig = await loadConfig();
+  const { config } = loadedConfig;
+
+  if (loadedConfig.status !== "ok") {
+    console.warn(
+      `[agent-memory] journal config ${loadedConfig.configPath}: ${loadedConfig.reason ?? loadedConfig.status}; journal tools will NOT be registered`,
+    );
+  }
+
+  const journalEnabled = loadedConfig.status === "ok" && config.journal?.enabled === true;
 
   // Mutable state updated by chat.message hook
   const journalCtx: JournalContext = {

package/src/tools.test.ts

@@ -2,9 +2,10 @@ import { describe, expect, test } from "bun:test";
 
 import { JournalRead, JournalSearch, JournalWrite } from "./tools";
 import type { JournalContext } from "./tools";
-import type { JournalStore, JournalTag } from "./journal";
+import type { JournalEntry, JournalStore } from "./journal";
 
-// Minimal mock store — tests only check description strings, not execute.
+// Minimal mock store — description tests use the default stubs, while search
+// output tests replace search with deterministic fixtures.
 const mockStore: JournalStore = {
   write: async () => {
     throw new Error("not implemented");
@@ -38,6 +39,31 @@ const READ_DESC = JournalRead(mockStore).description;
 const SEARCH_TOOL = JournalSearch(mockStore);
 const SEARCH_DESC = SEARCH_TOOL.description;
 
+function makeEntry(tags: string[]): JournalEntry {
+  return {
+    id: "20260101-000000-000",
+    title: "Retrieved entry",
+    project: "/tmp/test",
+    model: "test-model",
+    provider: "test-provider",
+    agent: "test-agent",
+    sessionId: "test-session",
+    created: new Date("2026-01-01T00:00:00.000Z"),
+    tags,
+    body: "Entry body",
+    filePath: "/tmp/test-entry.md",
+  };
+}
+
+async function executeSearch(result: Awaited<ReturnType<JournalStore["search"]>>): Promise<string> {
+  const store: JournalStore = {
+    ...mockStore,
+    search: async () => result,
+  };
+  const output = await JournalSearch(store).execute!({}, {} as never);
+  return String(output);
+}
+
 describe("journal_write description", () => {
   test("mentions append-only semantics", () => {
     expect(WRITE_DESC_NO_TAGS).toContain("append-only");
@@ -130,6 +156,66 @@ describe("journal_search description", () => {
   });
 });
 
+describe("journal_search tag inventory output", () => {
+  const manyTags = Array.from({ length: 21 }, (_, index) => `tag-${index + 1}`);
+  const exactlyTwentyTags = Array.from({ length: 20 }, (_, index) => `tag-${index + 1}`);
+
+  test("bounds large tag inventories while reporting their count", async () => {
+    const output = await executeSearch({
+      entries: [makeEntry(["entry-tag"])],
+      total: 1,
+      allTags: manyTags,
+    });
+
+    expect(output.split("\n")[1]).toBe("Tags in use: 21 (filter with tags=...)");
+    expect(output).not.toContain("tag-1");
+    expect(output).not.toContain("tag-21");
+  });
+
+  test("lists small tag inventories", async () => {
+    const output = await executeSearch({
+      entries: [makeEntry(["entry-tag"])],
+      total: 1,
+      allTags: ["perf", "debug"],
+    });
+
+    expect(output).toContain("Tags in use: perf, debug");
+  });
+
+  test("lists exactly 20 tags at the boundary", async () => {
+    const output = await executeSearch({
+      entries: [makeEntry(["entry-tag"])],
+      total: 1,
+      allTags: exactlyTwentyTags,
+    });
+
+    expect(output.split("\n")[1]).toBe(`Tags in use: ${exactlyTwentyTags.join(", ")}`);
+  });
+
+  test("omits the tag inventory line when no tags exist", async () => {
+    const output = await executeSearch({
+      entries: [],
+      total: 0,
+      allTags: [],
+    });
+
+    expect(output).toBe("No journal entries found.");
+  });
+
+  test("bounds large tag inventories for empty results too", async () => {
+    const output = await executeSearch({
+      entries: [],
+      total: 0,
+      allTags: manyTags,
+    });
+
+    expect(output).toContain("No journal entries found.");
+    expect(output.split("\n")[1]).toBe("Tags in use: 21 (filter with tags=...)");
+    expect(output).not.toContain("tag-1");
+    expect(output).not.toContain("tag-21");
+  });
+});
+
 // ─── Cross-tool invariants ───────────────────────────────────────────────────
 
 describe("cross-tool invariants", () => {

package/src/tools.ts

@@ -8,6 +8,21 @@ export type JournalContext = {
   provider: string;
 };
 
+const MAX_TAGS_TO_LIST = 20;
+
+function formatTagsInUse(allTags: readonly string[]): string {
+  if (allTags.length === 0) {
+    return "";
+  }
+
+  // Retrieved entries already show their own tags, so avoid repeating the
+  // entire global inventory when it grows beyond a useful size.
+  if (allTags.length > MAX_TAGS_TO_LIST) {
+    return `\nTags in use: ${allTags.length} (filter with tags=...)`;
+  }
+  return `\nTags in use: ${allTags.join(", ")}`;
+}
+
 export function JournalWrite(
   store: JournalStore,
   ctx: JournalContext,
@@ -115,20 +130,13 @@ export function JournalSearch(store: JournalStore) {
         offset: args.offset,
       });
 
+      const tagsLine = formatTagsInUse(result.allTags);
       if (result.entries.length === 0) {
-        const tagsLine =
-          result.allTags.length > 0
-            ? `\nTags in use: ${result.allTags.join(", ")}`
-            : "";
         return `No journal entries found.${tagsLine}`;
       }
 
       const offset = args.offset ?? 0;
       const header = `Found ${result.total} entries (showing ${offset + 1}–${offset + result.entries.length}):`;
-      const tagsLine =
-        result.allTags.length > 0
-          ? `\nTags in use: ${result.allTags.join(", ")}`
-          : "";
 
       const lines = result.entries.map((e) => {
         const tagStr =