4-layer tiered memory loading with token budgets (L0-L3)

[Esity]

Summary

MemPalace ships a formal 4-layer memory loading stack with defined token budgets per layer and a total wake-up cost of ~600-900 tokens (leaving 95%+ of context free). Legion's memory architecture currently has no equivalent tiered contract — working memory, semantic recall, and observational memory all load without a formal budget or priority order.

MemPalace's Layer Design

Layer	Tokens	Always Loaded	Content
L0 — Identity	~100	✅	Who am I? identity.txt — user-written
L1 — Essential Story	~500-800	✅	Top-weighted memories auto-selected from palace
L2 — On-Demand	~200-500 each	❌	Wing/topic filtered retrieval when topic comes up
L3 — Deep Search	unlimited	❌	Full semantic search on explicit request

Total guaranteed context cost on wake-up: ~600-900 tokens. Deterministic. No surprise context blowout.

The Problem in Legion

Today:

• Working memory: always loaded, no token cap
• Observational memory: loaded based on audit logic
• Apollo semantic recall: triggered per-query, no pre-session priming
• No equivalent to L1 "essential story" — a pre-session summary of the most important things to know

The result is unpredictable context window usage and no guarantee that the most important long-term context survives a wake-up.

Proposed Design

Introduce a Legion::Extensions::Agentic::Memory::Layers coordinator:

# On session start — always called
Memory::Layers.wake_up(agent_id:, context_budget: 900) do |layers|
  layers.l0(:identity)      # ~100 tokens — agent identity/persona
  layers.l1(:essential)     # ~800 tokens — top-weighted traces from Memory::Trace
end

# On topic detection — lazy load
Memory::Layers.load_on_demand(topic:, wing:) # L2 — ~200-500 tokens

# On explicit search — unlimited
Memory::Layers.deep_search(query:)            # L3

L1 Essential Story Generation

The key unsolved piece: generating L1 requires selecting the highest-importance memories from the full trace store. MemPalace does this by importance-weighting drawers at mine time. Legion equivalent:

• Use Memory::Trace power-law decay scores as importance weights
• Select top-N traces by score until token budget fills
• Cache the L1 selection per agent (invalidate on new high-weight trace ingest)

Dependencies

• Memory::Trace (already in lex-agentic-memory) — for L1 weight scoring
• Apollo semantic recall — for L2/L3 retrieval
• Token counting utility (for budget enforcement)

References

• MemPalace layers.py — full L0-L3 implementation
• MemPalace: wake-up cost benchmark (~600-900 tokens, <100ms)