@ghilteras/opencode-agent-memory 0.3.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Josh Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# opencode-agent-memory
+
+> **Fork notice**: This is the maintained fork `@ghilteras/opencode-agent-memory` v0.3.0 of
+> [opencode-agent-memory](https://github.com/joshuadavidthomas/opencode-agent-memory)
+> (joshuadavidthomas, MIT). 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.
+
+[Letta](https://letta.com)-style editable [memory blocks](https://docs.letta.com/guides/agents/memory-blocks/) for [OpenCode](https://opencode.ai).
+
+## 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.
+
+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/).
+
+## 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
+
+## Requirements
+
+- [OpenCode](https://opencode.ai/) v1.0.115 or later
+
+## Installation
+
+Add to your OpenCode config (`~/.config/opencode/opencode.json`):
+
+```json
+{
+  "plugin": ["opencode-agent-memory"]
+}
+```
+
+Restart OpenCode and you're ready to go.
+
+Optionally, pin to a specific version for stability:
+
+```json
+{
+  "plugin": ["opencode-agent-memory@0.2.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/joshuadavidthomas/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 ([all-MiniLM-L6-v2](https://huggingface.co/Xenova/all-MiniLM-L6-v2)) - no data leaves your machine.
+
+### Default Blocks
+
+Three blocks are seeded on first run:
+
+| 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) |
+
+These are just starting points. Create whatever blocks make sense for your workflow - `debugging-notes`, `api-preferences`, `learned-patterns`, etc.
+
+### Memory Locations
+
+- **Global blocks**: `~/.config/opencode/memory/*.md`
+- **Project blocks**: `.opencode/memory/*.md` (auto-gitignored)
+
+### Block Format
+
+Each block is a markdown file with YAML frontmatter:
+
+| 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 |
+
+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).
+
+### Journal Configuration
+
+The journal is opt-in. Enable it in `~/.config/opencode/agent-memory.json`:
+
+```json
+{
+  "journal": {
+    "enabled": true
+  }
+}
+```
+
+You can optionally suggest tags to guide the agent's classification:
+
+```json
+{
+  "journal": {
+    "enabled": true,
+    "tags": [
+      { "name": "perf", "description": "Performance optimization work" },
+      { "name": "debugging", "description": "Debugging sessions and findings" }
+    ]
+  }
+}
+```
+
+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
+
+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.
+
+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.
+
+## Contributing
+
+Contributions are welcome! Here's how to set up for development:
+
+```bash
+git clone https://github.com/joshuadavidthomas/opencode-agent-memory
+cd opencode-agent-memory
+bun install
+```
+
+Then symlink the plugin to your OpenCode config:
+
+```bash
+mkdir -p ~/.config/opencode/plugin
+ln -sf "$(pwd)/src/plugin.ts" ~/.config/opencode/plugin/memory.ts
+```
+
+## License
+
+opencode-agent-memory is licensed under the MIT license. See the [`LICENSE`](LICENSE) file for more information.
+
+---
+
+opencode-agent-memory is not built by, or affiliated with, the OpenCode team.
+
+OpenCode is ©2025 Anomaly.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ghilteras/opencode-agent-memory",
+  "version": "0.3.0",
+  "description": "Letta-style editable memory blocks + journal for OpenCode (maintained fork of opencode-agent-memory).",
+  "author": "Angelo Pantano <ghilteras@protonmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ghilteras/opencode-agent-memory.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "src/plugin.ts",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
+    "@opencode-ai/plugin": "^1.0.115",
+    "js-yaml": "^4.1.0",
+    "zod": "^4.1.13"
+  },
+  "overrides": {
+    "onnxruntime-node": "1.20.1"
+  },
+  "devDependencies": {
+    "@tsconfig/bun": "^1.0.10",
+    "@types/bun": "^1.3.3",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/embeddings.ts

@@ -0,0 +1,46 @@
+const MODEL_NAME = "Xenova/all-MiniLM-L6-v2";
+const MODEL_DTYPE = "q8";
+
+let pipelinePromise: Promise<any> | undefined;
+
+async function getPipeline() {
+  if (!pipelinePromise) {
+    pipelinePromise = (async () => {
+      const { pipeline } = await import("@huggingface/transformers");
+      return pipeline("feature-extraction", MODEL_NAME, {
+        dtype: MODEL_DTYPE,
+      });
+    })();
+  }
+  return pipelinePromise;
+}
+
+export async function generateEmbedding(text: string): Promise<number[]> {
+  const pipe = await getPipeline();
+  const output = await pipe(text, { pooling: "mean", normalize: true });
+  return Array.from(output.data as Float32Array) as number[];
+}
+
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length) {
+    throw new Error(
+      `Embedding dimension mismatch: ${a.length} vs ${b.length}`,
+    );
+  }
+
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    const ai = a[i]!;
+    const bi = b[i]!;
+    dotProduct += ai * bi;
+    normA += ai * ai;
+    normB += bi * bi;
+  }
+
+  const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+  if (denominator === 0) return 0;
+  return dotProduct / denominator;
+}

package/src/frontmatter.ts

@@ -0,0 +1,47 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+import yaml from "js-yaml";
+
+export function splitFrontmatter(text: string): {
+  frontmatterText: string | undefined;
+  body: string;
+} {
+  if (!text.startsWith("---\n")) {
+    return { frontmatterText: undefined, body: text };
+  }
+
+  const endIndex = text.indexOf("\n---\n", 4);
+  if (endIndex === -1) {
+    return { frontmatterText: undefined, body: text };
+  }
+
+  const frontmatterText = text.slice(4, endIndex);
+  const body = text.slice(endIndex + "\n---\n".length);
+  return { frontmatterText, body };
+}
+
+export function buildFrontmatterDocument(
+  frontmatter: Record<string, unknown>,
+  body: string,
+): string {
+  const frontmatterYaml = yaml.dump(frontmatter, {
+    lineWidth: 120,
+    noRefs: true,
+    sortKeys: true,
+  });
+
+  return `---\n${frontmatterYaml}---\n${body.trim()}\n`;
+}
+
+export async function atomicWriteFile(
+  filePath: string,
+  content: string,
+): Promise<void> {
+  const tempPath = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.tmp`,
+  );
+  await fs.writeFile(tempPath, content, "utf-8");
+  await fs.rename(tempPath, filePath);
+}