opencode-remote-agent-memory 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# OpenCode Memory Client
+
+OpenCode plugin that fetches memory blocks from a remote server and injects them into the system prompt.
+
+## Configuration
+
+Create `.opencode/agent-memory.json`:
+
+```json
+{
+  "remote": {
+    "url": "https://your-memory-server.com/api",
+    "apiKey": "your-api-key",
+    "project": "your-project-name"
+  },
+  "journal": {
+    "enabled": true,
+    "tags": [
+      { "name": "perf", "description": "Performance optimization work" },
+      { "name": "debugging", "description": "Debugging sessions and findings" }
+    ]
+  }
+}
+```
+
+**Configuration options:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `remote.url` | Yes | Server URL (e.g., `http://localhost:3000/api`) |
+| `remote.apiKey` | Yes | API key from server |
+| `remote.project` | Yes | Project name for project-specific memories |
+| `journal.enabled` | No | Enable journal (default: false) |
+| `journal.tags` | No | Suggested tags for journal entries |
+
+Then add the plugin to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-remote-agent-memory"]
+}
+```
+
+Restart OpenCode.
+
+## Available Tools
+
+### Memory Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_get` | Get a specific memory block by label and scope |
+| `memory_list` | List available memory blocks. Use `scope: "domain"` to retrieve domain knowledge on-demand |
+| `memory_set` | Create or update a memory block (full overwrite) |
+| `memory_replace` | Replace a substring within a memory block |
+
+### Journal Tools (when enabled)
+
+| 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 |
+| `journal_read` | Read a specific journal entry by ID |
+
+## Local Development
+
+```bash
+# Clone the repo
+git clone https://github.com/davidhidvegi/opencode-remote-agent-memory.git
+
+# Link the client to OpenCode
+mkdir -p ~/.config/opencode/plugin
+ln -sf "$(pwd)/client/src/plugin.ts" ~/.config/opencode/plugin/memory.ts
+```

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "opencode-remote-agent-memory",
+  "version": "0.1.0",
+  "description": "Letta-style editable remote memory blocks for OpenCode.",
+  "author": "David Hidvegi <david@hidvegi.xyz>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidhidvegi/opencode-remote-agent-memory.git"
+  },
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.0.115",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@tsconfig/bun": "^1.0.10",
+    "@types/bun": "^1.3.3",
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/journal.ts

