@ghilteras/opencode-agent-memory 0.4.3 → 0.5.1

package/README.md

@@ -1,30 +1,26 @@
 # opencode-agent-memory
 
-**agent-memory for OpenCode — maintained by Ghilteras.** Originally based on [opencode-agent-memory](https://github.com/joshuadavidthomas/opencode-agent-memory) by Josh Thomas (MIT).
+> The maintained public home is
+> [`Ghilteras/opencode-agent-memory`](https://github.com/Ghilteras/opencode-agent-memory);
+> the public npm package is [`@ghilteras/opencode-agent-memory`](https://www.npmjs.com/package/@ghilteras/opencode-agent-memory).
+>
+> Originally created by Joshua David Thomas and licensed under the MIT license. Attribution preserved below; see License section.
 
-[Letta](https://letta.com)-style editable [memory blocks](https://docs.letta.com/guides/agents/memory-blocks/) for [OpenCode](https://opencode.ai).
+A journal-only memory plugin for [OpenCode](https://opencode.ai): an append-only, tagged journal with local semantic search.
 
 ## Experimental
 
-This plugin is experimental. The core idea - giving the agent persistent, self-editable memory blocks - is adapted from [Letta](https://github.com/letta-ai/letta). Specifially, the plugin follows Letta's [shared memory blocks](https://docs.letta.com/tutorials/shared-memory-blocks) pattern - the markdown files on disk are shared state that every OpenCode session can read and write.
+This plugin is experimental. It gives the agent one durable, self-maintained surface: a private journal. Entries are append-only - the agent writes new entries but never edits old ones.
 
-Think of it as AGENTS.md with a harness. OpenCode supports [rules](https://opencode.ai/docs/rules/) via `AGENTS.md` and custom instruction files - this plugin is similar in spirit, but adds structure (scoped blocks with metadata and size limits), dedicated tools for memory operations, and prompting that encourages the agent to actively maintain its own memory. The content is similar; the scaffolding around it is what's different.
-
-For background on the memory concept, see Letta's docs on [memory](https://docs.letta.com/guides/agents/memory/) and [memory blocks](https://docs.letta.com/guides/agents/memory-blocks/).
-
-## Maintenance & contributions
-
-This repository (`Ghilteras/opencode-agent-memory`, npm `@ghilteras/opencode-agent-memory`) is the **maintained home** of this plugin and its sole upstream. Issues and pull requests belong here.
-
-The historical origin (`joshuadavidthomas/opencode-agent-memory`) is reference-only: it is not a contribution target — do not open PRs, issues, or comments there, including courtesy closings.
+Think of it as a searchable sidecar to `AGENTS.md`. OpenCode supports [rules](https://opencode.ai/docs/rules/) via `AGENTS.md` and custom instruction files; those remain the place for eager, always-in-context facts. The journal is for everything else: insights, discoveries, decisions, and observations worth finding later, not carrying every turn.
 
 ## Features
 
-- **Persistent memory** - Information survives across sessions and context compaction
-- **Shared across sessions** - Global blocks shared across all projects, project blocks shared across sessions in that codebase
-- **Self-editing** - The agent can read and modify its own memory with dedicated tools
-- **System prompt injection** - Memory blocks appear in the system prompt, always in-context
-- **Journal** - Append-only entries with semantic search for capturing insights, decisions, and discoveries across sessions
+- **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
+- **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
 
@@ -36,159 +32,111 @@ Add to your OpenCode config (`~/.config/opencode/opencode.json`):
 
 ```json
 {
-  "plugin": ["@ghilteras/opencode-agent-memory"]
-}
-```
-
-Restart OpenCode and you're ready to go.
-
-Optionally, pin to a specific version for stability:
-
-```json
-{
-  "plugin": ["@ghilteras/opencode-agent-memory@0.4.1"]
+  "plugin": ["@ghilteras/opencode-agent-memory@0.5.0"]
 }
 ```
 
 OpenCode fetches unpinned plugins from npm on each startup; pinned versions are cached and require a manual version bump to update.
 
-### Local Development
-
-If you want to customize or contribute:
-
-```bash
-git clone https://github.com/Ghilteras/opencode-agent-memory ~/.config/opencode/opencode-agent-memory
-mkdir -p ~/.config/opencode/plugin
-ln -sf ~/.config/opencode/opencode-agent-memory/src/plugin.ts ~/.config/opencode/plugin/memory.ts
-```
-
-## Usage
-
-### Memory Tools
-
-The plugin gives the agent 3 tools for managing memory:
-
-| Tool | Description |
-|------|-------------|
-| `memory_list` | List available memory blocks (labels, descriptions, sizes) |
-| `memory_set` | Create or update a memory block (full overwrite) |
-| `memory_replace` | Replace a substring within a memory block |
-
-You interact with memory by editing the markdown files directly or asking the agent to update its memory.
-
-### Journal Tools
-
-When the journal is enabled, the agent gets 3 additional tools:
-
-| Tool | Description |
-|------|-------------|
-| `journal_write` | Write a new journal entry with title, body, and optional tags |
-| `journal_search` | Search entries semantically, filter by project or tags, with pagination |
-| `journal_read` | Read a specific journal entry by ID |
-
-Journal entries are append-only markdown files with YAML frontmatter, stored in `~/.config/opencode/journal/`. Each entry records which project, model, provider, agent, and session it was written from. Semantic search uses local embeddings ([paraphrase-multilingual-MiniLM-L12-v2](https://huggingface.co/Xenova/paraphrase-multilingual-MiniLM-L12-v2), 384d, multilingual EN/IT) - no data leaves your machine.
-
-Embedding files (`.embedding`, written alongside each entry) use a versioned format (`{ v: 2, model, dimension, vector }`) so that stale or mismatched embeddings are detected: if the stored dimension doesn't match the current model, the entry falls back to text matching instead of failing the search. Legacy bare-array embeddings from v0.3.x remain readable.
-
-**Search performance (v0.4.1–v0.4.2)**: `journal_search` keeps an in-memory index per store instance. Entries are re-read only when their file changed — fingerprinted on both the entry `.md` and its `.embedding` sidecar (mtime + size), so regenerating or deleting a sidecar is picked up on the next search without a restart. The embedding model is warmed up in the background at plugin init when the journal is enabled (respecting `cacheDir`), so the first search after a restart doesn't pay the cold model-load cost. Since v0.4.2, a query whose text matches an entry's title (in either direction, case-insensitive) is guaranteed a high score floor (0.75), so title-based pointers remain retrievable even for entries with long bodies.
+## Journal
 
-### cacheDir Configuration
-
-By default the transformers.js model cache lives in the default location (`~/.cache/huggingface`). You can relocate it by setting `cacheDir` at the top level of `~/.config/opencode/agent-memory.json`:
+The journal is **opt-in**. Enable it in `~/.config/opencode/agent-memory.json`:
 
 ```json
 {
-  "cacheDir": "/home/angelo/.cache/opencode/memory-model",
   "journal": {
     "enabled": true
   }
 }
 ```
 
-### Default Blocks
+With the journal disabled the plugin registers **no tools**.
 
-Three blocks are seeded on first run:
+### Tools
 
-| Block | Scope | Purpose |
-|-------|-------|---------|
-| `persona` | global | How the agent should behave and respond |
-| `human` | global | Details about you (preferences, habits, constraints) |
-| `project` | project | Codebase-specific knowledge (commands, architecture, conventions) |
+When the journal is enabled, the agent gets 3 tools:
 
-These are just starting points. Create whatever blocks make sense for your workflow - `debugging-notes`, `api-preferences`, `learned-patterns`, etc.
+| Tool | Description |
+|------|-------------|
+| `journal_write` | Write a new append-only entry (title, body, optional tags) |
+| `journal_search` | Search entries semantically, filter by project or tags, with pagination |
+| `journal_read` | Read a specific journal entry by ID |
 
-### Memory Locations
+### Entry format
 
-- **Global blocks**: `~/.config/opencode/memory/*.md`
-- **Project blocks**: `.opencode/memory/*.md` (auto-gitignored)
+Entries are markdown files with YAML frontmatter in `~/.config/opencode/journal/`. Each entry records its project, model, provider, agent, session, creation time, and tags, followed by the body:
 
-### Block Format
+```markdown
+---
+title: "Reasoning-pruner wiring"
+created: 2026-09-21T18:16:11.300Z
+project: /home/angelo/homelab-config
+model: deepseek-v4.1-flash
+provider: opencode-go
+agent: executor
+session_id: ses_...
+tags: [plugin, wiring]
+---
 
-Each block is a markdown file with YAML frontmatter:
+Body text...
+```
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `label` | string | filename | Unique identifier for the block |
-| `description` | string | generic | Tells the agent how to use this block |
-| `limit` | integer | 5000 | Maximum characters allowed |
-| `read_only` | boolean | false | Prevent agent from modifying |
+### Semantic search
 
-All fields have defaults for graceful degradation, but `description` is essential - without it, the agent gets a generic fallback and won't know how to use the block effectively. See Letta's docs on [the importance of the description field](https://docs.letta.com/guides/agents/memory-blocks/#the-importance-of-the-description-field).
+Search uses local embeddings ([paraphrase-multilingual-MiniLM-L12-v2](https://huggingface.co/Xenova/paraphrase-multilingual-MiniLM-L12-v2), 384d, multilingual EN/IT) - no data leaves your machine. An `.embedding` sidecar is written next to each entry in a versioned format (`{ v: 2, model, dimension, vector }`). The search gate is a **dimension** check: an entry whose recorded `dimension` differs from the plugin's expected dimension is not cosine-compared - it falls back to text matching instead of failing the search. Legacy bare-array embeddings from v0.3.x remain readable.
 
-### Journal Configuration
+### Suggested tags
 
-The journal is opt-in. Enable it in `~/.config/opencode/agent-memory.json`:
+Tags are free-form strings - the agent can use any tag, not just the suggested ones. You can suggest tags to guide its classification:
 
 ```json
 {
   "journal": {
-    "enabled": true
+    "enabled": true,
+    "tags": [
+      { "name": "perf", "description": "Performance optimization work" },
+      { "name": "debugging", "description": "Debugging sessions and findings" }
+    ]
   }
 }
 ```
 
-You can optionally suggest tags to guide the agent's classification:
+Suggested tag **names** (not their descriptions) appear in the `journal_write` tool description as guidance.
+
+### cacheDir
+
+By default the transformers.js model cache lives in the default location (`~/.cache/huggingface`). Relocate it with `cacheDir` at the top level of `~/.config/opencode/agent-memory.json`:
 
 ```json
 {
+  "cacheDir": "/home/angelo/.cache/opencode/memory-model",
   "journal": {
-    "enabled": true,
-    "tags": [
-      { "name": "perf", "description": "Performance optimization work" },
-      { "name": "debugging", "description": "Debugging sessions and findings" }
-    ]
+    "enabled": true
   }
 }
 ```
 
-Tags are free-form strings - the agent can use any tag, not just the suggested ones. Suggested tags appear in the system prompt to provide guidance.
-
-## Inspiration
+## Upgrading from 0.4.x
 
-The memory architecture and philosophical framing are adapted from [Letta](https://github.com/letta-ai/letta) (formerly MemGPT), a framework for building LLM agents with editable long-term memory.
+Memory blocks and their tools (`memory_list`, `memory_set`, `memory_replace`) are **removed**. Blocks are no longer read, written, or injected into the system prompt; the plugin ships only the journal.
 
-Also worth exploring: [private-journal-mcp](https://github.com/obra/private-journal-mcp) by Jesse Vincent, which gives Claude a private journaling capability to process feelings and thoughts. His [blog post](https://blog.fsck.com/2025/05/28/dear-diary-the-user-asked-me-if-im-alive/) about it explores similar territory around AI self-reflection and persistent inner experience.
+Existing `~/.config/opencode/memory/` and `.opencode/memory/` directories are **not deleted** by the upgrade, but they are no longer read or written. Move anything still needed to `MEMORY.md` / `AGENTS.md` / `TOOLS.md`, or record it as a journal entry.
 
-## Contributing
+## Compatibility & Troubleshooting
 
-Contributions are welcome! Here's how to set up for development:
+- **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.
+- **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.
 
-```bash
-git clone https://github.com/Ghilteras/opencode-agent-memory
-cd opencode-agent-memory
-bun install
-```
-
-Then symlink the plugin to your OpenCode config:
+## Inspiration
 
-```bash
-mkdir -p ~/.config/opencode/plugin
-ln -sf "$(pwd)/src/plugin.ts" ~/.config/opencode/plugin/memory.ts
-```
+The journal concept is inspired by [private-journal-mcp](https://github.com/obra/private-journal-mcp) by Jesse Vincent.
 
 ## License
 
-opencode-agent-memory is licensed under the MIT license. See the [`LICENSE`](LICENSE) file for more information.
+Originally created by Joshua David Thomas and licensed under the MIT license. Maintained by Angelo Pantano. See the [`LICENSE`](LICENSE) file for full terms.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ghilteras/opencode-agent-memory",
-  "version": "0.4.3",
-  "description": "Letta-style editable memory blocks + journal for OpenCode (maintained fork of opencode-agent-memory).",
+  "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",
   "repository": {

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

@@ -0,0 +1,41 @@
+import { describe, expect, mock, test } from "bun:test";
+
+// Mock journal module so we don't hit the real filesystem for config/journal
+mock.module("./journal", () => ({
+  loadConfig: async () => ({
+    journal: { enabled: true },
+  }),
+  createJournalStore: () => ({}),
+}));
+
+// Mock embeddings to avoid model download
+mock.module("./embeddings", () => ({
+  warmupEmbedder: async () => {},
+}));
+
+import { MemoryPlugin } from "./plugin";
+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 structure", () => {
+  test("returns chat.message hook", async () => {
+    const plugin = await MemoryPlugin(stubInput);
+    expect(plugin["chat.message"]).toBeDefined();
+    expect(typeof plugin["chat.message"]).toBe("function");
+  });
+
+  test("does NOT return experimental.chat.system.transform hook", async () => {
+    const plugin = await MemoryPlugin(stubInput);
+    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();
+  });
+});

package/src/plugin.ts

@@ -1,34 +1,18 @@
 import type { Plugin, ToolDefinition } from "@opencode-ai/plugin";
 
-import { existsSync } from "node:fs";
-
 import {
-  buildJournalSystemNote,
   createJournalStore,
   loadConfig,
 } from "./journal";
-import { createMemoryStore } from "./memory";
-import { renderMemoryBlocks } from "./prompt";
 import {
   JournalRead,
   JournalSearch,
   JournalWrite,
-  MemoryList,
-  MemoryReplace,
-  MemorySet,
 } from "./tools";
 import type { JournalContext } from "./tools";
 import { warmupEmbedder } from "./embeddings";
 
 export const MemoryPlugin: Plugin = async ({ directory }) => {
-  const store = createMemoryStore(directory);
-  // Only seed into a directory that still exists. OpenCode walks a persisted instance list
-  // at startup and bootstraps every entry; because ensureSeed() creates
-  // <directory>/.opencode/memory recursively, a stale entry made this plugin re-create
-  // directories the operator had deliberately deleted. A missing directory means the
-  // instance is gone, not new, so there is nothing to seed.
-  if (existsSync(directory)) await store.ensureSeed();
-
   // Journal: opt-in via ~/.config/opencode/agent-memory.json
   const config = await loadConfig();
   const journalEnabled = config.journal?.enabled === true;
@@ -41,7 +25,6 @@ export const MemoryPlugin: Plugin = async ({ directory }) => {
   };
 
   let journalTools: Record<string, ToolDefinition> = {};
-  let journalSystemNote = "";
 
   if (journalEnabled) {
     const journalStore = createJournalStore(undefined, config.cacheDir);
@@ -49,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 {
@@ -64,27 +46,7 @@ export const MemoryPlugin: Plugin = async ({ directory }) => {
       }
     },
 
-    "experimental.chat.system.transform": async (_input, output) => {
-      const blocks = await store.listBlocks("all");
-      const xml = renderMemoryBlocks(blocks);
-      if (!xml) return;
-
-      // Append memory blocks at the END of the system prompt (stable tail).
-      // On opencode 1.18.x the hook receives a 1-element array, so splice(1) and push are byte-identical;
-      // push is correct under both current and future (V2 runner) array shapes and keeps the static
-      // provider/instructions prefix cacheable.
-      output.system.push(xml);
-
-      // Append journal instructions at the end (preserves memory block cache)
-      if (journalSystemNote) {
-        output.system.push(journalSystemNote);
-      }
-    },
-
     tool: {
-      memory_list: MemoryList(store),
-      memory_set: MemorySet(store),
-      memory_replace: MemoryReplace(store),
       ...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);
+  });
+});