@ghilteras/opencode-agent-memory 0.5.0 → 0.5.1

package/README.md

@@ -19,7 +19,7 @@ Think of it as a searchable sidecar to `AGENTS.md`. OpenCode supports [rules](ht
 - **Append-only journal** - Entries survive across sessions and context compaction
 - **Local semantic search** - Find entries by meaning, not just keywords
 - **Metadata on every entry** - Project, model, provider, agent, session, timestamp, tags
-- **Bounded system prompt note** - A short journal-instructions note is injected while the journal is enabled
+- **Guidance in tool descriptions** - Journal usage guidance lives in the descriptions of the journal tools, so an agent sees it only when it is allowed to call them
 - **No data leaves the machine** - Embeddings run locally
 
 ## Requirements
@@ -50,7 +50,7 @@ The journal is **opt-in**. Enable it in `~/.config/opencode/agent-memory.json`:
 }
 ```
 
-With the journal disabled the plugin registers **no tools** and injects nothing.
+With the journal disabled the plugin registers **no tools**.
 
 ### Tools
 
@@ -101,7 +101,7 @@ Tags are free-form strings - the agent can use any tag, not just the suggested o
 }
 ```
 
-Suggested tags appear in the system prompt as guidance.
+Suggested tag **names** (not their descriptions) appear in the `journal_write` tool description as guidance.
 
 ### cacheDir
 
@@ -126,8 +126,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 and injects nothing.
+- **Journal is opt-in.** You must explicitly enable it in `~/.config/opencode/agent-memory.json`; with it disabled the plugin 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.
 
 ## Inspiration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghilteras/opencode-agent-memory",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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.ts

@@ -452,21 +452,3 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
   };
 }
 
-export function buildJournalSystemNote(
-  tags?: readonly JournalTag[],
-): string {
-  const tagSection =
-    tags && tags.length > 0
-      ? `\n\nSuggested tags:\n${tags.map((t) => `- ${t.name}: ${t.description}`).join("\n")}`
-      : "";
-
-  return `<journal_instructions>
-You have access to a private journal. Use it to record thoughts, discoveries, and decisions as you work.
-Tags are free-form strings — use them to classify entries however makes sense.${tagSection}
-
-Before starting complex tasks, search the journal for relevant past context.
-Journal entries are append-only: you write new entries but never edit old ones.
-Use journal_search to find past entries semantically, and journal_read to read a specific entry.
-The journal is global across all projects but each entry records which project it was written from.
-</journal_instructions>`;
-}

package/src/plugin-disabled.test.ts

@@ -0,0 +1,53 @@
+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 },
+  }),
+  createJournalStore: () => ({}),
+}));
+
+// Mock embeddings to avoid model download
+mock.module("./embeddings", () => ({
+  warmupEmbedder: async () => {},
+}));
+
+import { MemoryPlugin } from "./plugin";
+import type { PluginInput } from "@opencode-ai/plugin";
+
+const stubInput = { directory: "/tmp/test-plugin-disabled" } as unknown as PluginInput;
+
+describe("plugin disabled path", () => {
+  test("registers zero tools when journal is disabled", async () => {
+    const plugin = await MemoryPlugin(stubInput);
+    // tool should be undefined or an empty object
+    if (plugin.tool) {
+      expect(Object.keys(plugin.tool)).toHaveLength(0);
+    } else {
+      expect(plugin.tool).toBeUndefined();
+    }
+  });
+
+  test("produces no guidance text when disabled", async () => {
+    const plugin = await MemoryPlugin(stubInput);
+    // There should be no system transform hook injecting guidance
+    expect(plugin["experimental.chat.system.transform"]).toBeUndefined();
+    // Tool definitions (if any exist as empty object) must not contain
+    // any description with journal guidance keywords
+    if (plugin.tool) {
+      for (const def of Object.values(plugin.tool)) {
+        const desc = (def as { description?: string }).description ?? "";
+        expect(desc).not.toMatch(/append-only|journal|search.*entry/i);
+      }
+    }
+  });
+
+  test("chat.message hook is still present when disabled", async () => {
+    const plugin = await MemoryPlugin(stubInput);
+    // The chat.message hook updates model/provider context — it should
+    // still be present even when journal is disabled.
+    expect(plugin["chat.message"]).toBeDefined();
+    expect(typeof plugin["chat.message"]).toBe("function");
+  });
+});

package/src/plugin.test.ts

