Skip to content
toon-memory logotoon-memory — The Continuity Layer for AI Agents

TOON Format — 22% Fewer Tokens Than JSON

What is TOON?

Section titled “What is TOON?”

TOON (Token-Oriented Object Notation) is a data format designed for LLMs. It uses ~22.5% fewer tokens than JSON (measured with gpt-tokenizer over representative entries) while maintaining lossless roundtrip.

Comparison

Section titled “Comparison”
Format Token Count LLM Accuracy
JSON 100 75%
YAML 95 72%
TOON 60 76.4%

Format Structure

Section titled “Format Structure”
version: 1
entries[3|]{id|category|key|content|file|tags|date|ttl|accessed|links|quality|confidence|lastAccessed|priority|path_scope|origin|status|supersededOn|importance}:
  a1b2c3d4|decision|use-zod|Use Zod for validation|src/types.ts|validation;types|2026-07-10||0|patterns/zod-schemas|0.80|1.00||0||agent|||
  e5f6g7h8|pattern|pydantic-configs|Project uses Pydantic v2|config.py|python;patterns|2026-07-10||0||0.72|1.00||0|||||high
  i9j0k1l2|bug|redis-pool-fix|Added max_connections=20|redis.ts|redis;fix|2026-07-10|7d|3||0.68|0.85||0||agent|obsolete||
summaries:
  src/services/redis.ts: Redis connection pool with retry logic

Components

Section titled “Components”
Component Description
version: 1 Format version
entries[N|]{fields}: Header with count and field names
id|category|key|... Pipe-separated values
ttl Optional time-to-live (empty = no expiration)
accessed Access count (for importance ranking)
links Semicolon-separated entry keys (graph edges)
quality Quality score 0-1 (auto-calculated)
confidence Confidence score 0-1 (1.0=asserted, <1.0=inferred)
lastAccessed ISO timestamp of last access (for importance ranking)
priority Pin priority 1-5 (0 = not pinned)
path_scope Optional file path scope (globMatch-friendly)
origin Entry origin: human, agent, or empty (inferred)
status Entry status: active, obsolete, suppressed, or empty
supersededOn Date when the entry was superseded
importance Explicit importance: critical, high, medium, low (empty = auto)
summaries: Optional file summaries

Entry Fields

Section titled “Entry Fields”
Field Required Description Example
id Yes 8-char hex ID a1b2c3d4
category Yes decision, pattern, bug, knowledge, warning decision
key Yes Kebab-case title use-zod
content Yes Detailed description Use Zod for validation
file No Related file path src/types.ts
tags No Semicolon-separated tags validation;types
date Yes YYYY-MM-DD 2026-07-10
ttl No Expiration: 7d, 30d, or 2026-12-31 7d
accessed No Access count (auto-incremented on recall) 3
links No Semicolon-separated entry keys (graph edges) patterns/zod-schemas
quality No Quality score 0-1 (auto-calculated) 0.80
confidence No Confidence score 0-1 (1.0=asserted) 1.00
lastAccessed No ISO timestamp of last access (auto-updated) 2026-07-10T12:00:00Z
priority No Pin priority 1-5 (0 = not pinned) 0
path_scope No File path scope for glob-matched recall src/
origin No Entry origin: human, agent, or empty agent
status No Entry status: active, obsolete, suppressed, empty obsolete
supersededOn No Date when the entry was superseded 2026-08-01
importance No Explicit importance: critical, high, medium, low (empty = auto, recency + frequency) critical

Benefits

Section titled “Benefits”
  1. Fewer tokens — More efficient for LLM context
  2. Better accuracy — LLMs understand it better than JSON
  3. Lossless — No data loss in conversion
  4. Human readable — Easy to read and edit manually