Toon Memory

MCP文档知识

提供方 未标注

文档知识 stdio · 本地进程 未标注 社区 / 第三方 Claude DesktopClaudeCursorVS Code
查看接入方式

toon-memory 是一款100%本地的持久化记忆MCP服务器,专为AI代码助手(Cursor、Claude Code、Windsurf等)设计。它采用超高效的TOON格式,可将令牌消耗降低多达30%,使代理能够以私密且加密(AES-256)的方式在会话之间保存、搜索和整合项目上下文与决策。

一句话选型结论

按资料字段整理

Toon Memory 属于文档知识类 MCP 服务器,stdio · 本地进程,鉴权方式未标注,可直接接入 Claude Desktop、Claude、Cursor 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式stdio · 本地进程 鉴权未标注 部署方式本地部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

记忆

安装与配置

stdio · 本地进程 未标注
客户端在本机拉起子进程,数据不出本机
# Interactive installer — detects agents and configures MCP npx toon-memory

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Toon Memory当前 未标注 stdio · 本地进程 本地部署 有 未标注
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方未标注上游标注的维护方 未标注
分类文档知识本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式未标注远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验未标注上游最后核验时间

详细介绍

65.7 KB
来自项目仓库与上游目录的原文,未做删改

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

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

> **Size:** A bare `npm i -g toon-memory` downloads ~1 MB and installs ~4.4 MB — three tiny prompt packages; everything else (MCP SDK, zod, TOON parser) ships bundled.

### 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/mcp.json JSON — ✅
Claude Code .mcp.json (MCP) + .claude/settings.json (hooks) JSON SessionStart + PostToolUse + Stop ✅
Cursor .cursor/mcp.json JSON — ✅
Windsurf ~/.codeium/windsurf/mcp_config.json JSON — ✅
Cline .cline/mcp.json JSON — ✅
Continue .continue/config.json JSON — ✅
Codex CLI .codex/config.toml TOML SessionStart + PostToolUse + Stop ([[hooks]] event=) ✅
Gemini CLI .gemini/settings.json JSON SessionStart + PostToolUse + Stop (hooks.*) ✅
Zed ~/.config/zed/settings.json JSONC — ✅
Antigravity .agents/mcp_config.json + .agents/hooks.json hooks.json PreInvocation + PostToolUse + Stop (no SessionStart event) ✅
Aider — — — 📝 Instructions
KiloCode ~/.kilocode/mcp_settings.json JSON — ✅
OpenClaw .openclaw.json JSON — ✅
Kiro .kiro/settings/mcp.json JSON — ✅

> 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/.


MCP Tools

