Storage & Ledger

Yunque Agent uses a dual-layer persistence architecture: SQLite relational storage + Ledger KV configuration store. All data is local-first with zero external service dependencies.

Architecture Overview

┌──────────────────────────────────────────┐
│           Application Layer              │
├───────────┬──────────────┬───────────────┤
│  SQLite   │  Ledger KV   │  Filesystem   │
│ (relational) │ (key-value)  │ (plugins/skills) │
├───────────┴──────────────┴───────────────┤
│           data/yunque.db                  │
└──────────────────────────────────────────┘

SQLite Relational Storage

Yunque uses pure-Go embedded SQLite (modernc.org/sqlite) — no CGO dependency.

Core Tables

Table	Purpose	Indexes
memories	Memory entries (short/mid/long-term) with vector embeddings	tenant_id, category
sessions	Conversation sessions	tenant_id
messages	Chat messages (role + content), cascade delete	session_id
bots	Bot definitions and config	—
inbox	Inbox items (notifications, task events)	is_read
models	Registered models (base_url, modalities, reasoning support)	—

Production Configuration

WAL mode — concurrent reads, non-blocking single writer
_busy_timeout=5000 — lock wait 5 seconds
MaxOpenConns=1 — SQLite single-writer mode

Ledger KV Store

Ledger KV stores JSON configuration data in SQLite, replacing the earlier scattered JSON file pattern. Wrapped by KVConfigStore with namespace isolation.

KV Namespaces

Over 25 subsystems use Ledger KV, including:

Category	Subsystems
Core State	StateKernel, TrustScore, CostTracker
Memory	Knowledge, EmotionHistory, WorkingMemory
Tasks	TaskTemplate, TaskGrowth, Thread, ForkPersist
Skills	Optimizer, SkillGrow
Security	ApprovalRules, ChannelGroups, IdentityBinding
Execution	WorkflowStore, TriggerStore, WasmSandbox
Cognitive	Reverie, ExperienceStore, LoRAScheduler
Other	BotManager, Inbox, IdentityResolver

All writes use KV-first, file-fallback mode — JSON files are auto-migrated to KV on startup.

Vector Index

Yunque includes three vector retrieval engines, auto-selected by data scale:

Engine	Complexity	Use Case
IVF (Inverted File)	O(N/K × nprobe)	Default, >1000 vectors
HNSW (Hierarchical Navigable Small World)	O(log N)	Large-scale, 100K+ vectors
Brute Force	O(N)	Auto-fallback when <1000 vectors

Ledger Persistence Layer

Ledger bridges in-memory computation with SQLite storage through two persisters:

• LedgerPersister — Persists mid/long-term memory layers (TF-IDF, BM25, vector computation runs in-memory)
• LedgerOrchPersister — Persists knowledge graph (entities + relations) and editable memory

Auto Maintenance

Interval	Task
5 min	WAL Checkpoint
1 hour	Integrity check
6 hours	Memory temporal decay
24 hours	Event compaction

Filesystem Storage

Some data uses the filesystem, including the database file itself and directory-based resources:

data/
├── yunque.db          # SQLite main database
├── plugins/           # Plugin directories (plugin.json + scripts)
├── skills/            # File-based skills (SKILL.md + meta.json)
├── knowledge/         # Knowledge base documents
├── stickers/          # Sticker assets
└── backup/            # Auto backups

Distributed Sync (Experimental)

Multi-instance deployment support:

• SyncEngine — Version vector causal ordering
• HTTP SyncTransport — Peer-to-peer event sync
• HTTP StreamTransport — Real-time event broadcast