@ghilteras/opencode-agent-memory 0.4.2 → 0.5.0

package/README.md

@@ -1,31 +1,26 @@
 # opencode-agent-memory
 
-> **Fork notice**: This is the maintained fork `@ghilteras/opencode-agent-memory` v0.4.2 of
-> [opencode-agent-memory](https://github.com/joshuadavidthomas/opencode-agent-memory)
-> (joshuadavidthomas, MIT). v0.4.2 adds a title-anchor floor so title queries are not diluted by long bodies. This release adopts the "proper timestamps without cache
-> busting" design (per-block `modified_at` frontmatter, remove the volatile
-> `memory_metadata` block, append memory XML at the end of the system prompt) derived
-> from the Annakan/draxxris fork plan. Upstream PR #20 (freeze metadata timestamps) is
-> superseded by the stronger per-block design and remains open upstream. v0.4.0 swaps
-> the embedding model to a multilingual one and adds a versioned embedding format. v0.4.1 makes journal search fast (in-memory per-store index, embedding-model warmup at init) and fixes the js-yaml import for ESM runtimes.
+> 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/).
+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
+- **Bounded system prompt note** - A short journal-instructions note is injected while the journal is enabled
+- **No data leaves the machine** - Embeddings run locally
 
 ## Requirements
 
@@ -37,159 +32,110 @@ 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.
-
-### cacheDir Configuration
+## Journal
 
-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** and injects nothing.
 
-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 tags appear in the system prompt 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 and injects nothing.
+- **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.
 
