toon-memory

[English](README.md) | [Español](README.es.md) | [中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português (BR)](README.pt-br.md) | [Deutsch](README.de.md) | [Français](README.fr.md)

# toon-memory

> MCP memory server 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/)
[![MCP Badge](https://lobehub.com/badge/mcp/luiggival08-toon-memory)](https://lobehub.com/mcp/luiggival08-toon-memory)

---

## Table of Contents

- [Overview](#overview)
- [Blog Post](#blog-post)
- [Features](#features)
- [Installation](#installation)
- [Supported Agents](#supported-agents)
- [MCP Tools](#mcp-tools)
- [Coordinación multi-sesión](#coordinación-multi-sesión)
- [Memory Graph (recall basado en grafo)](#memory-graph-recall-basado-en-grafo)
- [Tips & Best Practices](#tips--best-practices)
- [CLI Commands](#cli-commands)
- [Configuration](#configuration)
- [How It Works](#how-it-works)
- [Why TOON?](#why-toon)
- [Troubleshooting](#troubleshooting)
- [FAQ](#faq)
- [Development](#development)
- [Contributing](#contributing)
- [Security & Privacy](#security--privacy)
- [License](#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 gives your AI agent a persistent memory that survives restarts, so it actually learns from your project over time.

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

### Real-world use cases

| Scenario | What toon-memory does |
|----------|----------------------|
| Design debates | "We chose Redis over Memcached because of pub/sub support" |
| Framework choices | "This project uses Zod for validation, not Joi" |
| Bug fixes | "Redis pool exhaustion — fix was max_connections=20" |
| Architecture notes | "Broker service uses RESP protocol, not HTTP" |
| Onboarding | "The deploy script lives in scripts/deploy.sh" |
| Team context | "PR #142 reverted the caching change — don't re-add it" |

---

## 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

- **37 MCP tools** — 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_compress_all` (batch compression), `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_resolve` (restore soft-deleted entries), and `memory_suppress` (mark entries as obsolete)
- **MCP Resources** — Read memory as context without tool invocations, including a System Primer (auto-generated knowledge map)
- **15 agents supported** — OpenCode, VS Code, Claude Code, Cursor, Windsurf, Cline, Continue, Codex CLI, Gemini CLI, Zed, Antigravity, Aider, KiloCode, OpenClaw, Kiro
- **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_compress_all` does batch compression 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`). Use `memory_resolve` to restore, `memory_suppress` to hide. Permanent deletion via `hard: true`
- **Enhanced Health Audit** — `context_health` now detects missing-evidence (path_scope without file) and stale-claims (overlapping content in same category)

---

## Installation

### 1. Install

```bash
# 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.

### 2. Configure your agent(s)

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

The installer will:
1. Detect which AI agents you have installed
2. Ask which ones to configure
3. Add the MCP server config automatically

### 3. Use it

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

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

> **Tip:** Always run `memory_recall` at the start of a session. Your agent will have context from previous sessions instantly.

### MCP Client Quick Setup

#### Cursor

Add to `.cursor/mcp.json`:

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

#### Claude Desktop

Add to `claude_desktop_config.json`:

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

#### Windsurf

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

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

---

## Supported Agents

| Agent | Config Location | Format | Hooks | Auto-Setup |
|-------|-----------------|--------|-------|------------|
| **OpenCode** | `.opencode/opencode.json` + `.opencode/plugins/toon-memory.ts` | Plugin | SessionStart (plugin, no top-level `hooks`) | ✅ |
| **VS Code / Copilot** | `.vscode/m