@ghilteras/opencode-agent-memory 0.3.0

package/src/memory.ts

@@ -0,0 +1,300 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import 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/plugin.ts

@@ -0,0 +1,80 @@
+import type { Plugin, ToolDefinition } from "@opencode-ai/plugin";
+
+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";
+
+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;
+
+  // Mutable state updated by chat.message hook
+  const journalCtx: JournalContext = {
+    directory,
+    model: "",
+    provider: "",
+  };
+
+  let journalTools: Record<string, ToolDefinition> = {};
+  let journalSystemNote = "";
+
+  if (journalEnabled) {
+    const journalStore = createJournalStore();
+    journalTools = {
+      journal_write: JournalWrite(journalStore, journalCtx),
+      journal_read: JournalRead(journalStore),
+      journal_search: JournalSearch(journalStore),
+    };
+    journalSystemNote = buildJournalSystemNote(config.journal?.tags);
+  }
+
+  return {
+    "chat.message": async (input, _output) => {
+      if (input.model) {
+        journalCtx.model = input.model.modelID;
+        journalCtx.provider = input.model.providerID;
+      }
+    },
+
+    "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/prompt.test.ts

@@ -0,0 +1,158 @@
+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

@@ -0,0 +1,58 @@
+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");
+}