toon-memory 1.5.0 → 1.6.2

package/README.md

@@ -1,10 +1,29 @@
 # toon-memory
 
-Persistent memory for AI coding agents — remember decisions, patterns, and bugs between sessions.
+> Persistent memory for AI coding agents — remember decisions, patterns, and bugs between sessions.
 
 [![npm version](https://img.shields.io/npm/v/toon-memory.svg)](https://www.npmjs.com/package/toon-memory)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/LuiggiVal08/toon-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/LuiggiVal08/toon-memory/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-online-blue)](https://luiggival08.github.io/toon-memory/)
+
+---
+
+## Table of Contents
+
+- [What is toon-memory?](#what-is-toon-memory)
+- [Blog Post](#blog-post)
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Supported Agents](#supported-agents)
+- [MCP Tools](#mcp-tools)
+- [CLI Commands](#cli-commands)
+- [Configuration](#configuration)
+- [How It Works](#how-it-works)
+- [Why TOON?](#why-toon)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
 ---
 
@@ -12,6 +31,8 @@ Persistent memory for AI coding agents — remember decisions, patterns, and bug
 
 AI agents forget everything between sessions. toon-memory fixes this by providing persistent memory that survives restarts.
 
+📖 **[Read the documentation](https://luiggival08.github.io/toon-memory/)**
+
 **Use cases:**
 - Remember design decisions ("Why did we choose X over Y?")
 - Track patterns ("This project uses Zod for validation")
@@ -20,18 +41,24 @@ AI agents forget everything between sessions. toon-memory fixes this by providin
 
 ---
 
+## Blog Post
+
+Read [How toon-memory Makes Your AI Agent Smarter](https://luiggival08.github.io/toon-memory/blog) to see a real-world demo of persistent memory in action.
+
+---
+
 ## Features
 
-- **8 MCP tools** — `memory_remember`, `memory_recall`, `memory_forget`, `memory_stats`, `memory_summary`, `memory_archive`, `memory_encrypt`, `memory_decrypt`
+- **8 MCP tools** — Full memory management via Model Context Protocol
 - **7 agents supported** — OpenCode, VS Code/Copilot, Claude Code, Cursor, Windsurf, Cline, Continue
 - **TOON format** — 40% fewer tokens than JSON, better LLM comprehension
-- **Per-project memory** — each project gets its own memory file
-- **Zero config** — just install and use
-- **Auto gitignore** — automatically adds `.opencode/memory/` to `.gitignore`
-- **Date filtering** — search memory by date range
-- **Auto-archive** — old entries (>30 days) moved to archive automatically
+- **Per-project memory** — Each project gets its own memory file
+- **Zero config** — Just install and use
+- **Auto gitignore** — Automatically adds `.opencode/memory/` to `.gitignore`
+- **Date filtering** — Search memory by date range
+- **Auto-archive** — Old entries (>30 days) moved to archive automatically
 - **Encryption** — AES-256-GCM encryption for sensitive data
-- **Watch mode** — auto-backup every N minutes
+- **Watch mode** — Auto-backup every N minutes
 
 ---
 
@@ -83,7 +110,7 @@ memory_remember   # Save important decisions
 
 ---
 
-## Tools
+## MCP Tools
 
 | Tool | Description |
 |------|-------------|
@@ -96,12 +123,33 @@ memory_remember   # Save important decisions
 | `memory_encrypt` | Enable AES-256-GCM encryption |
 | `memory_decrypt` | Disable encryption |
 
-### Date Filtering
+### Examples
+
+#### Remember a decision
 
-Search memory by date range:
+```typescript
+memory_remember({
+  category: "decision",
+  key: "use-zod",
+  content: "Use Zod for validation",
+  file: "src/types.ts",
+  tags: "validation;types"
+})
+// 🧠 Guardado: decision/use-zod (a1b2c3d4)
+```
+
+#### Search memory
+
+```typescript
+memory_recall({ query: "redis" })
+// [bug] redis-pool-fix (i9j0k1l2)
+//   Added max_connections=20
+//   File: redis.ts | Tags: redis;fix | Date: 2026-07-10
+```
+
+#### Search with date filter
 
 ```typescript
-// Search with date filter
 memory_recall({
   query: "redis",
   from_date: "2026-07-01",
@@ -109,52 +157,21 @@ memory_recall({
 })
 ```
 
-### Auto-Archive
-
-Entries older than 30 days are automatically archived to keep memory clean:
+#### Archive old entries
 
 ```typescript
-// Manually trigger archiving
 memory_archive()
 // 📦 Archivadas 5 entradas antiguas
 // 📋 Quedan 42 entradas activas
 ```
 
-### Encryption
-
-Enable AES-256-GCM encryption for sensitive data:
+#### Enable encryption
 
 ```typescript
-// Enable encryption
 memory_encrypt()
 // 🔐 Encriptación habilitada
 // ⚠️ Guarda esta clave (no se puede recuperar):
 // a1b2c3d4...
-
-// Disable encryption
-memory_decrypt({ key: "a1b2c3d4..." })
-// 🔓 Encriptación deshabilitada
-```
-
----
-
-## How It Works
-
-1. **MCP Server** — runs locally, talks to your agent via stdio
-2. **TOON Format** — stores data in Token-Oriented Object Notation (~40% fewer tokens than JSON)
-3. **Per-project memory** — each project gets `.opencode/memory/data.toon`
-4. **Zero config** — just install and use
-
-### Memory File Format
-
-```
-version: 1
-entries[3|]{id|category|key|content|file|tags|date}:
-  a1b2c3d4|decision|use-zod|Use Zod for validation|src/types.ts|validation;types|2026-07-10
-  e5f6g7h8|pattern|pydantic-configs|Project uses Pydantic v2|config.py|python;patterns|2026-07-10
-  i9j0k1l2|bug|redis-pool-fix|Added max_connections=20|redis.ts|redis;fix|2026-07-10
-summaries:
-  src/services/redis.ts: Redis connection pool with retry logic
 ```
 
 ---
@@ -169,12 +186,14 @@ npx toon-memory status       # Check installation status
 npx toon-memory stats        # View memory statistics
 npx toon-memory export       # Export memory to JSON
 npx toon-memory import <file> # Import memory from JSON
-npx toon-memory watch [mins] # Auto-backup every N minutes (default: 5)
+npx toon-memory watch [options] # Auto-backup with options
 npx toon-memory upgrade      # Update to latest version
 npx toon-memory uninstall    # Remove from all agents
 ```
 
-### Stats
+### Examples
+
+#### Stats
 
 ```bash
 $ npx toon-memory stats
@@ -192,7 +211,7 @@ Last updated: 2026-07-10
 File size: 12.4 KB
 ```
 
-### Export
+#### Export
 
 ```bash
 $ npx toon-memory export
@@ -203,7 +222,7 @@ Exported 45 entries to:
   /path/to/project/toon-memory-export.json
 ```
 
-### Import
+#### Import
 
 ```bash
 $ npx toon-memory import backup.json
@@ -214,6 +233,34 @@ Imported 3 new entries
 Skipped 2 duplicates
 ```
 
+#### Watch
+
+```bash
+$ npx toon-memory watch 15 -c -m 20
+
+🧠 toon-memory watch
+
+Watching memory file every 15 minutes...
+Max backups: 20
+Compression: enabled
+Logging: disabled
+Press Ctrl+C to stop
+
+📦 Backup #1 created: 2026-07-11T16-00-00-000Z
+📦 Backup #2 created: 2026-07-11T16-15-00-000Z
+^C
+✅ Watch stopped. 2 backups created.
+```
+
+**Watch Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `[interval]` | Backup interval in minutes | 5 |
+| `-c, --compress` | Enable gzip compression | off |
+| `-l, --log [path]` | Enable file logging | off |
+| `-m, --max-backups <n>` | Max backups to keep (0=unlimited) | 10 |
+
 ---
 
 ## Configuration
@@ -267,6 +314,41 @@ Add to `.vscode/mcp.json`:
 
 ---
 
+## How It Works
+
+1. **MCP Server** — Runs locally, talks to your agent via stdio
+2. **TOON Format** — Stores data in Token-Oriented Object Notation (~40% fewer tokens than JSON)
+3. **Per-project memory** — Each project gets `.opencode/memory/data.toon`
+4. **Zero config** — Just install and use
+
+### Memory File Format
+
+```
+version: 1
+entries[3|]{id|category|key|content|file|tags|date}:
+  a1b2c3d4|decision|use-zod|Use Zod for validation|src/types.ts|validation;types|2026-07-10
+  e5f6g7h8|pattern|pydantic-configs|Project uses Pydantic v2|config.py|python;patterns|2026-07-10
+  i9j0k1l2|bug|redis-pool-fix|Added max_connections=20|redis.ts|redis;fix|2026-07-10
+summaries:
+  src/services/redis.ts: Redis connection pool with retry logic
+```
+
+### File Structure
+
+```
+.opencode/
+├── memory/
+│   ├── data.toon        # Main memory file
+│   ├── archive.toon     # Archived entries (>30 days)
+│   ├── config.json      # Encryption settings
+│   └── backups/         # Watch mode backups
+│       ├── backup-2026-07-11T16-00-00-000Z.toon
+│       └── backup-2026-07-11T16-10-00-000Z.toon
+└── opencode.json        # MCP server config
+```
+
+---
+
 ## Why TOON?
 
 TOON (Token-Oriented Object Notation) is designed for LLMs:
@@ -278,8 +360,8 @@ TOON (Token-Oriented Object Notation) is designed for LLMs:
 | **TOON** | **60** | **76.4%** |
 
 - **40% fewer tokens** than JSON
-- **Lossless roundtrip** — no data loss
-- **Better LLM comprehension** — structured for AI consumption
+- **Lossless roundtrip** — No data loss
+- **Better LLM comprehension** — Structured for AI consumption
 
 ---
 
@@ -293,6 +375,30 @@ npm run build
 npm test
 ```
 
+### Project Structure
+
+```
+toon-memory/
+├── src/
+│   ├── bin/
+│   │   └── toon-memory.ts      # Entry point
+│   ├── cli/
+│   │   ├── setup.ts             # CLI commands
+│   │   └── toon-memory.ts       # CLI runner
+│   ├── mcp/
+│   │   └── server.ts            # MCP server (8 tools)
+│   └── memory.ts                # Custom tool (OpenCode)
+├── tests/
+│   ├── cli.test.ts              # CLI tests
+│   └── memory.test.ts           # Memory tests
+├── .github/workflows/
+│   ├── ci.yml                   # CI (Node.js 20/22)
+│   └── publish.yml              # Auto-publish on release
+├── package.json
+├── tsconfig.json
+└── vitest.config.ts
+```
+
 ---
 
 ## Contributing

package/dist/cli/setup.js

@@ -1,9 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync, unlinkSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, readdirSync, statSync } from "fs";
 import { basename, dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { execSync } from "child_process";
 import { createInterface } from "readline";
 import { createRequire } from "module";
+import { gzipSync, gunzipSync } from "zlib";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const projectRoot = process.cwd();
 const sourceDir = join(__dirname, "..", "..", "src");
@@ -65,15 +66,11 @@ function detectAgents() {
   return agents2;
 }
 function installOpenCodeTools() {
-  const toolsDir = join(projectRoot, ".opencode", "tools");
   const memoryDir = join(projectRoot, ".opencode", "memory");
   const memoryFile = join(memoryDir, "data.toon");
-  if (!existsSync(toolsDir)) mkdirSync(toolsDir, { recursive: true });
   if (!existsSync(memoryDir)) mkdirSync(memoryDir, { recursive: true });
-  cpSync(join(sourceDir, "memory.ts"), join(toolsDir, "memory.ts"));
-  console.log("  Copied memory.ts to .opencode/tools/");
   if (!existsSync(memoryFile)) {
-    writeFileSync(memoryFile, "version: 1\nentries[0|]{id|category|key|content|file|tags|date}:\n");
+    writeFileSync(memoryFile, "version: 1\n[0|]\n");
     console.log("  Created .opencode/memory/data.toon");
   }
 }
@@ -112,10 +109,18 @@ function installMCPConfig(agent, scope) {
   }
   const mcpKey = agent.mcpKey || "mcpServers";
   if (!config[mcpKey]) config[mcpKey] = {};
-  config[mcpKey]["toon-memory"] = {
-    command: "npx",
-    args: ["-y", "toon-memory", "mcp"]
-  };
+  if (agent.name === "opencode") {
+    config[mcpKey]["toon-memory"] = {
+      enabled: true,
+      type: "local",
+      command: ["npx", "-y", "toon-memory", "mcp"]
+    };
+  } else {
+    config[mcpKey]["toon-memory"] = {
+      command: "npx",
+      args: ["-y", "toon-memory", "mcp"]
+    };
+  }
   writeFileSync(configPath, JSON.stringify(config, null, 2));
   console.log(`  MCP server added to ${configPath}`);
 }
@@ -335,6 +340,56 @@ ${newLines}
   console.log(`Skipped ${importData.entries.length - newEntries.length} duplicates
 `);
 }
+function parseWatchOptions(args2) {
+  const opts = {
+    interval: 5,
+    maxBackups: 10,
+    compress: false,
+    logFile: false,
+    logPath: ""
+  };
+  for (let i = 1; i < args2.length; i++) {
+    const arg = args2[i];
+    if (arg === "--compress" || arg === "-c") {
+      opts.compress = true;
+    } else if (arg === "--log" || arg === "-l") {
+      opts.logFile = true;
+      opts.logPath = args2[++i] || join(projectRoot, ".opencode", "memory", "watch.log");
+    } else if (arg === "--max-backups" || arg === "-m") {
+      opts.maxBackups = parseInt(args2[++i]) || 10;
+    } else if (!arg.startsWith("-")) {
+      opts.interval = parseInt(arg) || 5;
+    }
+  }
+  return opts;
+}
+function writeWatchLog(logPath, message) {
+  if (!logPath) return;
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const logLine = `[${timestamp}] ${message}
+`;
+  writeFileSync(logPath, logLine, { flag: "a" });
+}
+function getBackupFiles(backupDir) {
+  if (!existsSync(backupDir)) return [];
+  return readdirSync(backupDir).filter((f) => f.startsWith("backup-") && (f.endsWith(".toon") || f.endsWith(".gz"))).map((f) => join(backupDir, f)).sort((a, b) => statSync(a).mtimeMs - statSync(b).mtimeMs);
+}
+function pruneBackups(backupDir, maxBackups) {
+  if (maxBackups <= 0) return 0;
+  const files = getBackupFiles(backupDir);
+  const excess = files.length - maxBackups;
+  if (excess <= 0) return 0;
+  for (let i = 0; i < excess; i++) {
+    unlinkSync(files[i]);
+  }
+  return excess;
+}
+function compressData(data) {
+  return gzipSync(Buffer.from(data, "utf-8"));
+}
+function decompressData(data) {
+  return gunzipSync(data).toString("utf-8");
+}
 function watch() {
   console.log("\n\u{1F9E0} toon-memory watch\n");
   const memoryFile = join(projectRoot, ".opencode", "memory", "data.toon");
@@ -344,30 +399,68 @@ function watch() {
     return;
   }
   if (!existsSync(backupDir)) mkdirSync(backupDir, { recursive: true });
-  const intervalMinutes = parseInt(args[1]) || 5;
-  console.log(`Watching memory file every ${intervalMinutes} minutes...`);
+  const opts = parseWatchOptions(args);
+  if (opts.logFile) {
+    const logDir = dirname(opts.logPath);
+    if (!existsSync(logDir)) mkdirSync(logDir, { recursive: true });
+  }
+  console.log(`Watching memory file every ${opts.interval} minutes...`);
+  console.log(`Max backups: ${opts.maxBackups === 0 ? "unlimited" : opts.maxBackups}`);
+  console.log(`Compression: ${opts.compress ? "enabled" : "disabled"}`);
+  console.log(`Logging: ${opts.logFile ? `enabled (${opts.logPath})` : "disabled"}`);
   console.log(`Press Ctrl+C to stop
 `);
   let lastContent = readFileSync(memoryFile, "utf-8");
+  let lastHash = hashContent(lastContent);
   let backupCount = 0;
+  if (opts.logFile) writeWatchLog(opts.logPath, "Watch started");
   const backup = () => {
-    const currentContent = readFileSync(memoryFile, "utf-8");
-    if (currentContent !== lastContent) {
-      const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-      const backupFile = join(backupDir, `backup-${timestamp}.toon`);
-      writeFileSync(backupFile, currentContent);
-      backupCount++;
-      console.log(`\u{1F4E6} Backup #${backupCount} created: ${timestamp}`);
-      lastContent = currentContent;
+    try {
+      const currentContent = readFileSync(memoryFile, "utf-8");
+      const currentHash = hashContent(currentContent);
+      if (currentHash !== lastHash) {
+        const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+        const ext = opts.compress ? ".toon.gz" : ".toon";
+        const backupFile = join(backupDir, `backup-${timestamp}${ext}`);
+        if (opts.compress) {
+          writeFileSync(backupFile, compressData(currentContent));
+        } else {
+          writeFileSync(backupFile, currentContent);
+        }
+        backupCount++;
+        console.log(`\u{1F4E6} Backup #${backupCount} created: ${timestamp}`);
+        if (opts.logFile) writeWatchLog(opts.logPath, `Backup #${backupCount}: ${timestamp}`);
+        lastContent = currentContent;
+        lastHash = currentHash;
+        const pruned = pruneBackups(backupDir, opts.maxBackups);
+        if (pruned > 0) {
+          console.log(`\u{1F5D1}\uFE0F  Pruned ${pruned} old backup(s)`);
+          if (opts.logFile) writeWatchLog(opts.logPath, `Pruned ${pruned} old backup(s)`);
+        }
+      }
+    } catch (err) {
+      const msg = `Error creating backup: ${err.message}`;
+      console.error(`\u274C ${msg}`);
+      if (opts.logFile) writeWatchLog(opts.logPath, msg);
     }
   };
+  function hashContent(content) {
+    let hash = 0;
+    for (let i = 0; i < content.length; i++) {
+      const char = content.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash;
+    }
+    return hash.toString(36);
+  }
   backup();
-  const interval = setInterval(backup, intervalMinutes * 60 * 1e3);
+  const interval = setInterval(backup, opts.interval * 60 * 1e3);
   process.on("SIGINT", () => {
     clearInterval(interval);
     console.log(`
 \u2705 Watch stopped. ${backupCount} backups created.
 `);
+    if (opts.logFile) writeWatchLog(opts.logPath, `Watch stopped. ${backupCount} backups created.`);
     process.exit(0);
   });
   process.on("SIGTERM", () => {

package/mcp/server.js

@@ -27796,16 +27796,16 @@ server.registerTool(
     const id = generateId();
     const date5 = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
     const lines = data.split("\n");
-    let headerIdx = lines.findIndex((l) => l.startsWith("entries["));
+    let headerIdx = lines.findIndex((l) => l.startsWith("entries[") || /^\[\d+\|]/.test(l));
     if (headerIdx === -1) {
-      lines.push(`entries[0|]{id|category|key|content|file|tags|date}:`);
+      lines.push(`[0|]`);
       headerIdx = lines.length - 1;
     }
-    const match = lines[headerIdx].match(/entries\[(\d+)\|/);
+    const match = lines[headerIdx].match(/\[(\d+)\|/);
     const count = match ? parseInt(match[1]) : 0;
     const newEntry = `${id}|${category}|${key}|${content}|${file2 || ""}|${tags || ""}|${date5}`;
     lines.splice(headerIdx + 1, 0, `  ${newEntry}`);
-    lines[headerIdx] = lines[headerIdx].replace(/entries\[\d+\|/, `[${count + 1}|`);
+    lines[headerIdx] = lines[headerIdx].replace(/\[\d+\|/, `[${count + 1}|`);
     writeMemory(lines.join("\n"));
     return {
       content: [{ type: "text", text: `\u{1F9E0} Guardado: ${category}/${key} (${id})
@@ -27827,7 +27827,7 @@ server.registerTool(
   },
   async ({ query, category, from_date, to_date }) => {
     const data = readMemory();
-    const lines = data.split("\n").filter((l) => l.startsWith("  ") && l.includes("|"));
+    const lines = data.split("\n").filter((l) => l.startsWith("  ") && l.includes("|") && !l.startsWith("summaries:"));
     const queryLower = query.toLowerCase();
     const results = lines.map((line) => {
       const trimmed = line.trim();
@@ -27862,19 +27862,19 @@ server.registerTool(
   async ({ key }) => {
     const data = readMemory();
     const lines = data.split("\n");
-    const headerIdx = lines.findIndex((l) => l.startsWith("entries["));
+    const headerIdx = lines.findIndex((l) => l.startsWith("entries[") || /^\[\d+\|]/.test(l));
     if (headerIdx === -1) {
       return { content: [{ type: "text", text: "No hay entradas en memoria" }] };
     }
-    const entryLines = lines.slice(headerIdx + 1).filter((l) => l.trim().length > 0);
+    const entryLines = lines.slice(headerIdx + 1).filter((l) => l.trim().length > 0 && !l.startsWith("summaries:"));
     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 match = lines[headerIdx].match(/\[(\d+)\|/);
     const count = match ? parseInt(match[1]) : 0;
-    lines[headerIdx] = lines[headerIdx].replace(/entries\[\d+\|/, `[${count - removed}|`);
+    lines[headerIdx] = lines[headerIdx].replace(/\[\d+\|/, `[${count - removed}|`);
     lines.splice(headerIdx + 1, entryLines.length, ...filtered.map((l) => `  ${l.trim()}`));
     writeMemory(lines.join("\n"));
     return {
@@ -27891,7 +27891,7 @@ server.registerTool(
   },
   async () => {
     const data = readMemory();
-    const lines = data.split("\n").filter((l) => l.startsWith("  ") && l.includes("|"));
+    const lines = data.split("\n").filter((l) => l.startsWith("  ") && l.includes("|") && !l.startsWith("  summaries:"));
     const entries = lines.map((l) => {
       const parts = l.trim().split("|");
       return { category: parts[1] || "unknown" };
@@ -27900,7 +27900,7 @@ server.registerTool(
     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 summaryLines = data.split("\n").filter((l) => l.includes(":") && !l.startsWith("  ") && !l.startsWith("version") && !l.startsWith("entries") && !/^\[\d+\|]/.test(l));
     const stats = [
       `Entradas totales: ${entries.length}`,
       `Res\xFAmenes de archivos: ${summaryLines.length}`,

package/package.json

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