toon-memory 1.4.0 → 1.6.1

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,16 +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
 
-- **6 MCP tools** — `memory_remember`, `memory_recall`, `memory_forget`, `memory_stats`, `memory_summary`, `memory_archive`
+- **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
 
 ---
 
@@ -81,7 +110,7 @@ memory_remember   # Save important decisions
 
 ---
 
-## Tools
+## MCP Tools
 
 | Tool | Description |
 |------|-------------|
@@ -91,13 +120,36 @@ memory_remember   # Save important decisions
 | `memory_stats` | View memory state |
 | `memory_summary` | Save/retrieve file summaries |
 | `memory_archive` | Archive old entries (>30 days) |
+| `memory_encrypt` | Enable AES-256-GCM encryption |
+| `memory_decrypt` | Disable encryption |
+
+### Examples
 
-### Date Filtering
+#### Remember a decision
+
+```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 memory by date range:
+#### Search with date filter
 
 ```typescript
-// Search with date filter
 memory_recall({
   query: "redis",
   from_date: "2026-07-01",
@@ -105,36 +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
 ```
 
----
-
-## 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
+#### Enable encryption
 
-### 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
+```typescript
+memory_encrypt()
+// 🔐 Encriptación habilitada
+// ⚠️ Guarda esta clave (no se puede recuperar):
+// a1b2c3d4...
 ```
 
 ---
@@ -149,11 +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 [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
@@ -171,7 +211,7 @@ Last updated: 2026-07-10
 File size: 12.4 KB
 ```
 
-### Export
+#### Export
 
 ```bash
 $ npx toon-memory export
@@ -182,7 +222,7 @@ Exported 45 entries to:
   /path/to/project/toon-memory-export.json
 ```
 
-### Import
+#### Import
 
 ```bash
 $ npx toon-memory import backup.json
@@ -193,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
@@ -246,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:
@@ -257,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
 
 ---
 
@@ -272,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, cpSync, 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");
@@ -112,10 +113,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 +344,134 @@ ${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");
+  const backupDir = join(projectRoot, ".opencode", "memory", "backups");
+  if (!existsSync(memoryFile)) {
+    console.log("Memory not initialized. Run 'npx toon-memory init' first.\n");
+    return;
+  }
+  if (!existsSync(backupDir)) mkdirSync(backupDir, { recursive: true });
+  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 = () => {
+    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, 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", () => {
+    clearInterval(interval);
+    process.exit(0);
+  });
+}
 const args = process.argv.slice(2);
 if (args[0] === "uninstall") {
   uninstall();
@@ -364,6 +501,10 @@ if (args[0] === "import") {
   importMemory();
   process.exit(0);
 }
+if (args[0] === "watch") {
+  watch();
+  process.exit(0);
+}
 const agents = detectAgents();
 console.log("\n\u{1F9E0} toon-memory installer\n");
 console.log("Supported agents:");

package/mcp/server.js

@@ -27642,25 +27642,82 @@ var StdioServerTransport = class {
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { randomBytes } from "crypto";
+import { randomBytes, createCipheriv, createDecipheriv } from "crypto";
 var __dirname = dirname(fileURLToPath(import.meta.url));
 var MEMORY_DIR = join(process.cwd(), ".opencode", "memory");
 var MEMORY_FILE = join(MEMORY_DIR, "data.toon");
 var ARCHIVE_FILE = join(MEMORY_DIR, "archive.toon");
+var CONFIG_FILE = join(MEMORY_DIR, "config.json");
 var ARCHIVE_DAYS = 30;
-function ensureMemoryFile() {
+var ALGORITHM = "aes-256-gcm";
+function loadConfig() {
+  if (!existsSync(CONFIG_FILE)) {
+    return { encrypted: false };
+  }
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+  } catch {
+    return { encrypted: false };
+  }
+}
+function saveConfig(config2) {
+  ensureMemoryDir();
+  writeFileSync(CONFIG_FILE, JSON.stringify(config2, null, 2));
+}
+function ensureMemoryDir() {
   if (!existsSync(MEMORY_DIR)) mkdirSync(MEMORY_DIR, { recursive: true });
+}
+function ensureMemoryFile() {
+  ensureMemoryDir();
   if (!existsSync(MEMORY_FILE)) {
     writeFileSync(MEMORY_FILE, "version: 1\nentries[0|]{id|category|key|content|file|tags|date}:\n");
   }
 }
+function encrypt(text, key) {
+  const keyBuffer = Buffer.from(key, "hex");
+  const iv = randomBytes(16);
+  const cipher = createCipheriv(ALGORITHM, keyBuffer, iv);
+  let encrypted = cipher.update(text, "utf8", "hex");
+  encrypted += cipher.final("hex");
+  const authTag = cipher.getAuthTag();
+  return `${iv.toString("hex")}:${authTag.toString("hex")}:${encrypted}`;
+}
+function decrypt(encryptedData, key) {
+  const keyBuffer = Buffer.from(key, "hex");
+  const [ivHex, authTagHex, encrypted] = encryptedData.split(":");
+  const iv = Buffer.from(ivHex, "hex");
+  const authTag = Buffer.from(authTagHex, "hex");
+  const decipher = createDecipheriv(ALGORITHM, keyBuffer, iv);
+  decipher.setAuthTag(authTag);
+  let decrypted = decipher.update(encrypted, "hex", "utf8");
+  decrypted += decipher.final("utf8");
+  return decrypted;
+}
+function generateKey() {
+  return randomBytes(32).toString("hex");
+}
 function readMemory() {
   ensureMemoryFile();
-  return readFileSync(MEMORY_FILE, "utf-8");
+  const config2 = loadConfig();
+  const data = readFileSync(MEMORY_FILE, "utf-8");
+  if (config2.encrypted && config2.key) {
+    try {
+      return decrypt(data, config2.key);
+    } catch {
+      return data;
+    }
+  }
+  return data;
 }
 function writeMemory(content) {
   ensureMemoryFile();
-  writeFileSync(MEMORY_FILE, content);
+  const config2 = loadConfig();
+  if (config2.encrypted && config2.key) {
+    const encrypted = encrypt(content, config2.key);
+    writeFileSync(MEMORY_FILE, encrypted);
+  } else {
+    writeFileSync(MEMORY_FILE, content);
+  }
 }
 function generateId() {
   return randomBytes(4).toString("hex");
@@ -27928,6 +27985,60 @@ server.registerTool(
     };
   }
 );
+server.registerTool(
+  "memory_encrypt",
+  {
+    title: "Enable Encryption",
+    description: "Habilita encriptaci\xF3n AES-256-GCM para la memoria. La clave se genera autom\xE1ticamente.",
+    inputSchema: {}
+  },
+  async () => {
+    const config2 = loadConfig();
+    if (config2.encrypted) {
+      return { content: [{ type: "text", text: "La encriptaci\xF3n ya est\xE1 habilitada" }] };
+    }
+    const key = generateKey();
+    const data = readFileSync(MEMORY_FILE, "utf-8");
+    const encrypted = encrypt(data, key);
+    writeFileSync(MEMORY_FILE, encrypted);
+    saveConfig({ encrypted: true, key });
+    return {
+      content: [{
+        type: "text",
+        text: `\u{1F510} Encriptaci\xF3n habilitada
+\u26A0\uFE0F Guarda esta clave (no se puede recuperar):
+${key}`
+      }]
+    };
+  }
+);
+server.registerTool(
+  "memory_decrypt",
+  {
+    title: "Disable Encryption",
+    description: "Deshabilita la encriptaci\xF3n y decodifica la memoria.",
+    inputSchema: {
+      key: external_exports.string().describe("Clave de encriptaci\xF3n")
+    }
+  },
+  async ({ key }) => {
+    const config2 = loadConfig();
+    if (!config2.encrypted) {
+      return { content: [{ type: "text", text: "La encriptaci\xF3n no est\xE1 habilitada" }] };
+    }
+    try {
+      const data = readFileSync(MEMORY_FILE, "utf-8");
+      const decrypted = decrypt(data, key);
+      writeFileSync(MEMORY_FILE, decrypted);
+      saveConfig({ encrypted: false });
+      return {
+        content: [{ type: "text", text: "\u{1F513} Encriptaci\xF3n deshabilitada" }]
+      };
+    } catch {
+      return { content: [{ type: "text", text: "\u274C Clave incorrecta o datos corruptos" }] };
+    }
+  }
+);
 var transport = new StdioServerTransport();
 await server.connect(transport);
 /*! Bundled license information:

package/package.json

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