@@ -0,0 +1,149 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { z } from "zod";
+
+const TagSchema = z.looseObject({
+  name: z.string().min(1),
+  description: z.string().min(1),
+});
+
+const ConfigSchema = z.looseObject({
+  journal: z
+    .looseObject({
+      enabled: z.boolean().optional(),
+      tags: z.array(TagSchema).optional(),
+    })
+    .optional(),
+  remote: z.looseObject({
+    url: z.string().url().optional(),
+    apiKey: z.string().min(1).optional(),
+    project: z.string().min(1).optional(),
+  }),
+});
+
+export type AgentMemoryConfig = z.infer<typeof ConfigSchema>;
+
+export async function loadConfig(
+  projectDirectory: string = "",
+): Promise<Required<AgentMemoryConfig>> {
+  const globalConfigPath = path.join(
+    os.homedir(),
+    ".config",
+    "opencode",
+    "agent-memory.json",
+  );
+  const projectConfigPath = projectDirectory
+    ? path.join(projectDirectory, ".opencode", "agent-memory.json")
+    : null;
+
+  let globalConfig: Partial<AgentMemoryConfig> = {};
+  let projectConfig: Partial<AgentMemoryConfig> = {};
+
+  try {
+    const raw = await fs.readFile(globalConfigPath, "utf-8");
+    const parsed = ConfigSchema.safeParse(JSON.parse(raw));
+    if (parsed.success) {
+      globalConfig = parsed.data;
+    }
+  } catch {
+    // Global config not found or invalid - that's ok, we'll use project config
+  }
+
+  if (projectConfigPath) {
+    try {
+      const raw = await fs.readFile(projectConfigPath, "utf-8");
+      const parsed = ConfigSchema.safeParse(JSON.parse(raw));
+      if (parsed.success) {
+        projectConfig = parsed.data;
+      }
+    } catch {
+      // Project config not found - that's ok
+    }
+  }
+
+  const merged: Required<AgentMemoryConfig> = {
+    remote: {
+      url: (projectConfig.remote?.url ??
+        globalConfig.remote?.url ??
+        "") as string,
+      apiKey: (projectConfig.remote?.apiKey ??
+        globalConfig.remote?.apiKey ??
+        "") as string,
+      project: (projectConfig.remote?.project ??
+        globalConfig.remote?.project ??
+        "") as string,
+    },
+    journal: (projectConfig.journal ??
+      globalConfig.journal) as Required<AgentMemoryConfig>["journal"],
+  };
+
+  if (!merged.remote.url || !merged.remote.apiKey || !merged.remote.project) {
+    throw new Error(
+      "Remote memory configuration required. Add 'remote.url', 'remote.apiKey', and 'remote.project' to " +
+        (projectConfigPath ? `${projectConfigPath} or ` : "") +
+        globalConfigPath,
+    );
+  }
+
+  return merged;
+}
+
+export type JournalTag = {
+  name: string;
+  description: string;
+};
+
+export type JournalEntry = {
+  id: string;
+  title: string;
+  project: string;
+  model: string;
+  provider: string;
+  agent: string;
+  sessionId: string;
+  created: Date;
+  tags: string[];
+  body: string;
+  filePath: string;
+};
+
+export type JournalStore = {
+  write(entry: {
+    title: string;
+    body: string;
+    project?: string;
+    model?: string;
+    provider?: string;
+    agent?: string;
+    sessionId?: string;
+    tags?: string[];
+  }): Promise<JournalEntry>;
+
+  read(id: string): Promise<JournalEntry>;
+
+  search(query: {
+    text?: string;
+    project?: string;
+    tags?: string[];
+    limit?: number;
+    offset?: number;
+  }): Promise<{ entries: JournalEntry[]; total: number; allTags: string[] }>;
+};
+
+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.
+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/letta.ts

