Memory Evolution

This document tracks the evolution of Aleph's memory system through its design specifications.

Spec 1: Memory Capture Hooks

Status: Shipped
Focus: Observability and extension points for memory lifecycle events.

Introduced three hooks:

• PreCompress — Fired before session compression; allows extensions to inspect/modify raw memory
• Delegation — Fired when memory operations are delegated to sub-agents
• SessionEnd — Fired when a session closes; triggers final compaction

These hooks became the foundation for the later MemoryExtension trait (Spec 4).

Spec 2: MemoryReflector

Status: Shipped
Focus: Synthesis layer on top of raw retrieval.

Instead of returning a ranked list of facts, MemoryReflector:

1. Retrieves candidate facts via HybridAssembler
2. Asks the LLM to synthesise a coherent answer
3. Returns the answer with cited sources

pub struct MemoryReflector {
    assembler: Arc<dyn WorkingMemoryAssembler>,
    llm: Arc<dyn LlmBackend>,
}

Exposed via the memory_reflect builtin tool.

Key insight: Retrieval gives candidates; synthesis produces answers.

Spec 3: Context Fencing + Memory Modes

Status: Shipped
Focus: Control over how memory is injected into prompts.

Three memory modes:

• Context — Memory injected directly into system prompt
• Tools — Memory retrieved on-demand via memory_search / memory_reflect
• Hybrid — Both: critical facts in context, detailed queries via tools

Context fencing ensures memory never exceeds token budgets by using AssemblyBudget limits.

Spec 4: Pluggable Memory Extensions

Status: Shipped
Focus: Third-party extensions for custom memory behavior.

#[async_trait]
pub trait MemoryExtension: Send + Sync {
    fn name(&self) -> &str;
    async fn on_memory_created(&self, event: &MemoryEvent, backend: &MemoryBackend
    ) -> Result<(), AlephError>;
    async fn on_memory_retrieved(
        &self, query: &str, facts: &[MemoryFact], backend: &MemoryBackend
    ) -> Result<Vec<MemoryFact>, AlephError>;
    async fn on_session_end(
        &self, session_id: &str, backend: &MemoryBackend
    ) -> Result<(), AlephError>;
}

Extensions register at startup and receive callbacks for all memory events.

Spec A: Curated Hot Memory

Status: Shipped
Focus: Human-curated, frozen snapshot of critical facts.

Problem: Automatic retrieval sometimes misses facts that are obvious to humans.

Solution: Allow users to pin critical facts via the remember tool:

<builtin_tool>remember</builtin_tool>
<parameter name="content">User is allergic to shellfish</parameter>
<parameter name="priority">10</parameter>

• Stored in ~/.aleph/memory/curated/{agent_id}.json
• Frozen snapshot — changes require explicit re-curation
• Injected into every prompt unconditionally (within token budget)
• Bypasses normal retrieval and scoring entirely

Spec B: session_search Summarization

Status: Shipped
Focus: Summarise multiple sessions matching a query.

The session_search tool now returns:

1. Matching sessions with relevance scores
2. An AI-generated summary synthesising findings across sessions
3. Key quotes from transcripts

<builtin_tool>session_search</builtin_tool>
<parameter name="query">What did we decide about the database schema?</parameter>
<parameter name="limit">5</parameter>

Spec C: Cross-Process Safety

Status: Shipped
Focus: Safe concurrent access to SQLite from multiple processes.

Problem: Aleph can run multiple processes (CLI + GUI, or multiple agents).

Solution:

• WAL mode (Write-Ahead Logging) for SQLite
• Busy timeout (5s) with exponential backoff
• Lock recovery: unwrap_or_else(|e| e.into_inner())
• File locking for curated memory writes
• Atomic operations for note index updates

Timeline

Future Directions

Specs currently in design (not yet shipped):

• Spec 5: Multi-modal memory (images, audio embeddings)
• Spec D: Memory federation (sync across devices)

See Also

• Memory System — Current system overview
• Memory Architecture — Implementation details
• Gateway: Memory Methods — API reference