Toon Memory

# macOS / Linux curl -fsSL https://raw.githubusercontent.com/LuiggiVal08/toon-memory/main/install.sh | sh # Windows (PowerShell) irm https://raw.githubusercontent.com/LuiggiVal08/toon-memory/main/install.ps1 | iex # Or with npm (any platform) npm i -g toon-memory

Tip:The npm install is the most reliable method. The curl/irm scripts are convenience wrappers.

Size:A barenpm i -g toon-memorydownloads ~1 MB and installs ~4.4 MB — three tiny prompt packages; everything else (MCP SDK, zod, TOON parser) ships bundled.

# Interactive installer — detects agents and configures MCP npx toon-memory

- Detect which AI agents you have installed
- Ask which ones to configure
- Add the MCP server config automatically

That's it! In your next agent session, try:

memory_stats # See what's in memory memory_recall # Search memory before reading files memory_remember # Save important decisions

Tip:Always runmemory_recallat the start of a session. Your agent will have context from previous sessions instantly.

{ "mcpServers": { "toon-memory": { "command": "npx", "args": ["-y", "toon-memory", "mcp"] } } }

{ "mcpServers": { "toon-memory": { "command": "npx", "args": ["-y", "toon-memory", "mcp"] } } }

Add to~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "toon-memory": { "command": "npx", "args": ["-y", "toon-memory", "mcp"] } } }

Tip:You can configure toon-memory for multiple agents at the same time. Each agent gets the same shared memory file at.toon-memory/memory/.

Memory is also exposed as MCP resources for direct context reading:

memory_remember({ category: "decision", key: "use-zod", content: "Use Zod for validation — simpler than Joi, better TS support", file: "src/types.ts", tags: "validation;types" }) // 🧠 Guardado: decision/use-zod (a1b2c3d4) // Quality score: 0.65 (2 tags, detailed content) // 🔗 Entradas relacionadas: // [pattern] zod-schemas — Shared Zod schemas for API validation

Tip:Use descriptive keys likeuse-zodinstead of vague ones likevalidation. Your agent searches by key and content, so specificity helps. Saving with the same key auto-merges (union of tags, max confidence).

memory_remember({ category: "knowledge", key: "sprint-deadline", content: "Sprint ends July 18, feature freeze is July 16", ttl: "7d" }) // 🧠 Guardado: knowledge/sprint-deadline (x1y2z3w4) // ⏰ TTL: 2026-07-19 // Quality score is calculated automatically.

Tip:Use TTL for temporary context like deadlines, sprint info, or time-sensitive notes. Entries with expired TTL are automatically filtered from search results.

memory_remember({ category: "decision", key: "db-choice", content: "We chose Postgres over MySQL — JSONB for flexible schemas, better extension ecosystem", importance: "critical" }) // 🧠 Guardado: decision/db-choice (a1b2c3d4) // 🎯 Importance: critical (+0.3 boost) — surfaces above routine entries

Tip:Mark foundational decisionscriticalso they always rank near the top of recall.importanceacceptscritical,high,medium, orlow; leave it empty to let the system rank by recency and frequency automatically.

