@ghilteras/opencode-agent-memory 0.4.3 → 0.5.1

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()}.`;
-    },
-  });
-}
+import type { JournalStore, JournalTag } from "./journal";
 
 export type JournalContext = {
   directory: string;
@@ -76,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(),
@@ -147,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(),

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.concurrency.test.ts

@@ -1,57 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import { tmpdir } from "node:os";
-
-import { createMemoryStore } from "./memory";
-
-async function mkTmpDir(): Promise<string> {
-  return fs.mkdtemp(path.join(tmpdir(), "mem-race-"));
-}
-
-describe("concurrent block edits", () => {
-  test("two concurrent replaceInBlock calls both survive", async () => {
-    const dir = await mkTmpDir();
-    const store = createMemoryStore(dir);
-    await store.ensureSeed();
-    await store.setBlock("project", "project", "AAA bbb CCC ddd", { limit: 5000 });
-
-    await Promise.all([
-      store.replaceInBlock("project", "project", "AAA", "111"),
-      store.replaceInBlock("project", "project", "CCC", "333"),
-    ]);
-
-    const block = await store.getBlock("project", "project");
-    expect(block.value).toContain("111");
-    expect(block.value).toContain("333");
-    expect(block.value).toContain("bbb");
-    expect(block.value).toContain("ddd");
-
-    // No leftover temp files
-    const memDir = path.join(dir, ".opencode", "memory");
-    const files = await fs.readdir(memDir);
-    const tmpFiles = files.filter((f) => f.includes(".tmp"));
-    expect(tmpFiles).toEqual([]);
-  });
-
-  test("10 concurrent setBlock calls produce valid frontmatter", async () => {
-    const dir = await mkTmpDir();
-    const store = createMemoryStore(dir);
-    await store.ensureSeed();
-
-    const ops = Array.from({ length: 10 }, (_, i) =>
-      store.setBlock("project", `project`, `iteration ${i} ${"x".repeat(50)}`, { limit: 5000 }),
-    );
-    await Promise.all(ops);
-
-    // File must parse as valid frontmatter
-    const block = await store.getBlock("project", "project");
-    expect(block.value).toMatch(/iteration \d+/);
-
-    // No leftover temp files
-    const memDir = path.join(dir, ".opencode", "memory");
-    const files = await fs.readdir(memDir);
-    const tmpFiles = files.filter((f) => f.includes(".tmp"));
-    expect(tmpFiles).toEqual([]);
-  });
-});

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,308 +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, withFileLock } 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`);
-
-      return withFileLock(filePath, async () => {
-        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 safeLabel = validateLabel(label);
-      const filePath = path.join(scopeDir(projectDirectory, scope), `${safeLabel}.md`);
-
-      return withFileLock(filePath, async () => {
-        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,
-        });
-      });
-    },
-  };
-}