toon-memory 1.0.3 → 1.0.5

package/skills/toon-memory.md

@@ -1,68 +0,0 @@
-# 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/mcp/server.ts

@@ -1,307 +0,0 @@
-#!/usr/bin/env node
-
-import { McpServer } from "@modelcontextprotocol/server"
-import { serveStdio } from "@modelcontextprotocol/server/stdio"
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs"
-import * as path from "path"
-import { encode, decode } from "@toon-format/toon"
-import { randomUUID } from "crypto"
-import * as z from "zod/v4"
-
-// ── Memory storage ──────────────────────────────
-
-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)
-}
-
-// ── MCP Server ──────────────────────────────────
-
-serveStdio(() => {
-  const server = new McpServer({
-    name: "toon-memory",
-    version: "1.0.1",
-  })
-
-  // Tool: memory_remember
-  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: z.object({
-        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()
-          .describe("Archivo o línea relacionada (ej: spec.md:145)")
-          .default(""),
-        tags: z
-          .string()
-          .describe("Tags separados por punto y coma (ej: risk;spec)")
-          .default(""),
-      }),
-    },
-    async ({ 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 {
-        content: [
-          {
-            type: "text" as const,
-            text: `${existing ? "🧠 Actualizado" : "🧠 Guardado"}: ${category}/${key} (${entry.id})\n${content}`,
-          },
-        ],
-      }
-    },
-  )
-
-  // Tool: memory_recall
-  server.registerTool(
-    "memory_recall",
-    {
-      title: "Search Memory",
-      description:
-        "Busca en la memoria persistente del proyecto. Devuelve entradas relevantes. Usar ANTES de leer archivos.",
-      inputSchema: z.object({
-        query: z.string().describe("Texto a buscar"),
-        category: z
-          .string()
-          .describe("Filtrar por categoría (vacío = todos)")
-          .default(""),
-      }),
-    },
-    async ({ 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 {
-          content: [
-            {
-              type: "text" as const,
-              text: `No encontré nada para "${query}"${category ? ` en "${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 { content: [{ type: "text" as const, text: output }] }
-    },
-  )
-
-  // Tool: memory_forget
-  server.registerTool(
-    "memory_forget",
-    {
-      title: "Delete from Memory",
-      description: "Elimina una entrada de la memoria por su key o id.",
-      inputSchema: z.object({
-        key: z.string().describe("Key o id de la entrada a eliminar"),
-      }),
-    },
-    async ({ 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 {
-          content: [
-            {
-              type: "text" as const,
-              text: `No encontré "${key}" en la memoria.`,
-            },
-          ],
-        }
-      }
-      writeMemory(state)
-      return {
-        content: [
-          {
-            type: "text" as const,
-            text: `"${key}" eliminado. Quedan ${state.entries.length} entradas.`,
-          },
-        ],
-      }
-    },
-  )
-
-  // Tool: memory_stats
-  server.registerTool(
-    "memory_stats",
-    {
-      title: "Memory Stats",
-      description: "Muestra estadísticas de la memoria del proyecto.",
-      inputSchema: z.object({}),
-    },
-    async () => {
-      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 {
-        content: [
-          {
-            type: "text" as const,
-            text: [
-              `Entradas totales: ${state.entries.length}`,
-              `Resúmenes de archivos: ${Object.keys(state.summaries).length}`,
-              "",
-              "Por categoría:",
-              catStr || "  (vacío)",
-              "",
-              "Últimas 5:",
-              recent || "  (ninguna)",
-            ].join("\n"),
-          },
-        ],
-      }
-    },
-  )
-
-  // Tool: memory_summary
-  server.registerTool(
-    "memory_summary",
-    {
-      title: "File Summary",
-      description:
-        "Guarda o recupera un resumen de un archivo grande para ahorrar tokens.",
-      inputSchema: z.object({
-        action: z.enum(["get", "set"]).describe("get para leer, set para guardar"),
-        file: z.string().describe("Ruta del archivo"),
-        summary: z
-          .string()
-          .describe("Resumen del archivo (solo para set)")
-          .default(""),
-      }),
-    },
-    async ({ action, file, summary }) => {
-      const state = readMemory()
-      if (action === "get") {
-        const s = state.summaries[file]
-        if (!s) {
-          return {
-            content: [
-              {
-                type: "text" as const,
-                text: `No hay resumen para "${file}".`,
-              },
-            ],
-          }
-        }
-        return { content: [{ type: "text" as const, text: s }] }
-      }
-      state.summaries[file] = summary
-      writeMemory(state)
-      return {
-        content: [
-          {
-            type: "text" as const,
-            text: `${file} actualizado.`,
-          },
-        ],
-      }
-    },
-  )
-
-  return server
-})

package/src/memory.ts

@@ -1,244 +0,0 @@
-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.`,
-    }
-  },
-})