toon-memoryPowered by TOON

The Continuity Layer for AI Agents

Your agent's knowledge survives every session — offline, private, zero LLM.

Works with
OpenCodeVS Code / CopilotClaudeCursorWindsurf
+17 more
Get StartedView on GitHub
~/.toon-memory

$npm install -g toon-memory

Why do agents lose context between sessions?

AI coding agents start every session with amnesia

Context resets daily

Every new session, your agent forgets the decisions, patterns, and bugs it learned yesterday. You re-explain the same context over and over.

Hunting through history

Without memory, agents grep git history and re-read files to reconstruct why something was built a certain way — burning tokens and time.

Copy-paste notes

Developers paste context between chats by hand. It is fragile, gets stale, and never reaches the next autonomous run.

toon-memory gives your agent a persistent, queryable memory — so context survives every session, automatically.

Get to know toon-memory

The Continuity Layer for your coding workflow

A memory stores facts; a continuity layer preserves how your project works — so every session starts where the last one ended.

Decisions

The "why" behind every choice — frameworks, libraries, trade-offs. Recalled when it counts, never re-debated.

📏

Conventions

Naming, structure, and style rules your team has agreed on. Followed without being re-explained.

Context

Architecture, environment, and operational knowledge that doesn't live in any single file.

🤝

Shared understanding

Project knowledge and team decisions available to every agent and every session.

toon-memory introduces the concept of a continuity layer: a lightweight system that preserves project knowledge, decisions, and context between AI sessions — no cloud services or heavy infrastructure.

Why developers choose toon-memory

Private, lightweight, universal

The guarantees that make project memory safe to keep.

Privacy-first

  • 100% local — no cloud, no server, no telemetry
  • Optional AES-256-GCM encryption
  • You own the memory file, like any source file

Lightweight

  • Native TOON format — 22% fewer tokens than JSON
  • ~1 MB install — three tiny prompt packages, runs on any Node.js 18+
  • Deterministic logic — no LLM calls, no API keys
🛰️

Universal

  • Works with 20+ agents: Claude Code, Codex, Gemini CLI, Cursor, OpenCode and more
  • Standard MCP — switch agents without losing context
  • Project memory shared by every team member

Same project. Two sessions.

What your agent remembers changes the outcome.

Without toon-memory
Session 1
Use Sequelize.
OK.
Held in session context — tokens accumulate.
Session 2
What's our ORM?
No memory between sessions.
I don't know.
With toon-memory
Session 1
Use Sequelize.
$ memory_remember({ category: "decision", key: "orm:sequelize", content: "Use Sequelize as ORM" })
OK.
Saved to memory.
Session 2
What's our ORM?
Recalled from memory.
You're using Sequelize.

Benchmarks

Measured, not assumed

Token and tool-call savings measured across a real session

Auto-loading
~90%

fewer tokens per step

Dumping all memory at every step→Only the task-relevant entries

80% fewer tool calls (25 → 5)

Compact recall
68%

fewer tokens per recall

Reading whole files→One compact recall

58% fewer tokens (system primer)

Batch compress
14%

fewer tokens on disk

Scattered low-quality entries→One consolidated summary

TOON format

The TOON format is built for LLMs, not for humans

Metric
fewer tokens than JSON22.5%
on a single entry30.5%
faster to parse1.3x

JSON 1097→TOON 850

Measured with gpt-tokenizer (cl100k_base) over 16 representative memory entries, comparing the real on-disk TOON format against compact JSON. Reproducible: npm run bench.

Ranking quality

LongMemEval-style retrieval on a frozen 187-entry real snapshot — 42 gold queries

MetricLinearRRFUnified
R@5· gold entry in the top 50.6430.8610.829
nDCG@5· ordering quality0.6540.7640.739
MRR@5· position of the right hit0.7760.7880.760
97.6% of queries answered from the top-5

