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.

The MemoryExtension trait has since converged on five hook points: on_capture, on_retrieve, on_delegation, on_pre_compress, and on_session_switch.

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

Memory Hub Unification

Status: Shipped (2026-06-20)
Focus: Fold the two former memory surfaces into one host.

The radial Graph canvas (formerly /memory) and the faceted Table vault (formerly /dashboard/memory) are now a single Memory Hub with a shared toolbar — a Graph ↔ Table toggle, unified search, and a shared agent selector.

• Node identity is the note path; the same note is the same entity in both views.
• Bidirectional navigation: a table row's View in graph highlights the node, and a graph node's View in list jumps the table to that note's facet/page and opens its drawer.
• The old /dashboard/memory route now redirects to /memory?view=table.

Governance Surfacing

Status: Shipped (2026-06-20)
Focus: Read-only observability for the memory governance lifecycle.

Writes stay LLM/tool-driven; these surfaces only observe. Both live under Settings → Memory.

• Dream Insights panel — recent daily synthesis notes from the dream daemon plus dream-run history, backed by dreaming.list_insights (with dreaming.run_now to trigger a synthesis on demand).
• Corrections panel — surfaces the correction → distillation lifecycle, backed by memory.list_corrections.
• Retrieval trace — memory.retrieve_with_trace is wired to the real NoteFactRetrieval scoring pipeline and returns per-stage telemetry (query → candidate pool → BM25 + vector scores → RRF fusion → cutoff → ranked) for debugging why a fact did or didn't surface.

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