toon-memory 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# toon-memory
+
+Persistent memory system for [OpenCode](https://opencode.ai) AI agent using TOON format.
+
+**40% fewer tokens than JSON** for the same data. The agent remembers decisions, patterns, and bugs between sessions.
+
+## Install
+
+```bash
+# In your project
+npm install toon-memory @toon-format/toon
+npx toon-memory
+```
+
+Or globally:
+
+```bash
+npm install -g toon-memory @toon-format/toon
+# Then in any project:
+npx toon-memory
+```
+
+## What it does
+
+Copies 3 files to your project:
+
+| File | Purpose |
+|------|---------|
+| `.opencode/tools/memory.ts` | 5 tools for the AI agent |
+| `.opencode/memory/data.toon` | Your project's memory (TOON format) |
+| `.opencode/skills/toon-memory.md` | Usage instructions |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_remember` | Save a decision, pattern, bug, or knowledge |
+| `memory_recall` | Search memory (use BEFORE reading files) |
+| `memory_forget` | Remove an entry by key or id |
+| `memory_stats` | View memory state |
+| `memory_summary` | Save/retrieve file summaries |
+
+## How it works
+
+The agent stores entries in TOON format (Token-Oriented Object Notation):
+
+```
+version: 1
+entries[2|]{id|category|key|content|file|tags|date}:
+  a1b2c3d4|decision|use-pandas|Use pandas for time series|indicators.py|python;analytics|2026-07-10
+  e5f6g7h8|bug|redis-pool|max_connections missing|redis.adapter.ts|redis;pool|2026-07-10
+summaries:
+  path/to/file.py: Brief summary of what this file does
+```
+
+## Token savings
+
+| Format | Tokens (10 entries) | vs JSON |
+|--------|---------------------|---------|
+| JSON | ~800 | baseline |
+| YAML | ~650 | -19% |
+| **TOON** | **~480** | **-40%** |
+
+## License
+
+MIT

package/bin/setup.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync } from "fs"
+import { join, dirname } from "path"
+import { fileURLToPath } from "url"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const PROJECT_ROOT = process.cwd()
+const TOOLS_DIR = join(PROJECT_ROOT, ".opencode", "tools")
+const MEMORY_DIR = join(PROJECT_ROOT, ".opencode", "memory")
+const MEMORY_FILE = join(MEMORY_DIR, "data.toon")
+const SKILL_DIR = join(PROJECT_ROOT, ".opencode", "skills")
+const SKILL_FILE = join(SKILL_DIR, "toon-memory.md")
+const PKG_DIR = join(__dirname, "..")
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+}
+
+function main() {
+  console.log("🧠 toon-memory — Installing persistent memory for OpenCode...\n")
+
+  // 1. Copy tool file
+  ensureDir(TOOLS_DIR)
+  const toolSrc = join(PKG_DIR, "src", "memory.ts")
+  const toolDest = join(TOOLS_DIR, "memory.ts")
+  copyFileSync(toolSrc, toolDest)
+  console.log(`  ✅ Tool: ${toolDest}`)
+
+  // 2. Create memory directory and initial data file
+  ensureDir(MEMORY_DIR)
+  if (!existsSync(MEMORY_FILE)) {
+    writeFileSync(MEMORY_FILE, "version: 1\nentries[0|]:\nsummaries:\n", "utf-8")
+    console.log(`  ✅ Memory: ${MEMORY_FILE}`)
+  } else {
+    console.log(`  ⏭️  Memory already exists: ${MEMORY_FILE}`)
+  }
+
+  // 3. Copy SKILL.md
+  ensureDir(SKILL_DIR)
+  const skillSrc = join(PKG_DIR, "skills", "toon-memory.md")
+  if (existsSync(skillSrc)) {
+    copyFileSync(skillSrc, SKILL_FILE)
+    console.log(`  ✅ Skill: ${SKILL_FILE}`)
+  }
+
+  // 4. Check if @toon-format/toon is installed
+  const pkgPath = join(PROJECT_ROOT, "package.json")
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"))
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+    if (!deps["@toon-format/toon"]) {
+      console.log("\n  ⚠️  @toon-format/toon not found in dependencies.")
+      console.log("     Run: npm install @toon-format/toon")
+    }
+  }
+
+  console.log("\n🎉 Done! Restart OpenCode to load the memory tools.")
+  console.log("\nUsage:")
+  console.log("  memory_stats     — See memory state")
+  console.log("  memory_remember  — Save a decision/pattern/bug")
+  console.log("  memory_recall    — Search memory before reading files")
+  console.log("  memory_forget    — Remove an entry")
+  console.log("  memory_summary   — Save/retrieve file summaries")
+}
+
+main()

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "toon-memory",
+  "version": "1.0.0",
+  "description": "Persistent memory system for OpenCode AI agent using TOON format (40% fewer tokens than JSON)",
+  "type": "module",
+  "bin": {
+    "toon-memory": "./bin/setup.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "skills/"
+  ],
+  "dependencies": {
+    "@toon-format/toon": "^2.3.0"
+  },
+  "keywords": [
+    "opencode",
+    "ai-agent",
+    "memory",
+    "toon",
+    "llm",
+    "token-efficiency"
+  ],
+  "license": "MIT"
+}

package/skills/toon-memory.md

@@ -0,0 +1,68 @@
+# toon-memory — Persistent Memory for OpenCode
+
+## What is this?
+
+A persistent memory system for the OpenCode AI agent. It remembers decisions, patterns, bugs, and knowledge **between sessions** using TOON format (40% fewer tokens than JSON).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_remember` | Save a decision, pattern, bug, or knowledge |
+| `memory_recall` | Search memory (use BEFORE reading files) |
+| `memory_forget` | Remove an entry by key or id |
+| `memory_stats` | View memory state |
+| `memory_summary` | Save/retrieve file summaries |
+
+## How to use
+
+### At the START of every session
+
+1. Run `memory_stats` to see what's in memory.
+2. If the user asks something that might be in memory → `memory_recall(query)` BEFORE reading files.
+
+### When making decisions
+
+- Before implementing a non-trivial change → `memory_remember(category='decision')`
+- When you resolve a complex bug → `memory_remember(category='bug')`
+- When you observe a code pattern → `memory_remember(category='pattern')`
+
+### When exploring the project
+
+1. First: `memory_recall(query="what you need to know")`
+2. If no result: use CodeGraph or grep
+3. Only if both fail: read files directly
+
+### At the END of every session
+
+1. If you made design decisions → `memory_remember(category='decision')`
+2. If you resolved a bug → `memory_remember(category='bug')`
+3. If you observed a pattern → `memory_remember(category='pattern')`
+
+## Categories
+
+| Category | When | Example |
+|----------|------|---------|
+| `decision` | Non-trivial design decision | "Use pandas instead of numpy for time series" |
+| `pattern` | Observed code pattern | "This project uses Pydantic v2 for configs" |
+| `bug` | Complex bug resolved | "Redis pool exhaustion, missing max_connections" |
+| `knowledge` | General project knowledge | "Broker uses RESP protocol, not Redis-specific" |
+
+## File format
+
+Data is stored in `.opencode/memory/data.toon` using TOON (Token-Oriented Object Notation):
+
+```
+version: 1
+entries[2|]{id|category|key|content|file|tags|date}:
+  a1b2c3d4|decision|risk-priority|Risk Engine has priority|spec.md:145|risk;spec|2026-07-10
+  e5f6g7h8|pattern|pandas-over-numpy|Analytics uses pandas|indicators.py|python;analytics|2026-07-10
+summaries:
+  path/to/big-file.py: Brief summary of what this file does
+```
+
+## Anti-patterns
+
+- Don't store trivia in memory (only important facts)
+- Don't forget to save a decision before implementing
+- Don't re-read files that already have a summary in `memory_summary`

package/src/memory.ts

@@ -0,0 +1,244 @@
+import { tool } from "@opencode-ai/plugin"
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs"
+import * as path from "path"
+import { encode, decode } from "@toon-format/toon"
+import { randomUUID } from "crypto"
+
+const MEMORY_DIR = path.join(process.cwd(), ".opencode", "memory")
+const MEMORY_FILE = path.join(MEMORY_DIR, "data.toon")
+
+interface MemoryEntry {
+  id: string
+  category: "decision" | "pattern" | "bug" | "knowledge"
+  key: string
+  content: string
+  file: string
+  tags: string
+  date: string
+}
+
+interface MemoryData {
+  version: number
+  entries: MemoryEntry[]
+  summaries: Record<string, string>
+}
+
+function defaultData(): MemoryData {
+  return { version: 1, entries: [], summaries: {} }
+}
+
+function ensureDir() {
+  if (!existsSync(MEMORY_DIR)) mkdirSync(MEMORY_DIR, { recursive: true })
+}
+
+function readMemory(): MemoryData {
+  ensureDir()
+  if (!existsSync(MEMORY_FILE)) return defaultData()
+  try {
+    const raw = readFileSync(MEMORY_FILE, "utf-8")
+    const parsed = decode(raw) as MemoryData
+    if (!parsed || typeof parsed !== "object") return defaultData()
+    if (!Array.isArray(parsed.entries)) parsed.entries = []
+    if (!parsed.summaries || typeof parsed.summaries !== "object") parsed.summaries = {}
+    return parsed
+  } catch {
+    return defaultData()
+  }
+}
+
+function writeMemory(data: MemoryData): void {
+  ensureDir()
+  const toon = encode(data, { delimiter: "|", indent: 2 })
+  writeFileSync(MEMORY_FILE, toon, "utf-8")
+}
+
+function genId(): string {
+  return randomUUID().slice(0, 8)
+}
+
+export const memory_remember = tool({
+  description:
+    "Guarda un hecho en la memoria persistente del proyecto (decisiones, patrones, bugs, conocimiento). Se recuerda entre sesiones. Usar cuando el agente tome una decisión importante, resuelva un bug, o observe un patrón.",
+  args: {
+    category: tool.schema
+      .enum(["decision", "pattern", "bug", "knowledge"])
+      .describe("Categoría: decision (diseño), pattern (código), bug (resolución), knowledge (general)"),
+    key: tool.schema
+      .string()
+      .describe("Título corto en kebab-case (ej: risk-engine-prioridad)"),
+    content: tool.schema
+      .string()
+      .describe("Contenido detallado del hecho"),
+    file: tool.schema
+      .string()
+      .describe("Archivo o línea relacionada (ej: spec.md:145)")
+      .default(""),
+    tags: tool.schema
+      .string()
+      .describe("Tags separados por punto y coma (ej: risk;spec)")
+      .default(""),
+  },
+  async execute({ category, key, content, file, tags }) {
+    const state = readMemory()
+    const existing = state.entries.find(
+      (e) => e.category === category && e.key === key,
+    )
+    const entry: MemoryEntry = {
+      id: existing?.id || genId(),
+      category,
+      key,
+      content,
+      file,
+      tags,
+      date: new Date().toISOString().slice(0, 10),
+    }
+    if (existing) {
+      const idx = state.entries.indexOf(existing)
+      state.entries[idx] = entry
+    } else {
+      state.entries.push(entry)
+    }
+    writeMemory(state)
+    return {
+      title: existing ? "🧠 Actualizado" : "🧠 Guardado",
+      output: `${category}/${key} (${entry.id})\n${content}`,
+    }
+  },
+})
+
+export const memory_recall = tool({
+  description:
+    "Busca en la memoria persistente del proyecto. Devuelve entradas relevantes por categoría, tag, o texto libre. Usar ANTES de leer archivos para evitar re-investigar.",
+  args: {
+    query: tool.schema
+      .string()
+      .describe("Texto a buscar (busca en key, content, tags)"),
+    category: tool.schema
+      .string()
+      .describe("Filtrar por categoría (decision|pattern|bug|knowledge). Vacío = todos.")
+      .default(""),
+  },
+  async execute({ query, category }) {
+    const state = readMemory()
+    const q = query.toLowerCase()
+    let results = state.entries.filter((e) => {
+      const matchText =
+        e.key.toLowerCase().includes(q) ||
+        e.content.toLowerCase().includes(q) ||
+        e.tags.toLowerCase().includes(q)
+      const matchCat = category ? e.category === category : true
+      return matchText && matchCat
+    })
+    results = results.slice(0, 10)
+    if (results.length === 0) {
+      return {
+        title: "🔍 Sin resultados",
+        output: `No encontré nada para "${query}"${category ? ` en categoría "${category}"` : ""}.`,
+      }
+    }
+    const output = results
+      .map(
+        (e) =>
+          `[${e.category}] ${e.key} (${e.id})\n  ${e.content}\n  File: ${e.file || "N/A"} | Tags: ${e.tags || "N/A"} | Date: ${e.date}`,
+      )
+      .join("\n\n")
+    return { title: `🔍 ${results.length} resultados`, output }
+  },
+})
+
+export const memory_forget = tool({
+  description: "Elimina una entrada de la memoria por su key o id.",
+  args: {
+    key: tool.schema
+      .string()
+      .describe("Key o id de la entrada a eliminar"),
+  },
+  async execute({ key }) {
+    const state = readMemory()
+    const before = state.entries.length
+    state.entries = state.entries.filter(
+      (e) => e.key !== key && e.id !== key,
+    )
+    if (state.entries.length === before) {
+      return {
+        title: "⚠️ No encontrado",
+        output: `No encontré "${key}" en la memoria.`,
+      }
+    }
+    writeMemory(state)
+    return {
+      title: "🗑️ Eliminado",
+      output: `"${key}" eliminado. Quedan ${state.entries.length} entradas.`,
+    }
+  },
+})
+
+export const memory_stats = tool({
+  description:
+    "Muestra estadísticas de la memoria: total entradas, por categoría, y resúmenes de archivos.",
+  args: {},
+  async execute() {
+    const state = readMemory()
+    const byCategory: Record<string, number> = {}
+    for (const e of state.entries) {
+      byCategory[e.category] = (byCategory[e.category] || 0) + 1
+    }
+    const catStr = Object.entries(byCategory)
+      .map(([k, v]) => `  ${k}: ${v}`)
+      .join("\n")
+    const recent = state.entries
+      .slice(-5)
+      .reverse()
+      .map((e) => `  [${e.category}] ${e.key} (${e.date})`)
+      .join("\n")
+    return {
+      title: "📊 Memoria del proyecto",
+      output: [
+        `Entradas totales: ${state.entries.length}`,
+        `Resúmenes de archivos: ${Object.keys(state.summaries).length}`,
+        "",
+        "Por categoría:",
+        catStr || "  (vacío)",
+        "",
+        "Últimas 5 entradas:",
+        recent || "  (ninguna)",
+      ].join("\n"),
+    }
+  },
+})
+
+export const memory_summary = tool({
+  description:
+    "Guarda o recupera un resumen de un archivo grande. El agente puede leer el resumen en vez del archivo completo para ahorrar tokens.",
+  args: {
+    action: tool.schema
+      .enum(["get", "set"])
+      .describe("get para leer, set para guardar"),
+    file: tool.schema
+      .string()
+      .describe("Ruta del archivo"),
+    summary: tool.schema
+      .string()
+      .describe("Resumen del archivo (solo para set)")
+      .default(""),
+  },
+  async execute({ action, file, summary }) {
+    const state = readMemory()
+    if (action === "get") {
+      const s = state.summaries[file]
+      if (!s) {
+        return {
+          title: "📄 Sin resumen",
+          output: `No hay resumen para "${file}". Usar memory_summary action=set para guardar uno.`,
+        }
+      }
+      return { title: `📄 ${file}`, output: s }
+    }
+    state.summaries[file] = summary
+    writeMemory(state)
+    return {
+      title: "📄 Resumen guardado",
+      output: `${file} actualizado.`,
+    }
+  },
+})