Real data.toon snapshot (187 entries, 2026-08-01), deterministic today, read-only, no code copies; 2 priority meta-entries excluded. Reproducible: npm run bench:retrieval.

Auto-loading: the OpenCode plugin injects only file-relevant memory instead of dumping all entries. Full session: start → debug → implement → review → wrap-up. Reproducible: npm run bench:full, npm run bench:primer, npm run bench:compress-all.

How does it work?

Five steps from amnesia to memory

1

Install

One command. Zero configuration for 20+ agents.

npm install -g toon-memory
2

Remember

Save decisions, patterns, and bugs as you work — with auto-tag inference and optional TTL.

memory_remember({
  category: "decision",
  key: "use-zod",
  content: "Use Zod for validation",
  file: "src/types.ts"
})
3

Recall

Your agent queries memory on demand — no re-explaining, no token waste.

memory_recall({ query: "validation" })
// [decision] use-zod (a1b2c3d4)
//   Use Zod for validation — src/types.ts
4

Auto-Inject

System primer auto-injects at session start — top memories, categories, patterns. Zero tool calls.

// Session start (automatic)
toon-memory:
  Top memories:
    [pattern] retry-with-backoff: Exponential backoff...
    [decision] use-zod: Use Zod for validation...
  Categories: pattern: 5, bug: 12, knowledge: 25
5

Context

One call gives your agent everything: project, git, memory, sessions. 80% fewer tool calls.

context_generate({})
// # Project Briefing (full)
// ## Project — toon-memory v4.3.0
// ## Git — branch: main, 3 commits
// ## Memory — 26 entries, 18 edges
// ## Sessions — 2 active

A memory toolkit, not a protocol

Everything your agent needs to remember, recall, and reason — grouped by purpose, with resources for direct context reading and an interactive graph viewer.

Core Memory
memory_remembermemory_recallmemory_forgetmemory_statsmemory_diffmemory_suggestmemory_summarymemory_archivememory_checkpointmemory_visualizememory_pinmemory_unpinmemory_tagmemory_reflectmemory_promote
Search & Intelligence
memory_smart_recallmemory_capturedmemory_consolidatememory_graph_pathmemory_search
Context Briefing
context_briefcontext_generatecontext_diffcontext_focuscontext_healthcontext_export
Compression
memory_compressmemory_primer
Session Management
memory_sessionsmemory_merge_sessions
Sync & Security
memory_export_gistmemory_import_gistmemory_encryptmemory_decryptmemory_backupmemory_secretmemory_export_globalmemory_import_global

Multi-Agent

Works with 20+ AI coding agents. OpenCode, VS Code, Claude, Cursor, Windsurf, Cline, Continue, Codex, Gemini, Zed, Antigravity, Aider, KiloCode, OpenClaw — zero configuration.

OpenCodeClaudeCursorWindsurf

TOON Format

22% fewer tokens than JSON (measured). Custom encoding designed for LLM comprehension and token efficiency.

22% less tokens1.3x faster parse

Smart Recall

Graph-aware recall re-ranked by BM25 relevance and graph centrality (hubs surface even without the query word). Per-hop decay keeps distant context low. Token-efficient `compact` mode returns numeric-indexed, snippet-truncated results.

BM25Centralitycompact

Smart Memory

Auto-tag inference from a built-in vocabulary plus your project dependencies, quality scoring with staleness decay, confidence scores, merge-dedup, related entry suggestions, memory diff, and configurable TTL for temporary context.

Auto-tagsQualityStaleness decay

Intelligent Auto-Loading

OpenCode plugin auto-recalls relevant memory by file path on every tool execution — no dump-all, no wasted context. Injects only what matters via setContext(), saving ~90% tokens per interaction.

~90% fewer tokensFile-path recallZero config

Compression

LLM-powered compression for related entries, batch cleanup of low-quality entries deterministically (no LLM), merge similar entries by Jaccard similarity, and auto-injected system primer at session start.

