Vox Memory System

The memory system combines Codex (VoxDB) for structured, queryable data with workspace files for human-edited logs and optional exports. There is no single on-disk file for “all memory”; use the table below to pick the right tier.

Tiered persistence (SSOT by concern)

For RAM vs database vs JSONL tradeoffs across the whole stack (A2A, sessions, training corpora), use Database nomenclature — agent SSOT.

Architecture (high level)

┌─────────────────────────────────────────────────────────────┐
│  Codex (VoxDB): structured memory, knowledge, sessions      │
│  (tier: canonical vox.db vs repo .vox/store.db — see how-to)│
└────────────────────────────┬────────────────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              ▼                             ▼
    ┌──────────────────┐         ┌─────────────────┐
    │ MemoryManager    │         │ SessionManager  │
    │ (markdown logs)  │         │ (Codex events)  │
    └────────┬─────────┘         └─────────────────┘
             ▼
   memory/MEMORY.md, memory/logs/*.md

MCP Tools

Usage

#![allow(unused)]
fn main() {
// From Rust
use vox_db::VoxDb;

let db = VoxDb::open("path/to/db.sqlite").await?;

// Store a memory
db.store_memory("user_preference", "Use tabs for indentation").await?;

// Recall it
let val = db.recall_memory("user_preference").await?;

// Search
let results = db.search_memories("indentation").await?;
}

Compaction

When context gets large, use vox_compaction_status to check token budget. The CompactionEngine supports three strategies:

• Summarize — condense history into a summary block
• Drop Oldest — drop oldest entries until under budget
• Hybrid — summarize, then drop if still over

Persistence (summary)

• vox_memory_store → flat text in memory/MEMORY.md (workspace).
• vox_memory_log → memory/logs/YYYY-MM-DD.md.
• vox_memory_save_db / DB-backed tools → Codex relational tables for structured queries and search.

Storage and domain persistence

Prefer Arca-governed VoxDb operations in crates/vox-db for gamification (vox-ludus), schedules, and telemetry rather than duplicating state in unstructured logs. Markdown remains appropriate for human-curated narratives alongside Codex.