@@ -0,0 +1,54 @@
+/**
+ * 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:
+- memory_list: List available memory blocks. Use scope="domain" to retrieve domain knowledge on-demand.
+- memory_get: Retrieve a specific memory block by label and scope.
+- memory_set: Overwrite a block entirely.
+- memory_replace: 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 four scopes:
+- global: Shared across all projects. Use for general facts and information that applies everywhere.
+- user: Specific to the user. Use for user preferences, habits, constraints, and personal details. The user is inferred from your API key.
+- project: Specific to the current project (as configured). Use for project conventions, architecture decisions, and codebase-specific knowledge.
+- domain: Specific domain knowledge (e.g., Elixir, Python, debugging). NOT automatically injected - retrieve on-demand using memory_list with scope="domain" when you need domain-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.",
+  domain:
+    "The domain block: Stores specific domain knowledge (e.g., Elixir, Python, debugging techniques). Retrieved on-demand when you need specialized knowledge.",
+};
+
+export function getDefaultDescription(label: string): string {
+  return DEFAULT_DESCRIPTIONS[label] ?? "Durable memory block. Keep this concise and high-signal.";
+}

package/src/memory.ts

@@ -0,0 +1,49 @@
+export type MemoryScope = "global" | "user" | "project" | "domain";
+
+export const SPECIAL_SCOPES = ["global", "user", "domain"] as const;
+
+export function isSpecialScope(scope: string): scope is MemoryScope {
+  return (SPECIAL_SCOPES as readonly string[]).includes(scope);
+}
+
+export type MemoryBlock = {
+  scope: MemoryScope;
+  label: string;
+  description: string;
+  limit: number;
+  readOnly: boolean;
+  value: string;
+  filePath: string;
+  lastModified: Date;
+};
+
+export type MemoryError = {
+  message: string;
+  code:
+    | "CONNECTION_ERROR"
+    | "AUTH_ERROR"
+    | "FORBIDDEN"
+    | "NOT_FOUND"
+    | "UNKNOWN";
+  scope?: string;
+  label?: string;
+};
+
+export type MemoryStore = {
+  listBlocks(scope: MemoryScope | "all" | "domain"): Promise<MemoryBlock[]>;
+  getBlock(scope: MemoryScope, label: string): Promise<MemoryBlock>;
+  setBlock(
+    scope: MemoryScope | string,
+    label: string,
+    value: string,
+    opts?: { description?: string; limit?: number },
+  ): Promise<void>;
+  replaceInBlock(
+    scope: MemoryScope | string,
+    label: string,
+    oldText: string,
+    newText: string,
+  ): Promise<void>;
+  getLastError(): MemoryError | null;
+  clearError(): void;
+};

package/src/plugin.ts

@@ -0,0 +1,126 @@
+import type { Plugin, ToolDefinition } from "@opencode-ai/plugin";
+
+import {
+  buildJournalSystemNote,
+  loadConfig,
+} from "./journal";
+import { createRemoteMemoryStore, createRemoteJournalStore } from "./remote";
+import type { MemoryError } from "./remote";
+import { renderMemoryBlocks } from "./prompt";
+import {
+  JournalRead,
+  JournalSearch,
+  JournalWrite,
+  MemoryGet,
+  MemoryList,
+  MemoryReplace,
+  MemorySet,
+} from "./tools";
+import type { JournalContext } from "./tools";
+
+function getSystemErrorWarning(error: MemoryError | null): string {
+  if (!error) return "";
+  
+  switch (error.code) {
+    case "CONNECTION_ERROR":
+      return `\n\n<memory_warning>
+⚠️ Memory server unavailable. Memories cannot be loaded. Please check that the memory server is running.
+</memory_warning>`;
+    case "AUTH_ERROR":
+      return `\n\n<memory_warning>
+⚠️ Memory authentication failed. Check your API key configuration.
+</memory_warning>`;
+    case "FORBIDDEN":
+      return `\n\n<memory_warning>
+⚠️ Memory permission denied. ${error.message}
+</memory_warning>`;
+    default:
+      return `\n\n<memory_warning>
+⚠️ Memory error: ${error.message}
+</memory_warning>`;
+  }
+}
+
+export const MemoryPlugin: Plugin = async (input) => {
+  const directory = (input as { directory?: string }).directory ?? "";
+  const config = await loadConfig(directory);
+
+  const store = createRemoteMemoryStore(
+    config.remote.url!,
+    config.remote.apiKey!,
+    config.remote.project!
+  );
+
+  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 = createRemoteJournalStore(
+      config.remote.url!,
+      config.remote.apiKey!
+    );
+    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 error = store.getLastError?.() ?? null;
+      
+      // If we got blocks, show them. Otherwise, just show the error warning.
+      const xml = renderMemoryBlocks(blocks);
+      const errorWarning = getSystemErrorWarning(error);
+      
+      if (!xml && errorWarning) {
+        output.system.push(errorWarning);
+        return;
+      }
+      
+      if (!xml) return;
+
+      // Insert early (right after provider header) for salience.
+      // OpenCode will re-join system chunks to preserve caching.
+      const insertAt = output.system.length > 0 ? 1 : 0;
+      output.system.splice(insertAt, 0, xml);
+
+      // Append error warning if there was an error loading memories
+      if (errorWarning) {
+        output.system.push(errorWarning);
+      }
+
+      // Append journal instructions at the end (preserves memory block cache)
+      if (journalSystemNote) {
+        output.system.push(journalSystemNote);
+      }
+    },
+
+    tool: {
+      memory_get: MemoryGet(store),
+      memory_list: MemoryList(store),
+      memory_set: MemorySet(store),
+      memory_replace: MemoryReplace(store),
+      ...journalTools,
+    },
+  };
+};

package/src/prompt.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, test } from "bun:test";
+
+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 memory metadata block with timestamps", () => {
+    const testDate = new Date("2025-01-15T10:30:00Z");
+    const xml = renderMemoryBlocks([
+      {
+        scope: "global",
+        label: "human",
+        description: "User prefs",
+        limit: 10,
+        readOnly: false,
+        value: "hi",
+        filePath: "/tmp/human.md",
+        lastModified: testDate,
+      },
+    ]);
+
+    expect(xml).toContain("<memory_metadata>");
+    expect(xml).toContain("The current system date is:");
+    expect(xml).toContain("Memory blocks were last modified:");
+    expect(xml).toContain("</memory_metadata>");
+  });
+
+  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>");
+    const metadataIndex = xml.indexOf("<memory_metadata>");
+
+    expect(instructionsIndex).toBeLessThan(blocksIndex);
+    expect(blocksIndex).toBeLessThan(metadataIndex);
+
+    // Check both blocks present
+    expect(xml).toContain("<persona>");
+    expect(xml).toContain("</persona>");
+    expect(xml).toContain("<project>");
+    expect(xml).toContain("</project>");
+
+    // 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,72 @@
+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.";
+
+function renderMemoryMetadata(blocks: MemoryBlock[]): string {
+  const now = new Date();
+
+  const lastModified = blocks.reduce(
+    (latest, block) => (block.lastModified > latest ? block.lastModified : latest),
+    new Date(0)
+  );
+
+  return `<memory_metadata>
+- The current system date is: ${now.toISOString()}
+- Memory blocks were last modified: ${lastModified.toISOString()}
+- Use memory tools to manage your memory blocks
+</memory_metadata>`;
+}
+
+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}
+</metadata>
+<warning>
+${LINE_NUMBER_WARNING}
+</warning>
+<value>
+${numberedValue}
+</value>
+</${block.label}>`;
+
+    parts.push(memoryBlock);
+  }
+
+  parts.push("</memory_blocks>");
+  parts.push("");
+  parts.push(renderMemoryMetadata(blocks));
+
+  return parts.join("\n");
+}

package/src/remote.ts

@@ -0,0 +1,331 @@
+import { z } from "zod";
+
+import type { MemoryBlock, MemoryScope, MemoryStore } from "./memory";
+import { isSpecialScope } from "./memory";
+import { getDefaultDescription } from "./letta";
+import type { JournalEntry, JournalStore } from "./journal";
+
+export type MemoryError = {
+  message: string;
+  code: "CONNECTION_ERROR" | "AUTH_ERROR" | "FORBIDDEN" | "NOT_FOUND" | "UNKNOWN";
+  scope?: string;
+  label?: string;
+};
+
+export type JournalError = {
+  message: string;
+  code: "CONNECTION_ERROR" | "AUTH_ERROR" | "FORBIDDEN" | "NOT_FOUND" | "UNKNOWN";
+};
+
+const RemoteBlockSchema = z.looseObject({
+  scope: z.enum(["global", "user", "domain"]),
+  label: z.string().min(1),
+  description: z.string().optional(),
+  limit: z.number().int().positive().optional(),
+  read_only: z.boolean().optional(),
+  value: z.string().optional(),
+  last_modified: z.string().optional(),
+});
+
+const RemoteJournalEntrySchema = z.looseObject({
+  id: z.string(),
+  title: z.string(),
+  body: z.string(),
+  project: z.string().optional(),
+  model: z.string().optional(),
+  provider: z.string().optional(),
+  agent: z.string().optional(),
+  sessionId: z.string().optional(),
+  created: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+});
+
+const RemoteSearchResultSchema = z.looseObject({
+  entries: z.array(RemoteJournalEntrySchema),
+  total: z.number(),
+  allTags: z.array(z.string()),
+});
+
+type RemoteBlock = z.infer<typeof RemoteBlockSchema>;
+type RemoteJournalEntry = z.infer<typeof RemoteJournalEntrySchema>;
+
+function parseRemoteBlock(block: RemoteBlock, scope: string): MemoryBlock {
+  const resolvedScope = block.scope ?? (isSpecialScope(scope) ? scope : "project");
+  return {
+    scope: resolvedScope,
+    label: block.label,
+    description: block.description?.trim() ?? getDefaultDescription(block.label),
+    limit: block.limit ?? 5000,
+    readOnly: block.read_only ?? false,
+    value: block.value ?? "",
+    filePath: "",
+    lastModified: block.last_modified ? new Date(block.last_modified) : new Date(),
+  };
+}
+
+function parseRemoteJournalEntry(entry: RemoteJournalEntry): JournalEntry {
+  return {
+    id: entry.id,
+    title: entry.title,
+    body: entry.body,
+    project: entry.project ?? "",
+    model: entry.model ?? "",
+    provider: entry.provider ?? "",
+    agent: entry.agent ?? "",
+    sessionId: entry.sessionId ?? "",
+    created: entry.created ? new Date(entry.created) : new Date(),
+    tags: entry.tags ?? [],
+    filePath: "",
+  };
+}
+
+function stableSortBlocks(blocks: MemoryBlock[]): MemoryBlock[] {
+  const scopeOrder: Record<MemoryScope, number> = {
+    global: 0,
+    user: 1,
+    project: 2,
+    domain: 3,
+  };
+
+  blocks.sort((a, b) => {
+    const orderA = scopeOrder[a.scope] ?? 10;
+    const orderB = scopeOrder[b.scope] ?? 10;
+    if (orderA !== orderB) return orderA - orderB;
+    return a.label.localeCompare(b.label);
+  });
+
+  return blocks;
+}
+
+type ErrorCode = "CONNECTION_ERROR" | "AUTH_ERROR" | "FORBIDDEN" | "NOT_FOUND" | "UNKNOWN";
+
+type ErrorState = {
+  message: string;
+  code: ErrorCode;
+};
+
+abstract class BaseRemoteStore<T extends ErrorState> {
+  protected baseUrl: string;
+  protected apiKey: string;
+  protected lastError: T | null = null;
+
+  constructor(baseUrl: string, apiKey: string) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.apiKey = apiKey;
+  }
+
+  abstract getLastError(): T | null;
+  abstract clearError(): void;
+
+  protected async request<R>(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<R> {
+    const url = `${this.baseUrl}${path}`;
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+      });
+
+      if (!response.ok) {
+        const error = await response.text();
+        if (response.status === 401) {
+          this.setError("Authentication failed. Check your API key.", "AUTH_ERROR");
+        } else if (response.status === 403) {
+          this.setError("Permission denied.", "FORBIDDEN");
+        } else if (response.status === 404) {
+          this.setError(`Not found: ${path}`, "NOT_FOUND");
+        } else {
+          this.setError(`${response.status} ${response.statusText} - ${error}`, "UNKNOWN");
+        }
+        throw new Error(this.lastError!.message);
+      }
+
+      if (response.status === 204) {
+        return undefined as R;
+      }
+
+      return response.json() as Promise<R>;
+    } catch (err) {
+      if (this.lastError) {
+        throw err;
+      }
+      const errorMsg = err instanceof Error ? err.message : "Unknown error";
+      if (errorMsg.includes("ECONNREFUSED") || errorMsg.includes("fetch") || errorMsg.includes("timeout")) {
+        this.setError(`Cannot connect to memory server at ${this.baseUrl}`, "CONNECTION_ERROR");
+      } else {
+        this.setError(errorMsg, "UNKNOWN");
+      }
+      throw err;
+    }
+  }
+
+  protected setError(message: string, code: ErrorCode): void {
+    this.lastError = { message, code } as T;
+  }
+}
+
+export class RemoteMemoryStore extends BaseRemoteStore<MemoryError> implements MemoryStore {
+  private project: string;
+
+  constructor(baseUrl: string, apiKey: string, project: string) {
+    super(baseUrl, apiKey);
+    this.project = project;
+  }
+
+  getLastError(): MemoryError | null {
+    return this.lastError;
+  }
+
+  clearError(): void {
+    this.lastError = null;
+  }
+
+  private getScopePath(scope: MemoryScope): string {
+    if (isSpecialScope(scope)) {
+      return `/blocks/${scope}`;
+    }
+    return `/blocks/${this.project}`;
+  }
+
+  async listBlocks(scope: MemoryScope | "all" | "domain"): Promise<MemoryBlock[]> {
+    let scopesToFetch: string[];
+
+    if (scope === "all") {
+      scopesToFetch = ["global", "user", this.project];
+    } else if (scope === "domain") {
+      scopesToFetch = ["domain"];
+    } else if (isSpecialScope(scope)) {
+      scopesToFetch = [scope];
+    } else {
+      scopesToFetch = [this.project];
+    }
+
+    const allBlocks: MemoryBlock[] = [];
+
+    for (const s of scopesToFetch) {
+      try {
+        const path = `/blocks/${s}`;
+        const blocks = await this.request<RemoteBlock[]>("GET", path);
+        for (const block of blocks) {
+          allBlocks.push(parseRemoteBlock(block, s));
+        }
+      } catch {
+        // Server may return error if no blocks exist - skip silently
+      }
+    }
+
+    const filteredBlocks = scope === "domain"
+      ? allBlocks
+      : allBlocks.filter(b => b.scope !== "domain");
+
+    return stableSortBlocks(filteredBlocks);
+  }
+
+  async getBlock(scope: MemoryScope, label: string): Promise<MemoryBlock> {
+    const path = this.getScopePath(scope);
+    const block = await this.request<RemoteBlock>(
+      "GET",
+      `${path}/${encodeURIComponent(label)}`,
+    );
+    return parseRemoteBlock(block, scope);
+  }
+
+  async setBlock(
+    scope: MemoryScope,
+    label: string,
+    value: string,
+    opts?: { description?: string; limit?: number },
+  ): Promise<void> {
+    const path = this.getScopePath(scope);
+    await this.request<void>("POST", `${path}/${encodeURIComponent(label)}`, {
+      value,
+      description: opts?.description,
+      limit: opts?.limit,
+    });
+  }
+
+  async replaceInBlock(
+    scope: MemoryScope,
+    label: string,
+    oldText: string,
+    newText: string,
+  ): Promise<void> {
+    const path = this.getScopePath(scope);
+    await this.request<void>("PATCH", `${path}/${encodeURIComponent(label)}`, {
+      old_text: oldText,
+      new_text: newText,
+    });
+  }
+}
+
+export class RemoteJournalStore extends BaseRemoteStore<JournalError> implements JournalStore {
+  getLastError(): JournalError | null {
+    return this.lastError;
+  }
+
+  clearError(): void {
+    this.lastError = null;
+  }
+
+  async write(entry: {
+    title: string;
+    body: string;
+    project?: string;
+    model?: string;
+    provider?: string;
+    agent?: string;
+    sessionId?: string;
+    tags?: string[];
+  }): Promise<JournalEntry> {
+    const remoteEntry = await this.request<RemoteJournalEntry>("POST", "/journal", entry);
+    return parseRemoteJournalEntry(remoteEntry);
+  }
+
+  async read(id: string): Promise<JournalEntry> {
+    const remoteEntry = await this.request<RemoteJournalEntry>(
+      "GET",
+      `/journal/${encodeURIComponent(id)}`
+    );
+    return parseRemoteJournalEntry(remoteEntry);
+  }
+
+  async search(query: {
+    text?: string;
+    project?: string;
+    tags?: string[];
+    limit?: number;
+    offset?: number;
+  }): Promise<{ entries: JournalEntry[]; total: number; allTags: string[] }> {
+    const params = new URLSearchParams();
+    if (query.text) params.set("text", query.text);
+    if (query.project) params.set("project", query.project);
+    if (query.tags && query.tags.length > 0) params.set("tags", query.tags.join(","));
+    if (query.limit) params.set("limit", String(query.limit));
+    if (query.offset) params.set("offset", String(query.offset));
+
+    const path = `/journal${params.toString() ? "?" + params.toString() : ""}`;
+    const result = await this.request<z.infer<typeof RemoteSearchResultSchema>>("GET", path);
+
+    return {
+      entries: result.entries.map(parseRemoteJournalEntry),
+      total: result.total,
+      allTags: result.allTags,
+    };
+  }
+}
+
+export function createRemoteMemoryStore(baseUrl: string, apiKey: string, project: string): MemoryStore {
+  return new RemoteMemoryStore(baseUrl, apiKey, project);
+}
+
+export function createRemoteJournalStore(baseUrl: string, apiKey: string): JournalStore {
+  return new RemoteJournalStore(baseUrl, apiKey);
+}

package/src/tools.ts

@@ -0,0 +1,296 @@
+import { tool } from "@opencode-ai/plugin";
+
+import type { JournalStore } from "./journal";
+import type { MemoryError, MemoryScope, MemoryStore } from "./memory";
+
+function toKebabCase(str: string): string {
+  return str
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function getErrorMessage(store: MemoryStore): string | null {
+  const error = store.getLastError?.();
+  if (!error) return null;
+
+  switch (error.code) {
+    case "CONNECTION_ERROR":
+      return `⚠️ Memory server unavailable. Cannot connect to server. Check that the server is running.`;
+    case "AUTH_ERROR":
+      return `⚠️ Memory authentication failed. Check your API key.`;
+    case "FORBIDDEN":
+      return `⚠️ Memory permission denied. ${error.message}`;
+    case "NOT_FOUND":
+      return `⚠️ Memory not found. ${error.message}`;
+    default:
+      return `⚠️ Memory error. ${error.message}`;
+  }
+}
+
+export function MemoryList(store: MemoryStore) {
+  return tool({
+    description: "List available memory blocks (labels, descriptions, sizes). Use scope='domain' to retrieve domain knowledge on-demand.",
+    args: {
+      scope: tool.schema.enum(["all", "global", "user", "project", "domain"]).optional(),
+    },
+    async execute(args) {
+      const scope = (args.scope ?? "all") as MemoryScope | "all" | "domain";
+      const blocks = await store.listBlocks(scope);
+      
+      const errorMsg = getErrorMessage(store);
+      if (blocks.length === 0) {
+        if (errorMsg) {
+          return `${errorMsg}\n\nNo memory blocks available.`;
+        }
+        return "No memory blocks found.";
+      }
+
+      const blockList = blocks
+        .map(
+          (b) =>
+            `${b.scope}:${b.label}\n  read_only=${b.readOnly} chars=${b.value.length}/${b.limit}\n  ${b.description}`,
+        )
+        .join("\n\n");
+
+      if (errorMsg) {
+        return `${errorMsg}\n\n${blockList}`;
+      }
+      return blockList;
+    },
+  });
+}
+
+export function MemoryGet(store: MemoryStore) {
+  return tool({
+    description: "Get a specific memory block by label and scope.",
+    args: {
+      label: tool.schema.string(),
+      scope: tool.schema.enum(["global", "user", "project", "domain"]).optional(),
+    },
+    async execute(args) {
+      const scope = (args.scope ?? "project") as MemoryScope;
+      const label = scope === "user" ? toKebabCase(args.label) : args.label;
+      try {
+        const block = await store.getBlock(scope, label);
+        return `<${block.label}>
+<description>
+${block.description}
+</description>
+<metadata>
+- chars_current=${block.value.length}
+- chars_limit=${block.limit}
+- read_only=${block.readOnly}
+- scope=${block.scope}
+</metadata>
+<value>
+${block.value}
+</value>`;
+      } catch (err) {
+        const errorMsg = getErrorMessage(store);
+        if (errorMsg) {
+          return errorMsg;
+        }
+        const msg = err instanceof Error ? err.message : "Unknown error";
+        if (msg.includes("not found")) {
+          return `⚠️ Memory block '${args.label}' not found in scope '${scope}'.`;
+        }
+        return `⚠️ Failed to get memory block: ${msg}`;
+      }
+    },
+  });
+}
+
+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", "user", "project", "domain"]).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 label = scope === "user" ? toKebabCase(args.label) : args.label;
+      try {
+        await store.setBlock(scope, label, args.value, {
+          description: args.description,
+          limit: args.limit,
+        });
+        return `Updated memory block ${scope}:${label}.`;
+      } catch (err) {
+        const errorMsg = getErrorMessage(store);
+        if (errorMsg) {
+          return errorMsg;
+        }
+        const msg = err instanceof Error ? err.message : "Unknown error";
+        return `⚠️ Failed to set memory block: ${msg}`;
+      }
+    },
+  });
+}
+
+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", "user", "project", "domain"]).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 label = scope === "user" ? toKebabCase(args.label) : args.label;
+      try {
+        await store.replaceInBlock(scope, label, args.oldText, args.newText);
+        return `Updated memory block ${scope}:${label}.`;
+      } catch (err) {
+        const errorMsg = getErrorMessage(store);
+        if (errorMsg) {
+          return errorMsg;
+        }
+        const msg = err instanceof Error ? err.message : "Unknown error";
+        return `⚠️ Failed to replace in memory block: ${msg}`;
+      }
+    },
+  });
+}
+
+export type JournalContext = {
+  directory: string;
+  model: string;
+  provider: string;
+};
+
+export function JournalWrite(
+  store: JournalStore,
+  ctx: JournalContext,
+) {
+  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\".",
+    args: {
+      title: tool.schema.string(),
+      body: tool.schema.string(),
+      tags: tool.schema.string().optional(),
+    },
+    async execute(args, toolCtx) {
+      const tags = args.tags
+        ? args.tags
+            .split(",")
+            .map((t: string) => t.trim())
+            .filter(Boolean)
+        : undefined;
+
+      const entry = await store.write({
+        title: args.title,
+        body: args.body,
+        project: ctx.directory,
+        model: ctx.model,
+        provider: ctx.provider,
+        agent: toolCtx.agent,
+        sessionId: toolCtx.sessionID,
+        tags,
+      });
+
+      return `Journal entry created: ${entry.id}\n  title: ${entry.title}\n  created: ${entry.created.toISOString()}`;
+    },
+  });
+}
+
+export function JournalRead(store: JournalStore) {
+  return tool({
+    description:
+      "Read a specific journal entry by its ID. Returns the full entry " +
+      "including metadata and body.",
+    args: {
+      id: tool.schema.string(),
+    },
+    async execute(args) {
+      const entry = await store.read(args.id);
+
+      const meta = [
+        `title: ${entry.title}`,
+        `created: ${entry.created.toISOString()}`,
+        entry.project ? `project: ${entry.project}` : null,
+        entry.model ? `model: ${entry.model}` : null,
+        entry.provider ? `provider: ${entry.provider}` : null,
+        entry.agent ? `agent: ${entry.agent}` : null,
+        entry.sessionId ? `session: ${entry.sessionId}` : null,
+        entry.tags.length > 0
+          ? `tags: ${entry.tags.join(", ")}`
+          : null,
+      ]
+        .filter(Boolean)
+        .join("\n");
+
+      return `${meta}\n\n${entry.body}`;
+    },
+  });
+}
+
+export function JournalSearch(store: JournalStore) {
+  return tool({
+    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.",
+    args: {
+      text: tool.schema.string().optional(),
+      project: tool.schema.string().optional(),
+      tags: tool.schema.string().optional(),
+      limit: tool.schema.number().int().positive().optional(),
+      offset: tool.schema.number().int().nonnegative().optional(),
+    },
+    async execute(args) {
+      const tags = args.tags
+        ? args.tags
+            .split(",")
+            .map((t: string) => t.trim())
+            .filter(Boolean)
+        : undefined;
+
+      const result = await store.search({
+        text: args.text,
+        project: args.project,
+        tags,
+        limit: args.limit,
+        offset: args.offset,
+      });
+
+      if (result.entries.length === 0) {
+        const tagsLine =
+          result.allTags.length > 0
+            ? `\nTags in use: ${result.allTags.join(", ")}`
+            : "";
+        return `No journal entries found.${tagsLine}`;
+      }
+
+      const offset = args.offset ?? 0;
+      const header = `Found ${result.total} entries (showing ${offset + 1}–${offset + result.entries.length}):`;
+      const tagsLine =
+        result.allTags.length > 0
+          ? `\nTags in use: ${result.allTags.join(", ")}`
+          : "";
+
+      const lines = result.entries.map((e) => {
+        const tagStr =
+          e.tags.length > 0
+            ? ` [${e.tags.join(", ")}]`
+            : "";
+        return `${e.id}\n  ${e.title}${tagStr}\n  ${e.created.toISOString()}`;
+      });
+
+      return `${header}${tagsLine}\n\n${lines.join("\n\n")}`;
+    },
+  });
+}