toon-memory 1.5.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,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, 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,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 +403,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/package.json

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

package/src/cli/setup.ts

@@ -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()
@@ -12,10 +13,15 @@ const projectRoot = process.cwd()
 const sourceDir = join(__dirname, "..", "..", "src")
 const HOME = process.env.HOME || process.env.USERPROFILE || "~"
 
+/** Supported AI coding agent configuration */
 interface Agent {
+  /** Agent identifier (e.g., "opencode", "vscode/copilot") */
   name: string
+  /** Global config file path (e.g., ~/.config/opencode/opencode.json) */
   global?: string
+  /** Local (project-level) config file path (e.g., .opencode/opencode.json) */
   local?: string
+  /** JSON key where MCP servers are stored */
   mcpKey: string
 }
 
@@ -27,7 +33,22 @@ try {
   execSync("npm install @toon-format/toon", { cwd: projectRoot, stdio: "inherit" })
 }
 
-// Detect all supported agents
+/**
+ * Detect all supported AI coding agents on the system.
+ * 
+ * Scans for configuration files in both global (~/.config/) and local
+ * (.opencode/, .vscode/, etc.) locations.
+ * 
+ * @returns Array of detected agent configurations
+ * 
+ * @example
+ * ```typescript
+ * const agents = detectAgents()
+ * for (const agent of agents) {
+ *   console.log(`${agent.name}: ${agent.local || "not found"}`)
+ * }
+ * ```
+ */
 function detectAgents(): Agent[] {
   const agents: Agent[] = []
   
@@ -94,7 +115,17 @@ function detectAgents(): Agent[] {
   return agents
 }
 
-// Install custom tools for OpenCode
+/**
+ * Install custom tools and memory directory for OpenCode.
+ * 
+ * Creates `.opencode/tools/` and `.opencode/memory/` directories,
+ * copies `memory.ts` tool, and creates initial `data.toon` if needed.
+ * 
+ * @example
+ * ```bash
+ * npx toon-memory init  # Calls installOpenCodeTools()
+ * ```
+ */
 function installOpenCodeTools(): void {
   const toolsDir = join(projectRoot, ".opencode", "tools")
   const memoryDir = join(projectRoot, ".opencode", "memory")
@@ -112,7 +143,17 @@ function installOpenCodeTools(): void {
   }
 }
 
-// Add .opencode/memory/ to .gitignore if not present
+/**
+ * Add `.opencode/memory/` to `.gitignore` if not already present.
+ * 
+ * Creates `.gitignore` if it doesn't exist, or appends the memory
+ * exclusion pattern to the existing file.
+ * 
+ * @example
+ * ```typescript
+ * ensureGitignore()  // Adds .opencode/memory/ to .gitignore
+ * ```
+ */
 function ensureGitignore(): void {
   const gitignorePath = join(projectRoot, ".gitignore")
   const entry = ".opencode/memory/"
@@ -130,7 +171,20 @@ function ensureGitignore(): void {
   }
 }
 
-// Install MCP server config for different agents
+/**
+ * Install MCP server configuration for an agent.
+ * 
+ * Adds the `toon-memory` MCP server entry to the agent's config file.
+ * 
+ * @param agent - Agent configuration with config path and MCP key
+ * @param scope - "global" or "local" installation scope
+ * 
+ * @example
+ * ```typescript
+ * const agent = { name: "opencode", local: ".opencode/opencode.json", mcpKey: "mcp" }
+ * installMCPConfig(agent, "local")
+ * ```
+ */
 function installMCPConfig(agent: Agent, scope: string): void {
   const configPath = scope === "global" ? agent.global : agent.local
   
@@ -154,16 +208,34 @@ function installMCPConfig(agent: Agent, scope: string): void {
   const mcpKey = agent.mcpKey || "mcpServers"
   if (!config[mcpKey]) config[mcpKey] = {}
   
-  config[mcpKey]["toon-memory"] = {
-    command: "npx",
-    args: ["-y", "toon-memory", "mcp"]
+  // OpenCode uses a different format than other agents
+  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}`)
 }
 
-// Uninstall from all agents
+/**
+ * Uninstall toon-memory from all detected agents.
+ * 
+ * Removes MCP server configurations and custom tools from all agents.
+ * 
+ * @example
+ * ```bash
+ * npx toon-memory uninstall
+ * ```
+ */
 function uninstall(): void {
   console.log("\n🧠 toon-memory uninstaller\n")
   
@@ -198,7 +270,20 @@ function uninstall(): void {
   console.log("\n✅ toon-memory uninstalled from all agents\n")
 }
 
-// Quick init without interactive prompts
+/**
+ * Initialize toon-memory for all detected agents (non-interactive).
+ * 
+ * Installs MCP server configs, creates memory directory, and
+ * updates `.gitignore`.
+ * 
+ * @param scope - "local" (default) or "global" installation scope
+ * 
+ * @example
+ * ```bash
+ * npx toon-memory init          # Local install
+ * npx toon-memory init global   # Global install
+ * ```
+ */
 function init(scope: string = "local"): void {
   console.log("\n🧠 toon-memory init\n")
   
@@ -220,7 +305,16 @@ function init(scope: string = "local"): void {
   console.log("Done! Restart your agent to use memory tools.\n")
 }
 
-// Show installation status
+/**
+ * Show toon-memory installation status.
+ * 
+ * Displays version, memory entry count, and agent configuration status.
+ * 
+ * @example
+ * ```bash
+ * npx toon-memory status
+ * ```
+ */
 function status(): void {
   console.log("\n🧠 toon-memory status\n")
   
@@ -272,7 +366,16 @@ function status(): void {
   console.log("")
 }
 
-// Upgrade to latest version
+/**
+ * Upgrade toon-memory to the latest version.
+ * 
+ * Checks npm registry for updates and installs if available.
+ * 
+ * @example
+ * ```bash
+ * npx toon-memory upgrade
+ * ```
+ */
 function upgrade(): void {
   console.log("\n🧠 toon-memory upgrade\n")
   
@@ -291,7 +394,16 @@ function upgrade(): void {
   }
 }
 
-// Show memory statistics
+/**
+ * Display memory statistics.
+ * 
+ * Shows entry counts by category, last update date, and file size.
+ * 
+ * @example
+ * ```bash
+ * npx toon-memory stats
+ * ```
+ */
 function stats(): void {
   console.log("\n🧠 toon-memory stats\n")
   
@@ -333,7 +445,17 @@ function stats(): void {
   console.log("")
 }
 
-// Export memory to JSON
+/**
+ * Export memory to JSON format.
+ * 
+ * Creates a `toon-memory-export.json` file with all entries
+ * for backup or transfer to another project.
+ * 
+ * @example
+ * ```bash
+ * npx toon-memory export
+ * ```
+ */
 function exportMemory(): void {
   console.log("\n🧠 toon-memory export\n")
   
@@ -374,7 +496,18 @@ function exportMemory(): void {
   console.log(`  ${outputPath}\n`)
 }
 
-// Import memory from JSON
+/**
+ * Import memory from JSON file.
+ * 
+ * Imports entries from a JSON export, skipping duplicates based on key.
+ * 
+ * @param file - Path to JSON file (relative or absolute)
+ * 
+ * @example
+ * ```bash
+ * npx toon-memory import toon-memory-export.json
+ * ```
+ */
 function importMemory(): void {
   console.log("\n🧠 toon-memory import\n")
   
@@ -446,7 +579,104 @@ function importMemory(): void {
   console.log(`Skipped ${importData.entries.length - newEntries.length} duplicates\n`)
 }
 
-// Watch mode - backup memory every N minutes
+/** Watch mode options */
+interface WatchOptions {
+  /** Backup interval in minutes (default: 5) */
+  interval: number
+  /** Maximum number of backups to keep (0 = unlimited) */
+  maxBackups: number
+  /** Enable gzip compression for backups */
+  compress: boolean
+  /** Enable file logging */
+  logFile: boolean
+  /** Log file path */
+  logPath: string
+}
+
+/** Parse watch CLI arguments into WatchOptions */
+function parseWatchOptions(args: string[]): WatchOptions {
+  const opts: WatchOptions = {
+    interval: 5,
+    maxBackups: 10,
+    compress: false,
+    logFile: false,
+    logPath: ""
+  }
+  
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === "--compress" || arg === "-c") {
+      opts.compress = true
+    } else if (arg === "--log" || arg === "-l") {
+      opts.logFile = true
+      opts.logPath = args[++i] || join(projectRoot, ".opencode", "memory", "watch.log")
+    } else if (arg === "--max-backups" || arg === "-m") {
+      opts.maxBackups = parseInt(args[++i]) || 10
+    } else if (!arg.startsWith("-")) {
+      opts.interval = parseInt(arg) || 5
+    }
+  }
+  
+  return opts
+}
+
+/** Write a line to the watch log file */
+function writeWatchLog(logPath: string, message: string): void {
+  if (!logPath) return
+  const timestamp = new Date().toISOString()
+  const logLine = `[${timestamp}] ${message}\n`
+  writeFileSync(logPath, logLine, { flag: "a" })
+}
+
+/** Get list of backup files sorted by creation time (oldest first) */
+function getBackupFiles(backupDir: string): string[] {
+  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)
+}
+
+/** Remove oldest backups if we exceed maxBackups */
+function pruneBackups(backupDir: string, maxBackups: number): number {
+  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
+}
+
+/** Compress content with gzip */
+function compressData(data: string): Buffer {
+  return gzipSync(Buffer.from(data, "utf-8"))
+}
+
+/** Decompress gzip data to string */
+function decompressData(data: Buffer): string {
+  return gunzipSync(data).toString("utf-8")
+}
+
+/**
+ * Watch mode - backup memory every N minutes
+ * 
+ * @example
+ * ```bash
+ * npx toon-memory watch          # Default: 5 min interval, 10 max backups
+ * npx toon-memory watch 10       # 10 minute interval
+ * npx toon-memory watch -c       # Enable compression
+ * npx toon-memory watch -l       # Enable file logging
+ * npx toon-memory watch -m 20    # Keep max 20 backups
+ * npx toon-memory watch 15 -c -l -m 5  # All options
+ * ```
+ */
 function watch(): void {
   console.log("\n🧠 toon-memory watch\n")
   
@@ -460,36 +690,83 @@ function watch(): void {
   
   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\n`)
   
   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 = new Date().toISOString().replace(/[:.]/g, "-")
-      const backupFile = join(backupDir, `backup-${timestamp}.toon`)
-      writeFileSync(backupFile, currentContent)
-      backupCount++
-      console.log(`📦 Backup #${backupCount} created: ${timestamp}`)
-      lastContent = currentContent
+    try {
+      const currentContent = readFileSync(memoryFile, "utf-8")
+      const currentHash = hashContent(currentContent)
+      
+      if (currentHash !== lastHash) {
+        const timestamp = 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(`📦 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(`🗑️  Pruned ${pruned} old backup(s)`)
+          if (opts.logFile) writeWatchLog(opts.logPath, `Pruned ${pruned} old backup(s)`)
+        }
+      }
+    } catch (err) {
+      const msg = `Error creating backup: ${(err as Error).message}`
+      console.error(`❌ ${msg}`)
+      if (opts.logFile) writeWatchLog(opts.logPath, msg)
+    }
+  }
+  
+  /** Simple hash for change detection (not cryptographic) */
+  function hashContent(content: string): string {
+    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)
   }
   
   // Initial backup
   backup()
   
   // Set interval
-  const interval = setInterval(backup, intervalMinutes * 60 * 1000)
+  const interval = setInterval(backup, opts.interval * 60 * 1000)
   
   // Handle Ctrl+C
   process.on("SIGINT", () => {
     clearInterval(interval)
     console.log(`\n✅ Watch stopped. ${backupCount} backups created.\n`)
+    if (opts.logFile) writeWatchLog(opts.logPath, `Watch stopped. ${backupCount} backups created.`)
     process.exit(0)
   })
   

package/src/mcp/server.ts

@@ -7,19 +7,49 @@ import { fileURLToPath } from "url"
 import { randomBytes, createCipheriv, createDecipheriv } from "crypto"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
+
+/** Base directory for memory storage */
 const MEMORY_DIR = join(process.cwd(), ".opencode", "memory")
+
+/** Main memory data file */
 const MEMORY_FILE = join(MEMORY_DIR, "data.toon")
+
+/** Archive file for old entries */
 const ARCHIVE_FILE = join(MEMORY_DIR, "archive.toon")
+
+/** Configuration file for encryption settings */
 const CONFIG_FILE = join(MEMORY_DIR, "config.json")
+
+/** Maximum active entries before auto-archive */
 const MAX_ENTRIES = 100
+
+/** Days before entries are archived */
 const ARCHIVE_DAYS = 30
+
+/** Encryption algorithm for AES-256-GCM */
 const ALGORITHM = "aes-256-gcm"
 
+/** Memory configuration with encryption settings */
 interface MemoryConfig {
+  /** Whether encryption is enabled */
   encrypted: boolean
+  /** Encryption key (hex-encoded, 64 chars for AES-256) */
   key?: string
 }
 
+/**
+ * Load memory configuration from config.json.
+ * 
+ * @returns MemoryConfig object with encryption settings
+ * 
+ * @example
+ * ```typescript
+ * const config = loadConfig()
+ * if (config.encrypted) {
+ *   console.log("Encryption enabled")
+ * }
+ * ```
+ */
 function loadConfig(): MemoryConfig {
   if (!existsSync(CONFIG_FILE)) {
     return { encrypted: false }
@@ -31,22 +61,46 @@ function loadConfig(): MemoryConfig {
   }
 }
 
+/**
+ * Save memory configuration to config.json.
+ * 
+ * @param config - MemoryConfig to save
+ */
 function saveConfig(config: MemoryConfig): void {
   ensureMemoryDir()
   writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2))
 }
 
-function ensureMemoryDir() {
+/**
+ * Ensure memory directory exists, creating it if necessary.
+ */
+function ensureMemoryDir(): void {
   if (!existsSync(MEMORY_DIR)) mkdirSync(MEMORY_DIR, { recursive: true })
 }
 
-function ensureMemoryFile() {
+/**
+ * Ensure memory file exists with default structure.
+ */
+function ensureMemoryFile(): void {
   ensureMemoryDir()
   if (!existsSync(MEMORY_FILE)) {
     writeFileSync(MEMORY_FILE, "version: 1\nentries[0|]{id|category|key|content|file|tags|date}:\n")
   }
 }
 
+/**
+ * Encrypt text using AES-256-GCM.
+ * 
+ * @param text - Plain text to encrypt
+ * @param key - Hex-encoded encryption key (64 chars)
+ * @returns Encrypted string in format "iv:authTag:ciphertext"
+ * 
+ * @example
+ * ```typescript
+ * const encrypted = encrypt("my secret", key)
+ * // "a1b2c3d4...:e5f6g7h8...:i9j0k1l2..."
+ * ```
+ */
 function encrypt(text: string, key: string): string {
   const keyBuffer = Buffer.from(key, "hex")
   const iv = randomBytes(16)
@@ -60,6 +114,14 @@ function encrypt(text: string, key: string): string {
   return `${iv.toString("hex")}:${authTag.toString("hex")}:${encrypted}`
 }
 
+/**
+ * Decrypt AES-256-GCM encrypted data.
+ * 
+ * @param encryptedData - Encrypted string in format "iv:authTag:ciphertext"
+ * @param key - Hex-encoded encryption key (64 chars)
+ * @returns Decrypted plain text
+ * @throws If key is invalid or data is corrupted
+ */
 function decrypt(encryptedData: string, key: string): string {
   const keyBuffer = Buffer.from(key, "hex")
   const [ivHex, authTagHex, encrypted] = encryptedData.split(":")
@@ -75,10 +137,20 @@ function decrypt(encryptedData: string, key: string): string {
   return decrypted
 }
 
+/**
+ * Generate a random 256-bit encryption key.
+ * 
+ * @returns Hex-encoded key (64 chars)
+ */
 function generateKey(): string {
   return randomBytes(32).toString("hex")
 }
 
+/**
+ * Read memory file, decrypting if encryption is enabled.
+ * 
+ * @returns Memory content as string (TOON format)
+ */
 function readMemory(): string {
   ensureMemoryFile()
   const config = loadConfig()
@@ -95,6 +167,11 @@ function readMemory(): string {
   return data
 }
 
+/**
+ * Write content to memory file, encrypting if encryption is enabled.
+ * 
+ * @param content - Memory content to write (TOON format)
+ */
 function writeMemory(content: string): void {
   ensureMemoryFile()
   const config = loadConfig()
@@ -107,10 +184,29 @@ function writeMemory(content: string): void {
   }
 }
 
+/**
+ * Generate a random 8-character hex ID for memory entries.
+ * 
+ * @returns Hex string (8 chars)
+ */
 function generateId(): string {
   return randomBytes(4).toString("hex")
 }
 
+/**
+ * Archive entries older than ARCHIVE_DAYS to archive.toon.
+ * 
+ * Moves old entries from data.toon to archive.toon to keep
+ * the active memory file manageable.
+ * 
+ * @returns Object with counts of archived and kept entries
+ * 
+ * @example
+ * ```typescript
+ * const result = archiveOldEntries()
+ * console.log(`Archived: ${result.archived}, Kept: ${result.kept}`)
+ * ```
+ */
 function archiveOldEntries(): { archived: number; kept: number } {
   const data = readMemory()
   const lines = data.split("\n")
@@ -181,6 +277,20 @@ const server = new McpServer(
   { capabilities: { tools: { listChanged: true } } }
 )
 
+/**
+ * Register the memory_remember tool.
+ * Saves a fact to persistent memory (decisions, patterns, bugs, knowledge).
+ * 
+ * @example
+ * ```typescript
+ * // From MCP tool call:
+ * await callTool("memory_remember", {
+ *   category: "decision",
+ *   key: "use-ts-for-mcp",
+ *   content: "Using TypeScript for MCP server implementation"
+ * })
+ * ```
+ */
 server.registerTool(
   "memory_remember",
   {
@@ -220,6 +330,17 @@ server.registerTool(
   }
 )
 
+/**
+ * Register the memory_recall tool.
+ * Search persistent memory for relevant entries by text, category, or date range.
+ * 
+ * @example
+ * ```typescript
+ * // From MCP tool call:
+ * await callTool("memory_recall", { query: "risk engine" })
+ * await callTool("memory_recall", { query: "redis", category: "bug" })
+ * ```
+ */
 server.registerTool(
   "memory_recall",
   {
@@ -264,6 +385,15 @@ server.registerTool(
   }
 )
 
+/**
+ * Register the memory_forget tool.
+ * Delete a memory entry by key or ID.
+ * 
+ * @example
+ * ```typescript
+ * await callTool("memory_forget", { key: "old-decision" })
+ * ```
+ */
 server.registerTool(
   "memory_forget",
   {
@@ -301,6 +431,15 @@ server.registerTool(
   }
 )
 
+/**
+ * Register the memory_stats tool.
+ * Display memory statistics including entry counts and categories.
+ * 
+ * @example
+ * ```typescript
+ * await callTool("memory_stats", {})
+ * ```
+ */
 server.registerTool(
   "memory_stats",
   {
@@ -340,6 +479,26 @@ server.registerTool(
   }
 )
 
+/**
+ * Register the memory_summary tool.
+ * Get or set file summaries to save tokens when reading large files.
+ * 
+ * @example
+ * ```typescript
+ * // Set a summary
+ * await callTool("memory_summary", {
+ *   action: "set",
+ *   file: "src/complex.ts",
+ *   summary: "Complex module handling X, Y, Z"
+ * })
+ * 
+ * // Get a summary
+ * await callTool("memory_summary", {
+ *   action: "get",
+ *   file: "src/complex.ts"
+ * })
+ * ```
+ */
 server.registerTool(
   "memory_summary",
   {
@@ -396,6 +555,16 @@ server.registerTool(
   }
 )
 
+/**
+ * Register the memory_archive tool.
+ * Archive old entries (>30 days) to archive.toon to keep memory clean.
+ * 
+ * @example
+ * ```typescript
+ * await callTool("memory_archive", {})
+ * // "📦 Archivadas 5 entradas antiguas"
+ * ```
+ */
 server.registerTool(
   "memory_archive",
   {
@@ -419,6 +588,18 @@ server.registerTool(
   }
 )
 
+/**
+ * Register the memory_encrypt tool.
+ * Enable AES-256-GCM encryption for the memory file.
+ * 
+ * ⚠️ Warning: Save the encryption key! It cannot be recovered.
+ * 
+ * @example
+ * ```typescript
+ * await callTool("memory_encrypt", {})
+ * // "🔐 Encriptación habilitada\n⚠️ Guarda esta clave: ..."
+ * ```
+ */
 server.registerTool(
   "memory_encrypt",
   {
@@ -450,6 +631,16 @@ server.registerTool(
   }
 )
 
+/**
+ * Register the memory_decrypt tool.
+ * Disable encryption and decrypt the memory file.
+ * 
+ * @example
+ * ```typescript
+ * await callTool("memory_decrypt", { key: "your-encryption-key" })
+ * // "🔓 Encriptación deshabilitada"
+ * ```
+ */
 server.registerTool(
   "memory_decrypt",
   {