14% fewer tokensMerge similarAuto-primer

Encryption & Security

AES-256-GCM for sensitive data. Auto-archive old entries. Watch mode for automatic backup every N minutes.

AES-256-GCMAuto-backup

Sync & Sessions

Export/import memory via GitHub Gists. Merge observations across parallel sessions. Detect soft conflicts between agents.

Gist syncCross-session

Knowledge Graph

Entries linked via `links` or `[[key]]` refs form a queryable graph. BFS shortest-path finds connection chains between any two entries. Centrality scoring surfaces hub knowledge — no embeddings, no LLM, fully offline.

Graph pathCentralityOffline

Your memory, as a graph

Connect decisions to their specs, bugs, and architecture. Recall returns the right context — not just keyword matches.

  • Link entries with `links` or `[[key]]` refs — no embeddings, no LLM
  • `memory_recall({ mode: "graph" })` expands a relationship-aware subgraph
standard1097 tokens
memory_recall({ query: "riesgo", mode: "graph" })
[decision] risk-engine-priority (a1b2c3d4)
  The engine prioritizes risk over speed.
  File: spec.md:10 | Tags: risk;spec | Date: 2026-07-01
  links: engine-arch
compact: true~520 tokens
memory_recall({ query: "riesgo", mode: "graph", compact: true })
[1] decision/risk-engine-priority
  The engine prioritizes risk over speed.
  tags: risk;spec · edges: ->2, ->3
Inside the viewer:
SearchPath finderPNG / SVG exportDark & light themes

Memory Graph Viewer

Visualize your memory as an interactive force-directed graph. See entries, connections, categories, and access patterns at a glance.

  • CLI viewer: npx toon-memory viewer starts an HTTP server
  • Inline MCP Apps viewer: call memory_visualize() to render the graph directly in MCP Apps–compatible hosts — no server needed
  • Hover nodes for tooltips with content preview and quality score
  • Click to select and center; double-click to open details
  • Search filters entries and highlights matching nodes with a pulsing glow
  • Path finder finds and highlights the shortest connection between two entries
  • Adjustable physics, dark/light theme, PNG/SVG export

A memory toolkit

Everything your agent needs to remember, recall, and reason

Core Memory

memory_remember

Save to Memory

Store decisions, patterns, bugs, knowledge, or warnings (negative "do NOT do this" memories, recalled with a boost) — persisted across sessions with auto quality scoring.

memory_recall

Search Memory

Query the knowledge graph before reading files. Quality-weighted results. Supports path scoping (path_scope) and budget control (tiny/normal/deep). explain: true appends a per-entry reason line; budget_tokens caps output by estimated tokens.

memory_stats

Memory Stats

Show statistics about the project memory, including quality distribution, most accessed entries, and hit-rate/duplicate/dead metrics.

memory_visualize

Open Graph Viewer

Render the interactive memory graph inline in MCP Apps–compatible hosts. Force-directed graph, stats, timeline, detail panel.

Search & Intelligence

memory_smart_recall

Smart Recall

Unified search combining BM25 + graph centrality + quality score + freshness + session bias in one call. Supports explain: true (per-entry reasons) and budget_tokens (output cap).

memory_consolidate

Consolidate

Dedupe identical entries, merge near-duplicates (Jaccard >50%), batch-compress low-quality entries, or retire older library-version entries (mode: "versions") — deterministic, no LLM.

Context Briefing

context_generate

Full Project Briefing

One-call briefing: project structure + git state + memory + sessions. Replaces 6 manual calls. Saves 93% tokens.

context_health

Health Audit

Orphan links, duplicates, broken file refs, expired TTL, stale sessions. Score 0–100.

Compression

memory_compress

LLM Compress

LLM-powered two-step compression: summarize + overwrite. Uses Anthropic/OpenAI CLI if available.

memory_primer

Context Primer

One-call context primer: top memories + categories + session file changes. Auto-injected at session start.

Session Management

