Toon Memory

English | Español | 中文 | 日本語 | 한국어 | Português (BR) | Deutsch | Français

toon-memory

The Continuity Layer for AI Agents — AI agents shouldn't have to relearn your project every session.

Table of Contents

• Overview
• Blog Post
• Features
• Installation
• Supported Agents
• MCP Tools
• Coordinación multi-sesión
• Memory Graph (recall basado en grafo)
• Tips & Best Practices
• CLI Commands
• Configuration
• How It Works
• Why TOON?
• Troubleshooting
• FAQ
• Development
• Contributing
• Security & Privacy
• License

Overview

Ever had that feeling where your AI agent forgets everything from yesterday's session? You explain the same architecture decision for the third time, and it still suggests the approach you already rejected?

toon-memory fixes this. It's the Continuity Layer for AI Agents — a lightweight system that preserves your project's knowledge, decisions, and conventions across sessions, so every session starts where the last one ended. Fully local and private, over MCP — no cloud, no server.

📖 [Read the documentation](https://luiggival08.github.io/toon-memory/)

Real-world use cases

Blog Post

Read How toon-memory Makes Your AI Agent Smarter to see a real-world demo of persistent memory in action.

Features

• A complete memory toolkit — Full memory management via Model Context Protocol, including memory_smart_recall (unified recall with session bias), memory_sessions for multi-session coordination, context_* tools for one-call context generation (briefing, diff, focus, health audit, export), memory_compress (LLM-powered compression), memory_consolidate (deterministic dedup/merge/cleanup), memory_primer (auto-injected context), memory_merge_sessions (cross-session merge), memory_pin/memory_unpin (pin important entries with priority 1-5), memory_checkpoint (session snapshot with 7d TTL), memory_search (unified search with tag filters + session bias), memory_tag (batch tag operations), memory_export_gist/memory_import_gist (GitHub Gist sync), memory_secret (encrypted secrets vault), memory_export_global/memory_import_global (cross-project conventions), memory_forget (soft/hard delete, restore, supersede), memory_reflect (staleness/quality reflection), and memory_promote (auto-promote low-confidence drafts)
• MCP Resources — Read memory as context without tool invocations, including a System Primer (auto-generated knowledge map)
• 22 agents supported — OpenCode, VS Code, Claude Code, Cursor, Windsurf, Cline, Continue, Codex CLI, Gemini CLI, Zed, Antigravity, Aider, KiloCode, OpenClaw, Kiro, Qwen, Kimi, Goose, Junie, Amp, Grok, Trae
• Interactive installer — Select which agents to configure from a menu
• SessionStart hooks — Auto-reminders for Claude Code, Codex CLI, Gemini CLI, Antigravity
• TOON format — 22% fewer tokens than JSON (measured), better LLM comprehension
• Per-project memory — Each project gets its own memory file
• Zero config — Just install and use
• Auto gitignore — Automatically adds .toon-memory/memory/ to .gitignore
• Date filtering — Search memory by date range
• Auto-archive — Old entries (>30 days), expired TTL entries, or 100+ entries moved to archive automatically
• Encryption — AES-256-GCM encryption for sensitive data
• Watch mode — Auto-backup every N minutes
• Memory TTL — Configurable per-entry expiration (7d, 30d, or exact dates)
• Tag inference — Auto-detect tags from content when tags are empty (built-in vocabulary + project dependencies)
• Memory diff — See what changed since your last session
• Related entries — Auto-suggest related memories when saving
• Memory graph — Connect entries with links/[[key]] refs; memory_recall can expand a relationship-aware subgraph for more precise, lower-token recall (no embeddings, no LLM)
• Token-efficient recall — memory_recall({ compact: true }) returns numeric-indexed entries, drops id/date/file, renders graph edges as ->2, and truncates graph neighbors to snippets
• BM25 + centrality ranking — Recall re-ranks by BM25 relevance and graph centrality (hubs surface even without the query word); per-hop decay keeps distant nodes low
• Auto-tag from dependencies — toon-memory init scans package.json/Cargo.toml/requirements.txt/go.mod and writes a project vocabulary so entries mentioning a dependency get auto-tagged with it
• Smart Recall — memory_smart_recall combines BM25 + graph + decay + quality in one call; the LLM calls this at the start of every task
• Quality scoring — Every entry gets a 0–1 quality score based on structure (tags, links, content specificity, recency, access count); high-quality entries surface first
• Merge-dedup — Saving with the same key merges attributes (union of tags, max confidence, latest date, combined links) instead of overwriting
• Near-duplicate detection — Consolidation detects near-duplicates via Jaccard similarity (threshold 0.7) and merges them
• Confidence score — Each entry tracks reliability: user-asserted = 1.0, inferred = 0.65–0.75
• LLM-powered compression — memory_compress uses AI to summarize long entries; memory_consolidate(mode: "low-quality") does batch cleanup deterministically
• Cross-session merge — memory_merge_sessions merges observations across parallel sessions for a file
• GitHub Gist sync — memory_export_gist and memory_import_gist sync memory entries via GitHub Gist (zero dependencies)
• Verbatim mode — config.verbatim preserves original entries instead of overwriting on save
• Context generation tools — context_generate (full briefing), context_diff (incremental), context_focus (targeted), context_health (audit), context_export (markdown) — each replaces 5-6 manual tool calls. Zero LLM, pure deterministic aggregation
• System Primer — Auto-injected at session start via systemPrimer(), showing top 5 memories for instant context
• Path Scoping — Entries can be scoped to file paths via glob patterns (path_scope); recall filters by scope automatically
• Budget Control — Three output levels: budget: "tiny" (key+1 line, ~50 tokens), "normal" (compact with tags/edges), "deep" (all fields with origin/scope/status). Backward compatible with compact: true
• Origin Tracking — Each entry tracks its origin (human, agent, inferred); human assertions get a quality boost
• Soft Delete — memory_forget soft-deletes by default (sets status=obsolete). Restore with memory_forget(key, action: "restore"), hide with action: "soft", permanent removal via action: "hard"
• Enhanced Health Audit — context_health now detects missing-evidence (path_scope without file) and stale-claims (overlapping content in same category)
• Typed graph edges — Edges carry types (superseded_by, supersedes, relates), written as type:key in the graph. Explicit links become relates:key, so you can tell *how* entries are related, not just that they are
• RRF ranking — Recall fuses BM25 (×3) and graph-centrality ranks with Reciprocal Rank Fusion and an adaptive k = clamp(3..60, round(sqrt(n))). Benchmark (8 gold queries): nDCG 0.776, MRR 0.917 — exact parity with the previous linear scoring. Pass rrf: false to fall back
• Memory reflect — memory_reflect ranks entries by staleness, quality, and over-connection to surface what needs attention or cleanup. Deterministic, zero LLM
• Memory supersede — memory_forget(key, action: "supersede", new_key) marks an entry as replaced by a newer one (superseded_by link + supersededOn date). memory_recall({ as_of }) re-includes old entries for point-in-time queries before their supersession
• Auto-promote — memory_promote promotes low-confidence drafts to active entries deterministically (threshold 0.65, Jaccard dedup), with dryRun by default
• Explain WHY — memory_recall/memory_smart_recall accept explain: true and append a deterministic reason line to every returned entry (↳ 100% relevance · used 14× · used today · importance HIGH) — *why* it was retrieved, no LLM
• Token budgets — budget_tokens caps the recall output by estimated token count; entries accumulate greedily and the tail that would exceed the budget is dropped (0 = no limit)
• Version supersession — memory_consolidate(mode: "versions") detects entries describing the same subject at different library versions (e.g. "Use React 18" vs "Use React 19") and retires the older ones in favor of the newest
• Negative memories — a warning category for "do NOT do this" facts; warning entries get a recall boost so the agent sees the landmines before repeating them
• Language + folder ranking — recall boosts entries written in the same script family (latin/CJK/cyrillic/…) and entries whose path_scope matches the current file
• Explicit importance — memory_remember({ importance }) sets critical, high, medium, or low. Critical decisions surface first (+0.3), low notes stay out of the way (−0.1); empty = auto (recency + frequency). Re-saving keeps the higher level
• Evidence layer — every memory_remember save is annotated with an evidence level: verified when its referenced file exists on disk, unverified when it doesn't, conflict when it overlaps a warning or critical/high decision. Conflicts get a +0.15 recall boost (verified +0.03, unverified −0.02) and a ⚠️ CONTRADICTION warning on save — but never block the write
• Secrets vault — memory_secret stores credentials in an encrypted sidecar (secrets.toon, AES-256-GCM) so data.toon stays a readable open format while sensitive values never hit plaintext
• Global memory import/export — memory_export_global writes project memory to ~/.toon-memory/memory/global.toon; memory_import_global pulls cross-project conventions back with a one-shot, deterministic, offline merge (never a live dual source)
• ~1 MB install — three tiny prompt packages (@inquirer/checkbox/select/confirm); the MCP SDK, zod, and the TOON parser are bundled into the shipped binary — a single npm i -g downloads ~1 MB (was ~14 MB) and lands ~4.4 MB on disk (was ~33 MB)

Installation

1. Install

# macOS / Linux

curl