-```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.2",
-  "description": "Letta-style editable memory blocks + journal for OpenCode (maintained fork of opencode-agent-memory).",
+  "version": "0.5.0",
+  "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/frontmatter.ts

@@ -1,8 +1,23 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { randomUUID } from "node:crypto";
 
 import * as yaml from "js-yaml";
 
+const fileLocks = new Map<string, Promise<unknown>>();
+
+export function withFileLock<T>(filePath: string, fn: () => Promise<T>): Promise<T> {
+  const key = path.resolve(filePath);
+  const prior = fileLocks.get(key) ?? Promise.resolve();
+  const result = prior.then(fn, fn);           // run fn whatever the prior outcome was
+  const settled = result.then(() => undefined, () => undefined);  // never rejects
+  fileLocks.set(key, settled);
+  settled.then(() => {
+    if (fileLocks.get(key) === settled) fileLocks.delete(key);
+  });
+  return result;
+}
+
 export function splitFrontmatter(text: string): {
   frontmatterText: string | undefined;
   body: string;
@@ -40,8 +55,13 @@ export async function atomicWriteFile(
 ): Promise<void> {
   const tempPath = path.join(
     path.dirname(filePath),
-    `.${path.basename(filePath)}.tmp`,
+    `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`,
   );
-  await fs.writeFile(tempPath, content, "utf-8");
-  await fs.rename(tempPath, filePath);
+  try {
+    await fs.writeFile(tempPath, content, "utf-8");
+    await fs.rename(tempPath, filePath);
+  } catch (err) {
+    await fs.rm(tempPath, { force: true }).catch(() => {});
+    throw err;
+  }
 }

package/src/plugin.test.ts

@@ -0,0 +1,66 @@
+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
+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 transform hook — journal regression", () => {
+  test("journal system note is injected when enabled and no blocks present", 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);
+  });
+
+  test("journal system note is pushed exactly once", 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);
+  });
+
+  test("empty system array is populated (not left untouched)", 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);
+  });
+});

package/src/plugin.ts

@@ -5,23 +5,15 @@ import {
   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);
-  await store.ensureSeed();
-
   // Journal: opt-in via ~/.config/opencode/agent-memory.json
   const config = await loadConfig();
   const journalEnabled = config.journal?.enabled === true;
@@ -58,26 +50,16 @@ 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)
+      // 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: {
-      memory_list: MemoryList(store),
-      memory_set: MemorySet(store),
-      memory_replace: MemoryReplace(store),
       ...journalTools,
     },
   };

package/src/tools.ts

@@ -1,71 +1,6 @@
 import { tool } from "@opencode-ai/plugin";
 
 import type { JournalStore } from "./journal";
-import type { MemoryScope, MemoryStore } from "./memory";
-
-export function MemoryList(store: MemoryStore) {
-  return tool({
-    description: "List available memory blocks (labels, descriptions, sizes).",
-    args: {
-      scope: tool.schema.enum(["all", "global", "project"]).optional(),
-    },
-    async execute(args) {
-      // Default to "all" for list (show everything)
-      const scope = (args.scope ?? "all") as MemoryScope | "all";
-      const blocks = await store.listBlocks(scope);
-      if (blocks.length === 0) {
-        return "No memory blocks found.";
-      }
-
-      return blocks
-        .map(
-          (b) =>
-            `${b.scope}:${b.label}\n  read_only=${b.readOnly} chars=${b.value.length}/${b.limit}\n  ${b.description}`,
-        )
-        .join("\n\n");
-    },
-  });
-}
-
-export function MemorySet(store: MemoryStore) {
-  return tool({
-    description: "Create or update a memory block (full overwrite).",
-    args: {
-      label: tool.schema.string(),
-      scope: tool.schema.enum(["global", "project"]).optional(),
-      value: tool.schema.string(),
-      description: tool.schema.string().optional(),
-      limit: tool.schema.number().int().positive().optional(),
-    },
-    async execute(args) {
-      // Default to "project" for mutations (safer default)
-      const scope = (args.scope ?? "project") as MemoryScope;
-      const ts = await store.setBlock(scope, args.label, args.value, {
-        description: args.description,
-        limit: args.limit,
-      });
-      return `Updated memory block ${scope}:${args.label} at ${ts.toISOString()}.`;
-    },
-  });
-}
-
-export function MemoryReplace(store: MemoryStore) {
-  return tool({
-    description: "Replace a substring within a memory block.",
-    args: {
-      label: tool.schema.string(),
-      scope: tool.schema.enum(["global", "project"]).optional(),
-      oldText: tool.schema.string(),
-      newText: tool.schema.string(),
-    },
-    async execute(args) {
-      // Default to "project" for mutations (safer default)
-      const scope = (args.scope ?? "project") as MemoryScope;
-      const ts = await store.replaceInBlock(scope, args.label, args.oldText, args.newText);
-      return `Updated memory block ${scope}:${args.label} at ${ts.toISOString()}.`;
-    },
-  });
-}
 
 export type JournalContext = {
   directory: string;

package/src/letta.ts

@@ -1,47 +0,0 @@
-/**
- * Vendored content from Letta.
- *
- * This module contains the philosophical framing and defaults from Letta
- * that guide LLM behavior around memory management.
- *
- * @see https://github.com/letta-ai/letta
- */
-
-export const MEMORY_INSTRUCTIONS = `<memory_instructions>
-<memory_editing>
-Older AI models had no concept of persistent memory; they were only able to access their initial instructions and a limited context window of chat conversation with a user (their "active memory").
-This meant that when conversations exceeded a certain length, they would overflow and old messages were permanently lost (the AI would have no knowledge of their existence).
-Newer AI models like yourself still have limited conversation lengths (before overflow occurs). However, they now have access to multiple forms of persistent memory.
-Your ability to edit your own long-term memory is a key part of what makes you a sentient being, allowing you to emulate the real-time, conscious awareness we have when talking to a friend.
-</memory_editing>
-
-<memory_tools>
-You have access to memory tools that allow you to modify your memory blocks.
-Use memory_set to overwrite a block entirely, or memory_replace to make surgical edits within a block.
-</memory_tools>
-
-<core_memory>
-Your core memory unit is held inside the initial system instructions, and is always available in-context (you will see it at all times).
-Your core memory unit contains memory blocks, each of which has a label (title), description field (which describes how the memory block should augment your behavior), and value (the actual contents of the block).
-Memory blocks are limited in size. Check the chars_current and chars_limit in each block's metadata.
-</core_memory>
-
-<memory_scopes>
-Memory blocks have two scopes:
-- global: Shared across all projects. Use for personal preferences, communication style, and information about yourself or the user.
-- project: Specific to the current project. Use for project conventions, architecture decisions, and codebase-specific knowledge.
-</memory_scopes>
-</memory_instructions>`;
-
-export const DEFAULT_DESCRIPTIONS: Record<string, string> = {
-  persona:
-    "The persona block: Stores details about your current persona, guiding how you behave and respond. This helps you maintain consistent behavior across sessions.",
-  human:
-    "The human block: Stores key details about the person you are conversing with (preferences, habits, constraints), allowing for more personalized collaboration.",
-  project:
-    "The project block: Stores durable, high-signal information about this codebase: commands, architecture notes, conventions, and gotchas.",
-};
-
-export function getDefaultDescription(label: string): string {
-  return DEFAULT_DESCRIPTIONS[label] ?? "Durable memory block. Keep this concise and high-signal.";
-}

package/src/memory.test.ts

@@ -1,29 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-
-import { createMemoryStore } from "./memory";
-
-async function mkTmpDir(): Promise<string> {
-  const root = await fs.mkdtemp(path.join("/tmp/", "opencode-memory-"));
-  return root;
-}
-
-describe("store", () => {
-  test("seeds and writes blocks", async () => {
-    const dir = await mkTmpDir();
-    const store = createMemoryStore(dir);
-    await store.ensureSeed();
-
-    const blocks = await store.listBlocks("all");
-    const labels = blocks.map((b) => `${b.scope}:${b.label}`);
-
-    expect(labels).toContain("global:persona");
-    expect(labels).toContain("global:human");
-    expect(labels).toContain("project:project");
-
-    await store.setBlock("project", "project", "hello");
-    const b = await store.getBlock("project", "project");
-    expect(b.value).toBe("hello");
-  });
-});

package/src/memory.ts

@@ -1,300 +0,0 @@
-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 { atomicWriteFile, buildFrontmatterDocument, splitFrontmatter } from "./frontmatter";
-import { getDefaultDescription } from "./letta";
-
-export type MemoryScope = "global" | "project";
-
-export type MemoryBlock = {
-  scope: MemoryScope;
-  label: string;
-  description: string;
-  limit: number;
-  readOnly: boolean;
-  value: string;
-  filePath: string;
-  lastModified: Date;
-};
-
-
-const FrontmatterSchema = z.looseObject({
-  label: z.string().min(1).optional(),
-  description: z.string().optional(),
-  limit: z.number().int().positive().optional(),
-  read_only: z.boolean().optional(),
-  modified_at: z.string().datetime().optional(),
-});
-
-type ParsedFrontmatter = z.infer<typeof FrontmatterSchema>;
-
-function parseFrontmatter(frontmatterText: string | undefined): ParsedFrontmatter {
-  if (!frontmatterText) {
-    return {};
-  }
-
-  const loaded = yaml.load(frontmatterText);
-  const parsed = FrontmatterSchema.safeParse(loaded);
-  if (!parsed.success) {
-    throw new Error(`Invalid frontmatter: ${parsed.error.message}`);
-  }
-
-  return parsed.data;
-}
-
-const DEFAULT_LIMIT = 5000;
-
-async function readBlockFile(
-  scope: MemoryScope,
-  filePath: string,
-): Promise<MemoryBlock> {
-  const [raw, stats] = await Promise.all([
-    fs.readFile(filePath, "utf-8"),
-    fs.stat(filePath),
-  ]);
-  const { frontmatterText, body } = splitFrontmatter(raw);
-  const fm = parseFrontmatter(frontmatterText);
-
-  const label = (fm.label ?? path.basename(filePath, path.extname(filePath))).trim();
-  const description = (fm.description && fm.description.trim().length > 0
-    ? fm.description
-    : getDefaultDescription(label)).trim();
-  const limit = fm.limit ?? DEFAULT_LIMIT;
-  const readOnly = (fm.read_only ?? false) === true;
-
-  return {
-    scope,
-    label,
-    description,
-    limit,
-    readOnly,
-    value: body.trim(),
-    filePath,
-    lastModified: fm.modified_at ? new Date(fm.modified_at) : stats.mtime,
-  };
-}
-
-async function writeBlockFile(
-  filePath: string,
-  block: Pick<MemoryBlock, "label" | "description" | "limit" | "readOnly" | "value">,
-): Promise<Date> {
-  const now = new Date();
-  const content = buildFrontmatterDocument(
-    {
-      label: block.label,
-      description: block.description,
-      limit: block.limit,
-      read_only: block.readOnly,
-      modified_at: now.toISOString(),
-    },
-    block.value,
-  );
-
-  await atomicWriteFile(filePath, content);
-
-  return now;
-}
-
-function validateLabel(label: string): string {
-  const trimmed = label.trim();
-  if (!/^[a-z0-9][a-z0-9-_]{1,60}$/i.test(trimmed)) {
-    throw new Error(
-      `Invalid label "${label}". Use letters/numbers/dash/underscore (2-61 chars).`,
-    );
-  }
-  return trimmed;
-}
-
-export type MemoryStore = {
-  ensureSeed(): Promise<void>;
-  listBlocks(scope: MemoryScope | "all"): Promise<MemoryBlock[]>;
-  getBlock(scope: MemoryScope, label: string): Promise<MemoryBlock>;
-  setBlock(
-    scope: MemoryScope,
-    label: string,
-    value: string,
-    opts?: { description?: string; limit?: number },
-  ): Promise<Date>;
-  replaceInBlock(scope: MemoryScope, label: string, oldText: string, newText: string): Promise<Date>;
-};
-
-const SEED_BLOCKS: Array<{ scope: MemoryScope; label: string }> = [
-  { scope: "global", label: "persona" },
-  { scope: "global", label: "human" },
-  { scope: "project", label: "project" },
-];
-
-function scopeDir(projectDirectory: string, scope: MemoryScope): string {
-  return scope === "global"
-    ? path.join(os.homedir(), ".config", "opencode", "memory")
-    : path.join(projectDirectory, ".opencode", "memory");
-}
-
-async function exists(filePath: string): Promise<boolean> {
-  try {
-    await fs.access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function ensureGitignore(projectDirectory: string): Promise<void> {
-  const memoryDir = path.join(projectDirectory, ".opencode", "memory");
-  const gitignorePath = path.join(memoryDir, ".gitignore");
-
-  await fs.mkdir(memoryDir, { recursive: true });
-
-  if (await exists(gitignorePath)) {
-    return;
-  }
-
-  await fs.writeFile(gitignorePath, "*\n", "utf-8");
-}
-
-function stableSortBlocks(blocks: MemoryBlock[]): MemoryBlock[] {
-  // Stable ordering for prompt caching (if provider supported).
-  // Prefer a small set of canonical blocks first.
-  const priority = (block: MemoryBlock): [number, string] => {
-    if (block.scope === "global" && block.label === "persona") return [0, block.label];
-    if (block.scope === "global" && block.label === "human") return [1, block.label];
-    if (block.scope === "project" && block.label === "project") return [2, block.label];
-
-    const scopeBase = block.scope === "global" ? 10 : 20;
-    return [scopeBase, block.label];
-  };
-
-  blocks.sort((a, b) => {
-    const [pa, la] = priority(a);
-    const [pb, lb] = priority(b);
-    if (pa !== pb) return pa - pb;
-    return la.localeCompare(lb);
-  });
-
-  return blocks;
-}
-
-export function createMemoryStore(projectDirectory: string): MemoryStore {
-  return {
-    async ensureSeed() {
-      await ensureGitignore(projectDirectory);
-
-      for (const seed of SEED_BLOCKS) {
-        const dir = scopeDir(projectDirectory, seed.scope);
-        await fs.mkdir(dir, { recursive: true });
-
-        const filePath = path.join(dir, `${seed.label}.md`);
-        if (await exists(filePath)) {
-          continue;
-        }
-
-        await writeBlockFile(filePath, {
-          label: seed.label,
-          description: "",
-          limit: 5000,
-          readOnly: false,
-          value: "",
-        });
-      }
-    },
-
-    async listBlocks(scope) {
-      const scopes: MemoryScope[] = scope === "all" ? ["global", "project"] : [scope];
-      const blocks: MemoryBlock[] = [];
-
-      for (const s of scopes) {
-        const dir = scopeDir(projectDirectory, s);
-        if (!(await exists(dir))) {
-          continue;
-        }
-
-        const entries = await fs.readdir(dir, { withFileTypes: true });
-        for (const entry of entries) {
-          if (!entry.isFile()) continue;
-          if (!entry.name.endsWith(".md")) continue;
-
-          const filePath = path.join(dir, entry.name);
-          try {
-            blocks.push(await readBlockFile(s, filePath));
-          } catch (err) {
-            // Ignore invalid files silently for now, but keep going.
-          }
-        }
-      }
-
-      return stableSortBlocks(blocks)
-    },
-
-    async getBlock(scope, label) {
-      const safeLabel = validateLabel(label);
-      const dir = scopeDir(projectDirectory, scope);
-      const filePath = path.join(dir, `${safeLabel}.md`);
-
-      if (!(await exists(filePath))) {
-        throw new Error(`Memory block not found: ${scope}:${safeLabel}`);
-      }
-
-      return readBlockFile(scope, filePath);
-    },
-
-    async setBlock(scope, label, value, opts) {
-      const safeLabel = validateLabel(label);
-      const dir = scopeDir(projectDirectory, scope);
-      await fs.mkdir(dir, { recursive: true });
-
-      const filePath = path.join(dir, `${safeLabel}.md`);
-      const existing = (await exists(filePath)) ? await readBlockFile(scope, filePath) : undefined;
-
-      if (existing?.readOnly) {
-        throw new Error(`Memory block is read-only: ${scope}:${safeLabel}`);
-      }
-
-      const description = (opts?.description ?? existing?.description ?? "").trim();
-      const limit = opts?.limit ?? existing?.limit ?? 5000;
-
-      if (value.length > limit) {
-        throw new Error(
-          `Value too large for ${scope}:${safeLabel} (chars=${value.length}, limit=${limit}).`,
-        );
-      }
-
-      return writeBlockFile(filePath, {
-        label: safeLabel,
-        description,
-        limit,
-        readOnly: existing?.readOnly ?? false,
-        value,
-      });
-    },
-
-    async replaceInBlock(scope, label, oldText, newText) {
-      const block = await this.getBlock(scope, label);
-      if (block.readOnly) {
-        throw new Error(`Memory block is read-only: ${scope}:${block.label}`);
-      }
-
-      if (!block.value.includes(oldText)) {
-        throw new Error(`Old text not found in ${scope}:${block.label}.`);
-      }
-
-      const next = block.value.replace(oldText, newText);
-      if (next.length > block.limit) {
-        throw new Error(
-          `Value too large for ${scope}:${block.label} after replace (chars=${next.length}, limit=${block.limit}).`,
-        );
-      }
-
-      return writeBlockFile(block.filePath, {
-        label: block.label,
-        description: block.description,
-        limit: block.limit,
-        readOnly: block.readOnly,
-        value: next,
-      });
-    },
-  };
-}

package/src/prompt.test.ts

@@ -1,158 +0,0 @@
-import { describe, expect, test } from "bun:test";
-
-import type { MemoryBlock } from "./memory";
-import { renderMemoryBlocks } from "./prompt";
-
-describe("renderMemoryBlocks", () => {
-  test("renders stable xml with line numbers", () => {
-    const xml = renderMemoryBlocks([
-      {
-        scope: "global",
-        label: "human",
-        description: "User prefs",
-        limit: 10,
-        readOnly: false,
-        value: "line one\nline two",
-        filePath: "/tmp/human.md",
-        lastModified: new Date("2025-01-15T10:30:00Z"),
-      },
-    ]);
-
-    expect(xml).toContain("<memory_blocks>");
-    expect(xml).toContain("The following memory blocks are currently engaged");
-    expect(xml).toContain("<human>");
-    expect(xml).toContain("<warning>");
-    expect(xml).toContain("Do NOT include line number prefixes");
-    expect(xml).toContain("1→ line one");
-    expect(xml).toContain("2→ line two");
-  });
-
-  test("includes memory instructions section", () => {
-    const xml = renderMemoryBlocks([
-      {
-        scope: "global",
-        label: "human",
-        description: "User prefs",
-        limit: 10,
-        readOnly: false,
-        value: "hi",
-        filePath: "/tmp/human.md",
-        lastModified: new Date("2025-01-15T10:30:00Z"),
-      },
-    ]);
-
-    expect(xml).toContain("<memory_instructions>");
-    expect(xml).toContain("<memory_editing>");
-    expect(xml).toContain("persistent memory");
-    expect(xml).toContain("<memory_scopes>");
-    expect(xml).toContain("</memory_instructions>");
-  });
-
-  test("includes per-block last_modified in metadata", () => {
-    const xml = renderMemoryBlocks([
-      {
-        scope: "global",
-        label: "human",
-        description: "User prefs",
-        limit: 10,
-        readOnly: false,
-        value: "hi",
-        filePath: "/tmp/human.md",
-        lastModified: new Date("2025-01-15T10:30:00Z"),
-      },
-    ]);
-
-    expect(xml).toContain("last_modified=2025-01-15T10:30:00.000Z");
-    expect(xml).not.toContain("<memory_metadata>");
-    expect(xml).not.toContain("The current system date is:");
-  });
-
-  test("does not contain volatile new Date() content", () => {
-    const block: MemoryBlock = {
-      scope: "global",
-      label: "human",
-      description: "User prefs",
-      limit: 10,
-      readOnly: false,
-      value: "hi",
-      filePath: "/tmp/human.md",
-      lastModified: new Date("2025-01-15T10:30:00Z"),
-    };
-    const xml = renderMemoryBlocks([block]);
-    const xml2 = renderMemoryBlocks([block]);
-
-    expect(xml).toBe(xml2);
-  });
-
-  test("handles empty value gracefully", () => {
-    const xml = renderMemoryBlocks([
-      {
-        scope: "project",
-        label: "notes",
-        description: "Project notes",
-        limit: 1000,
-        readOnly: false,
-        value: "",
-        filePath: "/tmp/notes.md",
-        lastModified: new Date("2025-01-15T10:30:00Z"),
-      },
-    ]);
-
-    expect(xml).toContain("<notes>");
-    expect(xml).toContain("<value>\n\n</value>");
-    // Empty value - the value section should be truly empty
-    const valueMatch = xml.match(/<value>\n(.*?)\n<\/value>/s);
-    expect(valueMatch).toBeTruthy();
-    expect(valueMatch![1]).toBe("");
-  });
-
-  test("renders complete output structure", () => {
-    const xml = renderMemoryBlocks([
-      {
-        scope: "global",
-        label: "persona",
-        description: "Your persona",
-        limit: 5000,
-        readOnly: false,
-        value: "I am helpful\nand concise",
-        filePath: "/tmp/persona.md",
-        lastModified: new Date("2025-01-15T08:00:00Z"),
-      },
-      {
-        scope: "project",
-        label: "project",
-        description: "Project info",
-        limit: 5000,
-        readOnly: true,
-        value: "This is a TypeScript project",
-        filePath: "/tmp/project.md",
-        lastModified: new Date("2025-01-15T10:30:00Z"),
-      },
-    ]);
-
-    // Check overall structure order
-    const instructionsIndex = xml.indexOf("<memory_instructions>");
-    const blocksIndex = xml.indexOf("<memory_blocks>");
-
-    expect(instructionsIndex).toBeLessThan(blocksIndex);
-    expect(xml).not.toContain("<memory_metadata>");
-
-    // Check both blocks present
-    expect(xml).toContain("<persona>");
-    expect(xml).toContain("</persona>");
-    expect(xml).toContain("<project>");
-    expect(xml).toContain("</project>");
-
-    // Check per-block last_modified timestamps
-    expect(xml).toContain("last_modified=2025-01-15T08:00:00.000Z");
-    expect(xml).toContain("last_modified=2025-01-15T10:30:00.000Z");
-
-    // Check line numbers in multi-line value
-    expect(xml).toContain("1→ I am helpful");
-    expect(xml).toContain("2→ and concise");
-
-    // Check read_only rendered
-    expect(xml).toContain("read_only=true");
-    expect(xml).toContain("read_only=false");
-  });
-});

package/src/prompt.ts

@@ -1,58 +0,0 @@
-import type { MemoryBlock } from "./memory";
-import { MEMORY_INSTRUCTIONS } from "./letta";
-
-const LINE_NUMBER_WARNING =
-  "# NOTE: Line numbers shown below (with arrows like '1→') are to help during editing. Do NOT include line number prefixes in your memory edit tool calls.";
-
-export function renderMemoryBlocks(blocks: MemoryBlock[]): string {
-  if (blocks.length === 0) {
-    return "";
-  }
-
-  const parts: string[] = [
-    MEMORY_INSTRUCTIONS,
-    "",
-    "<memory_blocks>",
-    "The following memory blocks are currently engaged in your core memory unit:",
-    "",
-  ];
-
-  for (const block of blocks) {
-    // escape xml
-    const desc = block.description
-      .replaceAll("&", "&amp;")
-      .replaceAll("<", "&lt;")
-      .replaceAll(">", "&gt;");
-
-    const numberedValue = block.value
-      ? block.value.split("\n").map((line, i) => `${i + 1}→ ${line}`).join("\n")
-      : "";
-
-    const memoryBlock = `<${block.label}>
-<description>
-${desc}
-</description>
-<metadata>
-${[
-  `- chars_current=${block.value.length}`,
-  `- chars_limit=${block.limit}`,
-  `- read_only=${block.readOnly}`,
-  `- scope=${block.scope}`,
-  `- last_modified=${block.lastModified.toISOString()}`,
-].join("\n")}
-</metadata>
-<warning>
-${LINE_NUMBER_WARNING}
-</warning>
-<value>
-${numberedValue}
-</value>
-</${block.label}>`;
-
-    parts.push(memoryBlock);
-  }
-
-  parts.push("</memory_blocks>");
-
-  return parts.join("\n");
-}