memory_sessions

Sessions

Show active agent sessions and detect soft conflicts.

memory_merge_sessions

Merge Sessions

Merge observations across parallel sessions for a file. Deduplicates and auto-promotes.

Sync & Security

memory_encrypt

Enable Encryption

AES-256-GCM encryption with an auto-generated key.

memory_backup

Backup Memory

Create timestamped backup of memory file. Auto-prunes to 10 most recent.

Resources:memory-entriesmemory-statsmemory-summariesmemory-viewer (ui://viewer)
Explore all 38 tools →

Works with 20+ AI coding agents

Zero configuration — toon-memory auto-detects and configures each one

OpenCodeOpenCode
VS Code / CopilotVS Code / Copilot
ClaudeClaude
CursorCursor
WindsurfWindsurf
ClineCline
ContinueContinue
CodexCodex
GeminiGemini
ZedZed
AntigravityAntigravity
AiderAider
KiloCodeKiloCode
OpenClawOpenClaw
KiroKiro
QwenQwen
KimiKimi
GooseGoose
JunieJunie
AmpAmp
GrokGrok
TraeTrae

Frequently Asked Questions

Everything you need to know about giving your agent a memory

What is toon-memory?

A memory layer that gives your AI coding agent continuity — it stores decisions, patterns, bugs, and context in a compact TOON format so your agent remembers everything across sessions, with 80% fewer tool calls per session.

Which agents are supported?

OpenCode, VS Code, Claude Code, Cursor, Windsurf, Cline, Continue, Codex, Gemini, Zed, Antigravity, Aider, KiloCode, OpenClaw, and Kiro — 20+ agents with zero configuration via the MCP server.

How is my data stored?

Entries are written to a local TOON file (a token-efficient format ~22% smaller than JSON, measured). You own the file and can commit it, diff it, or back it up like any other source file.

Is my memory encrypted?

Yes. Enable encryption with the memory_encrypt tool to secure sensitive entries with AES-256-GCM. The key is generated automatically and kept local.

Does it work offline?

Completely. toon-memory runs locally with no external services or accounts required. Watch mode even creates automatic backups on a schedule.

Can multiple agents share the same memory?

Yes. Because memory lives in a plain file in your project, every agent configured for that project reads and writes the same context.

How do I back up my memory?

Use watch mode for scheduled automatic backups, or simply commit the TOON file to git. Old entries are auto-archived after 30 days to keep things clean.

Is it free and open source?

Yes. toon-memory is MIT licensed and free to use. The source is available on GitHub and the package is published on npm.

How is this different from my agent's built-in memory?

Built-in memory is often ephemeral or vendor-specific. toon-memory gives you a portable, diffable, encrypted memory file you fully control across agents and projects.

Can I expire temporary context?

Yes. Set a TTL (e.g. ttl: "7d") on any entry and it auto-expires — perfect for sprints, deadlines, and time-sensitive notes.

What is smart recall?

memory_smart_recall combines BM25 keyword search, graph centrality, quality scoring, and freshness decay in a single call — the best of all ranking strategies without manual orchestration.

How does quality scoring work?

Every entry gets an automatic quality score (0-1) based on tag coverage, link richness, content detail, recency, and specificity. High-quality entries surface first in recall results.

What happens if I save the same key twice?

The system merges attributes instead of replacing: tags and links are unioned, quality and confidence take the max, and the date is updated. Your entry gets richer over time.

What is memory compression?

memory_compress lets an LLM summarize related entries into one concise summary. memory_consolidate(mode: "low-quality") removes low-quality entries (no tags, short content) deterministically — no LLM needed. Both reduce token count.

Can I sync memory across machines?

Yes. Use memory_export_gist to push entries to a GitHub Gist, then memory_import_gist on another machine. Entries merge automatically (union of tags, max confidence).

Ready to give your agent continuity?

Install in seconds and never re-explain your project again.

Get StartedView on GitHub