Tool · Description
memory_remember · Save a decision, pattern, bug, knowledge, or warning (negative "do NOT do this" memory, recalled with a boost) — optional TTL, auto-tag inference, links to build the memory graph, merge-dedup on same key, auto quality score and confidence. Write-path intelligence: each save is annotated with an evidence level — verified when the referenced file exists on disk, unverified when it doesn't, conflict when it overlaps a warning or critical/high decision (recalled with a boost and surfaced with a ⚠️ CONTRADICTION warning, but never blocks the write)
memory_recall · Search memory (use BEFORE reading files, filters expired TTL). mode: "graph" expands a relationship-aware subgraph for higher precision. budget: "tiny" · "normal" · "deep" controls output verbosity (backward compat with compact: true). path_scope filters by glob pattern. sessionBias boosts entries from the current git branch. explain: true appends a per-entry reason line (why it was retrieved). budget_tokens caps output by estimated tokens (0 = no limit). Quality-weighted ranking
memory_smart_recall · Unified recall: BM25 + graph + decay + quality in one call. sessionBias boosts entries from the current git branch. explain: true appends per-entry reasons, budget_tokens caps output by estimated tokens. Use at the START of every task. Returns compact, token-efficient output
memory_forget · Lifecycle ops by key or id: action: "soft" (default) marks obsolete, "hard" permanently removes, "restore" brings back to active, "supersede" retires it with a superseded_by link to new_key
memory_stats · View memory state (including TTL stats, quality distribution, origin/status breakdown, cold memories below quality/access thresholds, and hit rate / duplicate / obsolete metrics)
memory_summary · Save/retrieve file summaries
memory_archive · Archive old entries (>30 days) and expired TTL entries
memory_diff · Show changes since a date (24h, 7d, or exact date)
memory_suggest · Find related entries for a given context
memory_encrypt · Enable AES-256-GCM encryption
memory_decrypt · Disable encryption
memory_backup · Create timestamped backup of memory file (auto-prunes to 10 most recent)
memory_captured · List activity auto-captured by hooks (opt-in) or clear the log
memory_checkpoint · Session checkpoint: creates a snapshot of current memory state with 7d TTL. Useful for rollback reference during long sessions
memory_consolidate · Cleanup ops, deterministic (no LLM): mode: "identical" (default) dedupes identical-content entries, "similar" merges near-duplicates (Jaccard >50%), "low-quality" batch-removes low-quality entries (minQuality, dryRun), "versions" retires older library-version entries in favor of the newest
memory_sessions · Show active agent sessions (branch, files, last-seen) and soft conflicts for parallel work
memory_compress · LLM-powered two-step compression: summarize + overwrite. Uses anthropic/openai CLI if available, otherwise returns prompt for manual compression
memory_primer · One-call context primer: top memories + categories + session file changes. Auto-injected at session start
memory_merge_sessions · Merge observations across parallel sessions for a file. Deduplicates and optionally auto-promotes to memory
memory_export_gist · Export memory entries to a GitHub Gist (public or private). Uses GITHUB_TOKEN or gh CLI
memory_import_gist · Import entries from a GitHub Gist. Merges with existing entries (union of tags, max confidence)
memory_secret · Encrypted secrets vault (secrets.toon, AES-256-GCM): store/get/list/forget. Keeps data.toon readable while sensitive values stay encrypted at rest. Requires TOON_MEMORY_KEY
memory_export_global · Write current project memory to the global file (~/.toon-memory/memory/global.toon). One-shot share of cross-project conventions
memory_import_global · Merge cross-project conventions from the global file into this project (one-shot, deterministic, offline). merge: false replaces instead
memory_graph_path · BFS shortest path between two entries in the knowledge graph. Shows how concepts are connected
context_brief · One-call context briefing: memory + sessions + health in compact markdown. Use instead of 5-6 separate memory_ calls. Zero LLM, pure deterministic aggregation
context_generate ·
Full project briefing: combines project structure, git state, memory entries, and active sessions in one call. Replaces 5-6 manual tool calls
context_diff ·
Incremental briefing: git commits + modified files + new/updated memory + active sessions since last session
context_focus ·
Hyper-focused briefing: only relevant memory + related source files + callers + test files for a query
context_health ·
Memory health audit: orphan links, duplicates, broken file refs, expired TTL, stale sessions, score 0–100
context_export ·
Export memory as markdown: injectable context for system prompts (full or compact)
memory_pin ·
Pin an entry with priority 1-5: pinned entries always appear first in recall results sorted by priority, even without a keyword match
memory_unpin ·
Unpin an entry: remove the priority flag
memory_search ·
Unified search with filters: same as memory_recall plus category, tags, from_date, to_date filters. Tag filter uses AND logic — all specified tags must match. budget controls output verbosity. path_scope filters by glob pattern. sessionBias boosts entries from the current git branch
memory_tag ·
Batch tag operations*: add, remove, or set tags on one or more entries by key or id

MCP Resources

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

Resource URI Description
Memory Entries toon://memory/entries Full memory dump
Current Memory toon://memory/current Current memory state with recent entries
Memory Stats toon://memory/stats Category counts and TTL info
System Primer toon://memory/summaries Auto-generated knowledge map (top entries, categories, patterns)

MCP Prompts

Prompt Description
summarize_project_context Analyze current TOON memory and generate a compact project summary. Optional intent parameter to focus on a specific area