@@ -1,16 +1,11 @@
 import { describe, expect, mock, test } from "bun:test";
 
 // Mock journal module so we don't hit the real filesystem for config/journal
-const JOURNAL_NOTE = `<journal_instructions>
-You have access to a private journal.
-</journal_instructions>`;
-
 mock.module("./journal", () => ({
   loadConfig: async () => ({
     journal: { enabled: true },
   }),
   createJournalStore: () => ({}),
-  buildJournalSystemNote: () => JOURNAL_NOTE,
 }));
 
 // Mock embeddings to avoid model download
@@ -24,43 +19,23 @@ 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;
 
-describe("plugin transform hook — journal regression", () => {
-  test("journal system note is injected when enabled and no blocks present", async () => {
+describe("plugin structure", () => {
+  test("returns chat.message hook", async () => {
     const plugin = await MemoryPlugin(stubInput);
-
-    const transform = plugin["experimental.chat.system.transform"];
-    expect(transform).toBeDefined();
-
-    const output = { system: [] as string[] };
-    // The chat.message hook expects a model param; the transform hook does not use it.
-    // Pass a minimal mock for the transform signature.
-    await (transform as Function)({}, output);
-
-    // The journal note MUST be present — this is the core regression check.
-    // With the old early-return (`if (!xml) return;`), when renderMemoryBlocks
-    // returned "" (no blocks), the entire transform returned before pushing
-    // journalSystemNote, silently disabling the journal.
-    expect(output.system).toContain(JOURNAL_NOTE);
+    expect(plugin["chat.message"]).toBeDefined();
+    expect(typeof plugin["chat.message"]).toBe("function");
   });
 
-  test("journal system note is pushed exactly once", async () => {
+  test("does NOT return experimental.chat.system.transform hook", async () => {
     const plugin = await MemoryPlugin(stubInput);
-
-    const transform = plugin["experimental.chat.system.transform"];
-    const output = { system: [] as string[] };
-    await (transform as Function)({}, output);
-
-    const count = output.system.filter((s) => s === JOURNAL_NOTE).length;
-    expect(count).toBe(1);
+    expect(plugin["experimental.chat.system.transform"]).toBeUndefined();
   });
 
-  test("empty system array is populated (not left untouched)", async () => {
+  test("registers journal tools when enabled", async () => {
     const plugin = await MemoryPlugin(stubInput);
-
-    const transform = plugin["experimental.chat.system.transform"];
-    const output = { system: [] as string[] };
-    await (transform as Function)({}, output);
-
-    expect(output.system.length).toBeGreaterThan(0);
+    expect(plugin.tool).toBeDefined();
+    expect(plugin.tool!["journal_write"]).toBeDefined();
+    expect(plugin.tool!["journal_read"]).toBeDefined();
+    expect(plugin.tool!["journal_search"]).toBeDefined();
   });
 });

package/src/plugin.ts

@@ -1,7 +1,6 @@
 import type { Plugin, ToolDefinition } from "@opencode-ai/plugin";
 
 import {
-  buildJournalSystemNote,
   createJournalStore,
   loadConfig,
 } from "./journal";
@@ -26,7 +25,6 @@ export const MemoryPlugin: Plugin = async ({ directory }) => {
   };
 
   let journalTools: Record<string, ToolDefinition> = {};
-  let journalSystemNote = "";
 
   if (journalEnabled) {
     const journalStore = createJournalStore(undefined, config.cacheDir);
@@ -34,11 +32,10 @@ export const MemoryPlugin: Plugin = async ({ directory }) => {
     // first-init-wins singleton caches to the correct directory.
     void warmupEmbedder(config.cacheDir).catch(() => {});
     journalTools = {
-      journal_write: JournalWrite(journalStore, journalCtx),
+      journal_write: JournalWrite(journalStore, journalCtx, config.journal?.tags),
       journal_read: JournalRead(journalStore),
       journal_search: JournalSearch(journalStore),
     };
-    journalSystemNote = buildJournalSystemNote(config.journal?.tags);
   }
 
   return {
@@ -49,16 +46,6 @@ export const MemoryPlugin: Plugin = async ({ directory }) => {
       }
     },
 
-    "experimental.chat.system.transform": async (_input, output) => {
-      // Inject journal instructions unconditionally when enabled.
-      // Previous versions returned early when no memory blocks were present,
-      // which also skipped the journal note — a regression-class bug that
-      // silently disabled the journal entirely once blocks were removed.
-      if (journalSystemNote) {
-        output.system.push(journalSystemNote);
-      }
-    },
-
     tool: {
       ...journalTools,
     },

package/src/tools.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, test } from "bun:test";
+
+import { JournalRead, JournalSearch, JournalWrite } from "./tools";
+import type { JournalContext } from "./tools";
+import type { JournalStore, JournalTag } from "./journal";
+
+// Minimal mock store — tests only check description strings, not execute.
+const mockStore: JournalStore = {
+  write: async () => {
+    throw new Error("not implemented");
+  },
+  read: async () => {
+    throw new Error("not implemented");
+  },
+  search: async () => {
+    throw new Error("not implemented");
+  },
+};
+
+const mockCtx: JournalContext = {
+  directory: "/tmp/test",
+  model: "test-model",
+  provider: "test-provider",
+};
+
+// ─── Tool description tests ───────────────────────────────────────────────
+// These assert semantic properties of the description strings: that guidance
+// content is present, that stale/hallucinated text is absent, and that structural
+// invariants hold.  They use substring/regex assertions, so intra-sentence
+// rewording is tolerated; only content-level regressions trip them.
+
+const WRITE_DESC_NO_TAGS = JournalWrite(mockStore, mockCtx).description;
+const WRITE_DESC_WITH_TAGS = JournalWrite(mockStore, mockCtx, [
+  { name: "perf", description: "Performance optimization" },
+  { name: "debug", description: "Debugging sessions" },
+]).description;
+const READ_DESC = JournalRead(mockStore).description;
+const SEARCH_TOOL = JournalSearch(mockStore);
+const SEARCH_DESC = SEARCH_TOOL.description;
+
+describe("journal_write description", () => {
+  test("mentions append-only semantics", () => {
+    expect(WRITE_DESC_NO_TAGS).toContain("append-only");
+  });
+
+  test("explains that entries cannot be edited", () => {
+    expect(WRITE_DESC_NO_TAGS).toMatch(/never edit|cannot be (edited|modified)/i);
+  });
+
+  test("documents tag format", () => {
+    expect(WRITE_DESC_NO_TAGS).toMatch(/tags/i);
+    expect(WRITE_DESC_NO_TAGS).toMatch(/comma.separated/i);
+  });
+
+  test("contains no dynamic or timestamped content", () => {
+    // A static description must not embed a date or ISO timestamp
+    expect(WRITE_DESC_NO_TAGS).not.toMatch(/\d{4}-\d{2}-\d{2}T/);
+  });
+
+  test("mentions the journal is for recording insights", () => {
+    expect(WRITE_DESC_NO_TAGS).toMatch(/insight|discovery|decision|observation/i);
+  });
+
+  test("does not include suggested tags when none provided", () => {
+    expect(WRITE_DESC_NO_TAGS).not.toMatch(/suggested tags/i);
+  });
+
+  test("includes suggested tags when provided", () => {
+    expect(WRITE_DESC_WITH_TAGS).toMatch(/suggested tags/i);
+    expect(WRITE_DESC_WITH_TAGS).toContain("perf");
+    expect(WRITE_DESC_WITH_TAGS).toContain("debug");
+  });
+
+  test("suggested tags are tag names only, not descriptions", () => {
+    expect(WRITE_DESC_WITH_TAGS).toContain("perf");
+    expect(WRITE_DESC_WITH_TAGS).toContain("debug");
+    // Tag descriptions should NOT appear in the tool description
+    expect(WRITE_DESC_WITH_TAGS).not.toContain("Performance optimization");
+    expect(WRITE_DESC_WITH_TAGS).not.toContain("Debugging sessions");
+  });
+});
+
+describe("journal_read description", () => {
+  test("mentions reading a specific entry by ID", () => {
+    expect(READ_DESC).toMatch(/by.*ID/i);
+  });
+
+  test("does not contain write-only guidance", () => {
+    // Write-scoping guidance (append-only, cannot be edited) belongs only in
+    // journal_write's description.  An agent with read-but-not-write would
+    // see this guidance without the ability to act on it.
+    expect(READ_DESC).not.toMatch(/append.only|cannot be (edited|modified)/i);
+  });
+
+  test("contains no dynamic or timestamped content", () => {
+    expect(READ_DESC).not.toMatch(/\d{4}-\d{2}-\d{2}T/);
+  });
+});
+
+describe("journal_search description", () => {
+  test("mentions searching semantically", () => {
+    expect(SEARCH_DESC).toMatch(/semantic|similarity|meaning/i);
+  });
+
+  test("mentions that filters can be combined", () => {
+    expect(SEARCH_DESC).toMatch(/filter/i);
+  });
+
+  test("documents the project filter argument", () => {
+    // The project filter is documented via the tool's args schema, not the
+    // description prose.  Assert the arg exists so a schema regression is caught.
+    expect(SEARCH_TOOL.args).toBeDefined();
+    expect(SEARCH_TOOL.args!.project).toBeDefined();
+  });
+
+  test("mentions pagination (offset)", () => {
+    expect(SEARCH_DESC).toMatch(/offset|paginate/i);
+  });
+
+  test("mentions the journal is global across projects", () => {
+    expect(SEARCH_DESC).toMatch(/global.*project|across.*project/i);
+  });
+
+  test("advises searching before complex tasks", () => {
+    expect(SEARCH_DESC).toMatch(/complex task|before start/i);
+  });
+
+  test("contains no dynamic or timestamped content", () => {
+    expect(SEARCH_DESC).not.toMatch(/\d{4}-\d{2}-\d{2}T/);
+  });
+});
+
+// ─── Cross-tool invariants ───────────────────────────────────────────────────
+
+describe("cross-tool invariants", () => {
+  test("no description mentions another journal tool by name", () => {
+    const toolNames = ["journal_search", "journal_read", "journal_write"];
+    for (const name of toolNames) {
+      const desc =
+        name === "journal_write"
+          ? WRITE_DESC_NO_TAGS
+          : name === "journal_read"
+            ? READ_DESC
+            : SEARCH_DESC;
+      const others = toolNames.filter((n) => n !== name);
+      for (const other of others) {
+        expect(desc).not.toContain(other);
+      }
+    }
+  });
+
+  test("all descriptions are non-empty strings", () => {
+    expect(typeof WRITE_DESC_NO_TAGS).toBe("string");
+    expect(WRITE_DESC_NO_TAGS.length).toBeGreaterThan(0);
+    expect(typeof READ_DESC).toBe("string");
+    expect(READ_DESC.length).toBeGreaterThan(0);
+    expect(typeof SEARCH_DESC).toBe("string");
+    expect(SEARCH_DESC.length).toBeGreaterThan(0);
+  });
+
+  test("no description contains the retired invitation phrase", () => {
+    const retired = "record thoughts, discoveries, and decisions as you work";
+    expect(WRITE_DESC_NO_TAGS).not.toContain(retired);
+    expect(READ_DESC).not.toContain(retired);
+    expect(SEARCH_DESC).not.toContain(retired);
+  });
+});

package/src/tools.ts

@@ -1,6 +1,6 @@
 import { tool } from "@opencode-ai/plugin";
 
-import type { JournalStore } from "./journal";
+import type { JournalStore, JournalTag } from "./journal";
 
 export type JournalContext = {
   directory: string;
@@ -11,12 +11,19 @@ export type JournalContext = {
 export function JournalWrite(
   store: JournalStore,
   ctx: JournalContext,
+  tags?: readonly JournalTag[],
 ) {
+  const suggestedTags =
+    tags && tags.length > 0
+      ? ` Suggested tags: ${tags.map((t) => t.name).join(", ")}.`
+      : "";
   return tool({
     description:
-      "Write a new journal entry. Use this to capture insights, technical discoveries, " +
-      "design decisions, observations, or reflections. Entries are append-only and cannot be edited. " +
-      "Tags are optional comma-separated names, e.g. \"perf, debugging\".",
+      "Write a new append-only journal entry. Use this to capture insights, technical discoveries, " +
+      "design decisions, observations, or reflections. " +
+      "Entries are append-only: you write new entries but never edit old ones. " +
+      "Tags are optional comma-separated names, e.g. \"perf, debugging\"." +
+      suggestedTags,
     args: {
       title: tool.schema.string(),
       body: tool.schema.string(),
@@ -82,7 +89,9 @@ export function JournalSearch(store: JournalStore) {
     description:
       "Search journal entries using semantic similarity. Returns matching entries " +
       "sorted by relevance. All filters are optional and combined with AND logic. " +
-      "Use with no arguments to list recent entries. Use offset to paginate.",
+      "Use with no arguments to list recent entries. Use offset to paginate. " +
+      "Before starting complex tasks, search the journal for relevant past context. " +
+      "The journal is global across all projects but each entry records which project it was written from.",
     args: {
       text: tool.schema.string().optional(),
       project: tool.schema.string().optional(),