toon-memory 1.0.5 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toon-memory",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Persistent memory system for OpenCode AI agent using TOON format (40% fewer tokens than JSON)",
   "type": "module",
   "bin": {

package/skills/toon-memory.md

@@ -0,0 +1,113 @@
+# 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 |
+
+## Installation
+
+### Option 1: Interactive installer (recommended)
+
+```bash
+npx toon-memory
+```
+
+This will:
+1. Detect installed agents (OpenCode, Claude, Cursor)
+2. Ask if you want local or global installation
+3. Configure the MCP server automatically
+
+### Option 2: Global MCP Server
+
+Add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "mcp": {
+    "toon-memory": {
+      "type": "local",
+      "command": ["npx", "-y", "toon-memory", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+### Option 3: Project-level MCP Server
+
+Add to `.opencode/opencode.json`:
+
+```json
+{
+  "mcp": {
+    "toon-memory": {
+      "type": "local",
+      "command": ["npx", "-y", "toon-memory", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+## 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/mcp/server.ts

@@ -0,0 +1,251 @@
+import { McpServer } from "@modelcontextprotocol/server"
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio"
+import { z } from "zod"
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs"
+import { dirname, join } from "path"
+import { fileURLToPath } from "url"
+import { randomBytes } from "crypto"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const MEMORY_DIR = join(process.cwd(), ".opencode", "memory")
+const MEMORY_FILE = join(MEMORY_DIR, "data.toon")
+
+function ensureMemoryFile() {
+  if (!existsSync(MEMORY_DIR)) mkdirSync(MEMORY_DIR, { recursive: true })
+  if (!existsSync(MEMORY_FILE)) {
+    writeFileSync(MEMORY_FILE, "version: 1\nentries[0|]{id|category|key|content|file|tags|date}:\n")
+  }
+}
+
+function readMemory() {
+  ensureMemoryFile()
+  return readFileSync(MEMORY_FILE, "utf-8")
+}
+
+function writeMemory(content: string) {
+  ensureMemoryFile()
+  writeFileSync(MEMORY_FILE, content)
+}
+
+function generateId(): string {
+  return randomBytes(4).toString("hex")
+}
+
+const server = new McpServer(
+  { name: "toon-memory", version: "1.0.7" },
+  { capabilities: { tools: { listChanged: true } } }
+)
+
+server.registerTool(
+  "memory_remember",
+  {
+    title: "Save to Memory",
+    description: "Guarda un hecho en la memoria persistente del proyecto (decisiones, patrones, bugs, conocimiento). Se recuerda entre sesiones.",
+    inputSchema: {
+      category: z.enum(["decision", "pattern", "bug", "knowledge"]).describe("Categoría del hecho"),
+      key: z.string().describe("Título corto en kebab-case (ej: risk-engine-prioridad)"),
+      content: z.string().describe("Contenido detallado del hecho"),
+      file: z.string().optional().default("").describe("Archivo o línea relacionada (ej: spec.md:145)"),
+      tags: z.string().optional().default("").describe("Tags separados por punto y coma (ej: risk;spec)"),
+    },
+  },
+  async ({ category, key, content, file, tags }) => {
+    const data = readMemory()
+    const id = generateId()
+    const date = new Date().toISOString().split("T")[0]
+    const lines = data.split("\n")
+
+    let headerIdx = lines.findIndex((l) => l.startsWith("entries["))
+    if (headerIdx === -1) {
+      lines.push(`entries[0|]{id|category|key|content|file|tags|date}:`)
+      headerIdx = lines.length - 1
+    }
+
+    const match = lines[headerIdx].match(/entries\[(\d+)\|/)
+    const count = match ? parseInt(match[1]) : 0
+    const newEntry = `${id}|${category}|${key}|${content}|${file || ""}|${tags || ""}|${date}`
+
+    lines.splice(headerIdx + 1, 0, `  ${newEntry}`)
+    lines[headerIdx] = lines[headerIdx].replace(/entries\[\d+\|/, `[${count + 1}|`)
+
+    writeMemory(lines.join("\n"))
+    return {
+      content: [{ type: "text" as const, text: `🧠 Guardado: ${category}/${key} (${id})\n${content}` }],
+    }
+  }
+)
+
+server.registerTool(
+  "memory_recall",
+  {
+    title: "Search Memory",
+    description: "Busca en la memoria persistente del proyecto. Devuelve entradas relevantes. Usar ANTES de leer archivos.",
+    inputSchema: {
+      query: z.string().describe("Texto a buscar"),
+      category: z.string().optional().default("").describe("Filtrar por categoría (vacío = todos)"),
+    },
+  },
+  async ({ query, category }) => {
+    const data = readMemory()
+    const lines = data.split("\n").filter((l) => l.startsWith("  ") && l.includes("|"))
+    const queryLower = query.toLowerCase()
+
+    const results = lines
+      .map((line) => {
+        const trimmed = line.trim()
+        const parts = trimmed.split("|")
+        if (parts.length < 7) return null
+        const [id, cat, key, content, file, tags, date] = parts
+        if (category && cat !== category) return null
+        const searchStr = `${id} ${cat} ${key} ${content} ${file} ${tags}`.toLowerCase()
+        if (!searchStr.includes(queryLower)) return null
+        return { id, cat, key, content, file, tags, date }
+      })
+      .filter(Boolean)
+
+    if (results.length === 0) {
+      return { content: [{ type: "text" as const, text: `No se encontraron resultados para "${query}"` }] }
+    }
+
+    const formatted = results
+      .map((r) => `[${r!.cat}] ${r!.key} (${r!.id})\n  ${r!.content}\n  File: ${r!.file} | Tags: ${r!.tags} | Date: ${r!.date}`)
+      .join("\n\n")
+
+    return { content: [{ type: "text" as const, text: formatted }] }
+  }
+)
+
+server.registerTool(
+  "memory_forget",
+  {
+    title: "Delete from Memory",
+    description: "Elimina una entrada de la memoria por su key o id.",
+    inputSchema: {
+      key: z.string().describe("Key o id de la entrada a eliminar"),
+    },
+  },
+  async ({ key }) => {
+    const data = readMemory()
+    const lines = data.split("\n")
+    const headerIdx = lines.findIndex((l) => l.startsWith("entries["))
+
+    if (headerIdx === -1) {
+      return { content: [{ type: "text" as const, text: "No hay entradas en memoria" }] }
+    }
+
+    const entryLines = lines.slice(headerIdx + 1).filter((l) => l.trim().length > 0)
+    const filtered = entryLines.filter((l) => {
+      const parts = l.trim().split("|")
+      return parts[0] !== key && parts[2] !== key
+    })
+
+    const removed = entryLines.length - filtered.length
+    const match = lines[headerIdx].match(/entries\[(\d+)\|/)
+    const count = match ? parseInt(match[1]) : 0
+    lines[headerIdx] = lines[headerIdx].replace(/entries\[\d+\|/, `[${count - removed}|`)
+    lines.splice(headerIdx + 1, entryLines.length, ...filtered.map((l) => `  ${l.trim()}`))
+
+    writeMemory(lines.join("\n"))
+    return {
+      content: [{ type: "text" as const, text: `"${key}" eliminado. Quedan ${count - removed} entradas.` }],
+    }
+  }
+)
+
+server.registerTool(
+  "memory_stats",
+  {
+    title: "Memory Stats",
+    description: "Muestra estadísticas de la memoria del proyecto.",
+    inputSchema: {},
+  },
+  async () => {
+    const data = readMemory()
+    const lines = data.split("\n").filter((l) => l.startsWith("  ") && l.includes("|"))
+    const entries = lines.map((l) => {
+      const parts = l.trim().split("|")
+      return { category: parts[1] || "unknown" }
+    })
+
+    const byCategory: Record<string, number> = {}
+    for (const e of entries) {
+      byCategory[e.category] = (byCategory[e.category] || 0) + 1
+    }
+
+    const summaryLines = data.split("\n").filter((l) => l.includes(":") && !l.startsWith("  ") && !l.startsWith("version") && !l.startsWith("entries"))
+    const stats = [
+      `Entradas totales: ${entries.length}`,
+      `Resúmenes de archivos: ${summaryLines.length}`,
+      "",
+      "Por categoría:",
+      ...Object.entries(byCategory).map(([k, v]) => `  ${k}: ${v}`),
+      "",
+      `Últimas 5 entradas:`,
+      ...lines.slice(-5).map((l) => {
+        const parts = l.trim().split("|")
+        return `  [${parts[1]}] ${parts[2]} (${parts[0]})`
+      }),
+    ]
+
+    return { content: [{ type: "text" as const, text: stats.join("\n") }] }
+  }
+)
+
+server.registerTool(
+  "memory_summary",
+  {
+    title: "File Summary",
+    description: "Guarda o recupera un resumen de un archivo grande para ahorrar tokens.",
+    inputSchema: {
+      action: z.enum(["get", "set"]).describe("get para leer, set para guardar"),
+      file: z.string().describe("Ruta del archivo"),
+      summary: z.string().optional().default("").describe("Resumen del archivo (solo para set)"),
+    },
+  },
+  async ({ action, file, summary }) => {
+    const data = readMemory()
+
+    if (action === "get") {
+      const lines = data.split("\n")
+      const summaryIdx = lines.findIndex((l) => l.trim().startsWith("summaries:"))
+      if (summaryIdx === -1) {
+        return { content: [{ type: "text" as const, text: `No hay resúmenes guardados para "${file}"` }] }
+      }
+
+      const summaryLines = lines.slice(summaryIdx + 1).filter((l) => l.includes(":"))
+      const match = summaryLines.find((l) => l.startsWith(`  ${file}:`))
+      if (!match) {
+        return { content: [{ type: "text" as const, text: `No hay resumen para "${file}"` }] }
+      }
+
+      const summaryText = match.replace(`  ${file}: `, "")
+      return { content: [{ type: "text" as const, text: summaryText }] }
+    }
+
+    const lines = data.split("\n")
+    let summaryIdx = lines.findIndex((l) => l.trim().startsWith("summaries:"))
+
+    if (summaryIdx === -1) {
+      lines.push("", "summaries:")
+      summaryIdx = lines.length - 1
+    }
+
+    const summaryLines = lines.slice(summaryIdx + 1).filter((l) => l.includes(":"))
+    const existingIdx = summaryLines.findIndex((l) => l.startsWith(`  ${file}:`))
+
+    if (existingIdx !== -1) {
+      summaryLines[existingIdx] = `  ${file}: ${summary}`
+    } else {
+      summaryLines.push(`  ${file}: ${summary}`)
+    }
+
+    lines.splice(summaryIdx + 1, lines.length - summaryIdx - 1, ...summaryLines)
+    writeMemory(lines.join("\n"))
+    return {
+      content: [{ type: "text" as const, text: `📝 Resumen guardado para ${file}` }],
+    }
+  }
+)
+
+const transport = new StdioServerTransport()
+await server.connect(transport)

package/src/memory.ts

@@ -0,0 +1,237 @@
+import { tool } from "@opencode-ai/plugin"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs"
+import { dirname, join } from "path"
+import { fileURLToPath } from "url"
+import { randomBytes } from "crypto"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const MEMORY_DIR = join(__dirname, "..", "memory")
+const MEMORY_FILE = join(MEMORY_DIR, "data.toon")
+
+function ensureMemoryFile() {
+  if (!existsSync(MEMORY_DIR)) mkdirSync(MEMORY_DIR, { recursive: true })
+  if (!existsSync(MEMORY_FILE)) {
+    writeFileSync(MEMORY_FILE, "version: 1\nentries[0|]{id|category|key|content|file|tags|date}:\n")
+  }
+}
+
+function readMemory() {
+  ensureMemoryFile()
+  return readFileSync(MEMORY_FILE, "utf-8")
+}
+
+function writeMemory(content: string) {
+  ensureMemoryFile()
+  writeFileSync(MEMORY_FILE, content)
+}
+
+function generateId(): string {
+  return randomBytes(4).toString("hex")
+}
+
+export const memoryRemember = tool({
+  description: "Guarda un hecho en la memoria persistente del proyecto (decisiones, patrones, bugs, conocimiento). Se recuerda entre sesiones.",
+  args: {
+    category: tool.schema.enum({
+      description: "Categoría del hecho",
+      options: ["decision", "pattern", "bug", "knowledge"],
+    }),
+    key: tool.schema.string({
+      description: "Título corto en kebab-case (ej: risk-engine-prioridad)",
+    }),
+    content: tool.schema.string({
+      description: "Contenido detallado del hecho",
+    }),
+    file: tool.schema.string({
+      description: "Archivo o línea relacionada (ej: spec.md:145)",
+    }),
+    tags: tool.schema.string({
+      description: "Tags separados por punto y coma (ej: risk;spec)",
+    }),
+  },
+  async execute(args) {
+    const data = readMemory()
+    const id = generateId()
+    const date = new Date().toISOString().split("T")[0]
+    const lines = data.split("\n")
+
+    let headerIdx = lines.findIndex((l) => l.startsWith("entries["))
+    if (headerIdx === -1) {
+      lines.push(`entries[0|]{id|category|key|content|file|tags|date}:`)
+      headerIdx = lines.length - 1
+    }
+
+    const match = lines[headerIdx].match(/entries\[(\d+)\|/)
+    const count = match ? parseInt(match[1]) : 0
+    const newEntry = `${id}|${args.category}|${args.key}|${args.content}|${args.file || ""}|${args.tags || ""}|${date}`
+
+    lines.splice(headerIdx + 1, 0, `  ${newEntry}`)
+    lines[headerIdx] = lines[headerIdx].replace(/entries\[\d+\|/, `[${count + 1}|`)
+
+    writeMemory(lines.join("\n"))
+    return `🧠 Guardado: ${args.category}/${args.key} (${id})\n${args.content}`
+  },
+})
+
+export const memoryRecall = 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({
+      description: "Texto a buscar (busca en key, content, tags)",
+    }),
+    category: tool.schema.string({
+      description: "Filtrar por categoría (decision|pattern|bug|knowledge). Vacío = todos.",
+    }),
+  },
+  async execute(args) {
+    const data = readMemory()
+    const lines = data.split("\n").filter((l) => l.startsWith("  ") && l.includes("|"))
+    const queryLower = args.query.toLowerCase()
+
+    const results = lines
+      .map((line) => {
+        const trimmed = line.trim()
+        const parts = trimmed.split("|")
+        if (parts.length < 7) return null
+        const [id, cat, key, content, file, tags, date] = parts
+        if (args.category && cat !== args.category) return null
+        const searchStr = `${id} ${cat} ${key} ${content} ${file} ${tags}`.toLowerCase()
+        if (!searchStr.includes(queryLower)) return null
+        return { id, cat, key, content, file, tags, date }
+      })
+      .filter(Boolean)
+
+    if (results.length === 0) {
+      return `No se encontraron resultados para "${args.query}"`
+    }
+
+    return results
+      .map((r) => `[${r!.cat}] ${r!.key} (${r!.id})\n  ${r!.content}\n  File: ${r!.file} | Tags: ${r!.tags} | Date: ${r!.date}`)
+      .join("\n\n")
+  },
+})
+
+export const memoryForget = tool({
+  description: "Elimina una entrada de la memoria por su key o id.",
+  args: {
+    key: tool.schema.string({
+      description: "Key o id de la entrada a eliminar",
+    }),
+  },
+  async execute(args) {
+    const data = readMemory()
+    const lines = data.split("\n")
+    const headerIdx = lines.findIndex((l) => l.startsWith("entries["))
+
+    if (headerIdx === -1) {
+      return "No hay entradas en memoria"
+    }
+
+    const entryLines = lines.slice(headerIdx + 1).filter((l) => l.trim().length > 0)
+    const filtered = entryLines.filter((l) => {
+      const parts = l.trim().split("|")
+      return parts[0] !== args.key && parts[2] !== args.key
+    })
+
+    const removed = entryLines.length - filtered.length
+    const match = lines[headerIdx].match(/entries\[(\d+)\|/)
+    const count = match ? parseInt(match[1]) : 0
+    lines[headerIdx] = lines[headerIdx].replace(/entries\[\d+\|/, `[${count - removed}|`)
+    lines.splice(headerIdx + 1, entryLines.length, ...filtered.map((l) => `  ${l.trim()}`))
+
+    writeMemory(lines.join("\n"))
+    return `"${args.key}" eliminado. Quedan ${count - removed} entradas.`
+  },
+})
+
+export const memoryStats = tool({
+  description: "Muestra estadísticas de la memoria: total entradas, por categoría, y resúmenes de archivos.",
+  args: {},
+  async execute() {
+    const data = readMemory()
+    const lines = data.split("\n").filter((l) => l.startsWith("  ") && l.includes("|"))
+    const entries = lines.map((l) => {
+      const parts = l.trim().split("|")
+      return { category: parts[1] || "unknown" }
+    })
+
+    const byCategory: Record<string, number> = {}
+    for (const e of entries) {
+      byCategory[e.category] = (byCategory[e.category] || 0) + 1
+    }
+
+    const summaryLines = data.split("\n").filter((l) => l.includes(":") && !l.startsWith("  ") && !l.startsWith("version") && !l.startsWith("entries"))
+    const stats = [
+      `Entradas totales: ${entries.length}`,
+      `Resúmenes de archivos: ${summaryLines.length}`,
+      "",
+      "Por categoría:",
+      ...Object.entries(byCategory).map(([k, v]) => `  ${k}: ${v}`),
+      "",
+      `Últimas 5 entradas:`,
+      ...lines.slice(-5).map((l) => {
+        const parts = l.trim().split("|")
+        return `  [${parts[1]}] ${parts[2]} (${parts[0]})`
+      }),
+    ]
+
+    return stats.join("\n")
+  },
+})
+
+export const memorySummary = 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({
+      description: "get para leer, set para guardar",
+      options: ["get", "set"],
+    }),
+    file: tool.schema.string({
+      description: "Ruta del archivo",
+    }),
+    summary: tool.schema.string({
+      description: "Resumen del archivo (solo para set)",
+    }),
+  },
+  async execute(args) {
+    const data = readMemory()
+
+    if (args.action === "get") {
+      const lines = data.split("\n")
+      const summaryIdx = lines.findIndex((l) => l.trim().startsWith("summaries:"))
+      if (summaryIdx === -1) {
+        return `No hay resúmenes guardados para "${args.file}"`
+      }
+
+      const summaryLines = lines.slice(summaryIdx + 1).filter((l) => l.includes(":"))
+      const match = summaryLines.find((l) => l.startsWith(`  ${args.file}:`))
+      if (!match) {
+        return `No hay resumen para "${args.file}"`
+      }
+
+      const summaryText = match.replace(`  ${args.file}: `, "")
+      return summaryText
+    }
+
+    const lines = data.split("\n")
+    let summaryIdx = lines.findIndex((l) => l.trim().startsWith("summaries:"))
+
+    if (summaryIdx === -1) {
+      lines.push("", "summaries:")
+      summaryIdx = lines.length - 1
+    }
+
+    const summaryLines = lines.slice(summaryIdx + 1).filter((l) => l.includes(":"))
+    const existingIdx = summaryLines.findIndex((l) => l.startsWith(`  ${args.file}:`))
+
+    if (existingIdx !== -1) {
+      summaryLines[existingIdx] = `  ${args.file}: ${args.summary}`
+    } else {
+      summaryLines.push(`  ${args.file}: ${args.summary}`)
+    }
+
+    lines.splice(summaryIdx + 1, lines.length - summaryIdx - 1, ...summaryLines)
+    writeMemory(lines.join("\n"))
+    return `📝 Resumen guardado para ${args.file}`
+  },
+})