Examples

Remember a decision```typescript

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 like `use-zod` instead of vague ones like `validation`. Your agent searches by key and content, so specificity helps. Saving with the same key auto-merges (union of tags, max confidence).

#### Remember with TTL```typescript
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.

Set explicit importance```typescript

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 decisions `critical` so they always rank near the top of recall. `importance` accepts `critical`, `high`, `medium`, or `low`; leave it empty to let the system rank by recency and frequency automatically.

#### Auto-inferred tags```typescript
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: Leave tags empty and the system will infer them from your content using a built-in vocabulary of 20+ categories (redis, auth, api, db, security, etc.) plus a project vocabulary derived from your dependencies at init time. So if your project depends on redis, any entry mentioning "redis" gets auto-tagged redis.

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


> **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 use `memory_smart_recall` for a more comprehensive result.

#### Search with date filter```typescript
memory_recall({
  query: "redis",
  from_date: "2026-07-01",
  to_date: "2026-07-31"
})

> Tip: Use date filters when you remember roughly when something happened but not exactly what. Quality-weighted ranking still applies.

Archive old entries```typescript

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


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

#### Show changes since last session```typescript
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: Use memory_diff at 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.

Find related entries```typescript

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:** Use `memory_suggest` when you need context about a topic but aren't sure what to search for. Or use `memory_smart_recall` for a more comprehensive result.

#### Smart Recall (unified)```typescript
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: Use memory_smart_recall at the START of every task. It combines BM25 + graph + decay + quality in one call — no need to guess what to search for.

Explain WHY a result was returned```typescript

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


The `↳` reason line is deterministic (relevance %, access count, last-used, importance) — no LLM involved. Use `explain: true` when you want to know *why* the agent was shown those entries.

#### Cap output with `budget_tokens````typescript
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: Combine budget_tokens with budget: "deep" for a context window that stays inside a hard token ceiling regardless of memory size.

Full project briefing (one call)```typescript

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:** Use `context_generate` at the start of a session to get full context in one call. Replaces 5-6 separate tool calls.

#### Memory health audit```typescript
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: Run context_health when 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).

Merge-dedup (automatic)

When you save with the same key, attributes are merged instead of overwritten:```typescript
// 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.

#### Quality scoring

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

| Factor | Weight | What it measures |
|--------|--------|------------------|
| Tags | 0.3 max | More specific tags = higher quality |
| Links | 0.2 max | Connected entries = higher quality |
| Content length | 0.3 max | Detailed > vague |
| Recency | 0.1 max | Recent entries score higher |
| Specificity | 0.1 max | Unique words vs repeated words |
| Origin | +0.1/−0.05 | Human assertions boosted, inferred slightly penalized |

High-quality entries surface first in recall. Check quality with `memory_stats`:```typescript
memory_stats()
// ...
// Calidad promedio: 0.58 (12 con score)

Confidence score

Each entry tracks how reliable the information is:

Source Confidence Meaning
User assertion 1.0 "We use Postgres" — direct statement
Inferred 0.65–0.75 Agent inferred from context
Uncertain 0.50 Agent is guessing

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

System Primer

The System Primer is an auto-generated knowledge map exposed as an MCP resource. Agents load it at session start for instant context:```typescript
// Exposed as toon://memory/summaries

…(正文过长,页面只展示前面部分,完整内容见仓库)
```

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Toon Memory 怎么安装?

在客户端按下面的安装命令接入:# Interactive installer — detects agents and configures MCP npx toon-memory。装完在客户端配置里引用同一个包或端点。

Toon Memory 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Toon Memory 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Toon Memory 需要 API Key 吗?

资料没有标注鉴权方式,是否需要密钥取决于服务本身,接入前按官方文档确认。

Toon Memory 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、VS Code、Windsurf、Cline;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Toon Memory 能提供哪些能力?

资料显示能力标签包括 记忆。具体工具清单以官方文档为准。

Toon Memory 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

Toon Memory 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 未标注。