memory_remember({ category: "bug", key: "redis-connection-timeout", content: "Redis connection timeout in production, increased pool size" // tags left empty — auto-inferred from content }) // 🧠 Guardado: bug/redis-connection-timeout (a1b2c3d4) // 🏷️ Tags inferidos: redis // Quality score is calculated automatically based on inferred tags and content.

Tip:Leavetagsempty and the system will infer them from your content using a built-in vocabulary of 20+ categories (redis, auth, api, db, security, etc.)plusa project vocabulary derived from your dependencies atinittime. So if your project depends onredis, any entry mentioning "redis" gets auto-taggedredis.

memory_recall({ query: "redis" }) // [bug] redis-pool-fix (i9j0k1l2) // Added max_connections=20 // File: redis.ts | Tags: redis;fix | Date: 2026-07-10

Tip:Search before you read files. This saves tokens and gives your agent context it wouldn't get from code alone. Quality-weighted ranking ensures the most useful entries surface first. Or usememory_smart_recallfor a more comprehensive result.

memory_recall({ query: "redis", from_date: "2026-07-01", to_date: "2026-07-31" })

memory_archive() // 📦 Archivadas 5 entradas antiguas // 📋 Quedan 42 entradas activas

Tip:Run this periodically to keep memory lean. Archived entries are still searchable viamemory_recallwith date filters. Entries with expired TTL are also archived automatically. Low-quality entries get lower recall priority. Low-quality entries get lower recall priority.

memory_diff({ since: "24h" }) // 📋 Cambios desde 2026-07-11: // // ➕ Nuevas (2): // [decision] use-zod (a1b2c3d4) // Use Zod for validation // [bug] redis-timeout (e5f6g7h8) // Redis connection timeout fix

Tip:Usememory_diffat the start of a session to see what your agent learned since you last worked on the project. New entries include quality scores. New entries include quality scores.

memory_suggest({ context: "redis cache configuration" }) // 🔍 Sugerencias para "redis cache configuration": // // [decision] redis-cache-config (a1b2c3d4) // Redis cache layer for session storage // File: src/cache.ts | Tags: redis;cache | Date: 2026-07-10 // // [bug] redis-pool-fix (i9j0k1l2) // Added max_connections=20 // File: redis.ts | Tags: redis;fix | Date: 2026-07-10

Tip:Usememory_suggestwhen you need context about a topic but aren't sure what to search for. Or usememory_smart_recallfor a more comprehensive result.

memory_smart_recall({ intent: "diseño de base de datos para backend" }) // [1] decision/use-postgres // Choose Postgres for ACID compliance and JSON support // tags: db;decision · edges: ->2 // // [2] pattern/db-migrations // Use sequential migration files, never edit committed ones // tags: db;pattern · edges: ->1 // // [3] bug/redis-timeout // Redis connection timeout — increased pool to 20 // tags: redis;bug

Tip:Usememory_smart_recallat the START of every task. It combines BM25 + graph + decay + quality in one call — no need to guess what to search for.

memory_recall({ query: "redis", explain: true }) // [decision] redis-cache-config (a1b2c3d4) // Redis cache layer for session storage // File: src/cache.ts | Tags: redis;cache | Date: 2026-07-10 // ↳ 92% relevance · used 14× · used today · importance HIGH

memory_recall({ query: "redis", budget_tokens: 300 }) // Entries accumulate greedily; the tail that would exceed the estimate is dropped. // budget_tokens: 0 (default) = no limit.

Tip:Combinebudget_tokenswithbudget: "deep"for a context window that stays inside a hard token ceiling regardless of memory size.

context_generate({}) // # Project Briefing (full) // // ## Project // - Name: my-app // - Root: /path/to/project // - Package Manager: npm // - TypeScript: ✓ (v5.3) // // ## Git Status // - Branch: main // - 3 uncommitted, 0 untracked // // ## Memory (42 entries, 12 patterns, 8 bugs) // [1] decision/use-postgres // Choose Postgres for ACID compliance // tags: db;decision // // ## Sessions // - egraterol (main, 2m ago): 42 files touched

Tip:Usecontext_generateat the start of a session to get full context in one call. Replaces 5-6 separate tool calls.

context_health({}) // # Memory Health (score: 87/100) // // ## Summary // - 42 entries (12 patterns, 8 bugs, 15 decisions, 7 knowledge) // - 65.3% average quality // // ## Issues (3) // - Orphan link: pattern/db-migrations → pattern/db-seed (key not found) // - Duplicate: [bug] redis-pool-fix has identical content // - Expired TTL: [knowledge] sprint-deadline (expired 2026-07-20) // // ## Stale Files (1) // - src/legacy.ts (deleted, 2 refs)

Tip:Runcontext_healthwhen memory feels cluttered. Shows orphan links, duplicates, expired TTL entries, broken file references, missing-evidence entries (path_scope without file), and stale claims (overlapping content).

When you save with the samekey, attributes are merged instead of overwritten:

// First save memory_remember({ category: "decision", key: "use-zod", content: "Use Zod for validation", tags: "types" }) // 🧠 Guardado: decision/use-zod (a1b2c3d4) // Later save with same key — merges automatically memory_remember({ category: "decision", key: "use-zod", content: "Use Zod for validation — also handles API response parsing", tags: "types;api" }) // 🧠 Actualizado: decision/use-zod (a1b2c3d4) // 🔗 Merge: tags combinados, fecha y links actualizados // Tags now: "types;api" (union of both)

Tip:Use descriptive, stable keys. The same key = merge, different key = new entry.

Every entry gets an automatic quality score (0–1) based on structure:

High-quality entries surface first in recall. Check quality withmemory_stats:

memory_stats() // ... // Calidad promedio: 0.58 (12 con score)

Each entry tracks how reliable the information is:

Confidence is preserved on merge (max of both entries).

The System Primer is an auto-generated knowledge map exposed as an MCP resource. Agents load it at session start for instant context:

// Exposed as toon://memory/summaries // Auto-regenerates on every read // Contains: top entries, categories, patterns

Tip:Addtoon://memory/summariesto your agent's system prompt for instant context at session start.

// First, set TOON_MEMORY_KEY in your environment (or .env file): // export TOON_MEMORY_KEY="your-secret-key-here" memory_encrypt() // 🔐 Encriptación habilitada

Warning:The encryption key must be set viaTOON_MEMORY_KEYenv var before encrypting. Save it somewhere safe — if you lose it, your memory data is gone forever. Quality scores and confidence are preserved through encryption.

When you runseveral AI agent sessions in parallel(e.g. three OpenCode sessions on the same repo at once), they can accidentally clobber each other's work. toon-memory ships withmemory_sessions, a file-based coordination tool that lets every session see what its siblings are doing — withno server, no network, and no LLM calls.

memory_sessions({ conflictsOnly: false }) // 🧭 Sesiones activas (2) — ventana 30 min: // // • opencode @ feature/auth (tú) // id: a1b2c3d4 // hace 2 min // Archivos: // • src/auth.ts // // • claude @ feature/db // id: e5f6g7h8 // hace 9 min // • src/db.ts // // 🔥 Conflictos suaves (1): // ⚠️ src/types.ts ↔ opencode @ feature/auth, claude @ feature/db

- PassconflictsOnly: trueto skip the session list and show only soft conflicts:

memory_sessions({ conflictsOnly: true }) // 🔥 Conflictos suaves (1): // // ⚠️ src/types.ts // ↔ opencode @ feature/auth (a1b2c3d4), claude @ feature/db (e5f6g7h8)

- At the start of every session, theSessionStarthook already prints the other active sessions and any soft conflicts.
- Runmemory_smart_recall({ intent: "what I'm working on" })to get full context (memory + graph + quality).
- Runmemory_sessions()to see the full picture (branches, files, last-seen) andmemory_sessions({ conflictsOnly: true })if you only care about clashes.
- If you share a file with another session, sync up before editing so you don't overwrite each other's changes.