Struct Memory 

pub struct Memory { /* private fields */ }

Mémoire d’un agent : moteur de stockage (vecteur natif) + embedder, scellés par un AgentId. Le chiffrement est obligatoire (ADR-007).

Implementations

impl Memory

pub async fn export_jsonl(&self) -> Result<String>

Exporte tout ce qui appartient à cet agent — souvenirs (y compris invalidés/expirés : c’est un backup, la validité est préservée), entités et relations du graphe — en JSONL versionné.

Les embeddings sont volontairement exclus (re-calculables) : le fichier est portable entre machines et entre modèles d’embedding.

Errors

Propage les erreurs de stockage/sérialisation.

pub async fn import_jsonl(&self, jsonl: &str) -> Result<ImportReport>

Importe un export JSONL dans cette mémoire (l’agent cible est celui de la façade, quel que soit l’agent_id d’origine de l’export).

Les souvenirs sont ré-embeddés par l’embedder courant (une passe embed_batch par lots de 128), puis tout est inséré dans une seule transaction : l’import aboutit entièrement ou pas du tout. Idempotent : les lignes dont l’identifiant existe déjà sont comptées en *_skipped et laissées intactes.

Errors

MemoryError::Porting si l’en-tête manque/diverge ou si une ligne est malformée ; MemoryError::UnknownLayer si une couche est inconnue ; propage les erreurs d’embedding/stockage.

impl Memory

pub fn new(store: Store, embedder: Box<dyn Embedder>, agent: AgentId) -> Self

Assemble une mémoire à partir des primitives du core déjà construites, sans migrer le schéma (à utiliser quand le schéma est déjà en place).

pub async fn open( store: Store, embedder: Box<dyn Embedder>, agent: AgentId, ) -> Result<Self>

Ouvre une mémoire : vérifie le chiffrement, applique le schéma (memory + index vecteur natif), puis renvoie la façade scellée par agent.

Le chiffrement est obligatoire pour les stores sur fichier (ADR-007) : un store :memory: est éphémère, la règle ne s’y applique pas.

Errors

crate::MemoryError::EncryptionRequired si le store est sur fichier et non chiffré. crate::MemoryError::Core si la migration échoue.

Examples found in repository

examples/llm_consolidation.rs (line 55)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = Store::open_in_memory().await?;
    let agent = AgentId::new("consolidation-demo").expect("non-empty id");
    let memory = Memory::open(store, Box::new(FakeEmbedder), agent).await?;

    // Store a raw episode (what happened).
    memory
        .remember(
            "Alice attended a conference in Paris, the capital of France.",
            MemoryLayer::Episodic,
        )
        .await?;

    // Consolidate: extract facts + populate graph via FakeLlm.
    let report = consolidate(&memory, &FakeLlm).await?;
    println!(
        "Consolidation: {} episode(s) seen, {} fact(s) added, {} entity(ies) upserted, {} relation(s).",
        report.episodes_seen, report.facts_added, report.entities_upserted, report.relations_upserted,
    );

    // The extracted fact should now be searchable in semantic layer.
    let facts = memory
        .recall_by_layer("What is the capital of France?", MemoryLayer::Semantic, 5)
        .await?;
    println!("\nSemantic facts after consolidation ({}):", facts.len());
    for f in &facts {
        println!("  • {}", f.text);
    }

    Ok(())
}

examples/temporal_replacement.rs (line 46)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = Store::open_in_memory().await?;
    let agent = AgentId::new("temporal-demo").expect("non-empty id");
    let memory = Memory::open(store, Box::new(DemoEmbedder), agent).await?;

    let old_id = memory
        .remember("The user is on the Free billing plan.", MemoryLayer::Semantic)
        .await?;

    println!("Initially remembered: Free plan ({old_id})");

    memory.invalidate(&old_id).await?;
    let new_id = memory
        .remember("The user is on the Pro billing plan.", MemoryLayer::Semantic)
        .await?;

    println!("Invalidated old fact and remembered: Pro plan ({new_id})");

    let hits = memory.recall_hybrid("current billing plan", 5).await?;
    println!("\nRecall for `current billing plan`:");
    for hit in &hits {
        println!("  [{layer}] {text}", layer = hit.layer.table(), text = hit.text);
    }

    assert!(
        hits.iter().any(|r| r.text.contains("Pro billing plan")),
        "the current fact should be recalled"
    );
    assert!(
        hits.iter().all(|r| !r.text.contains("Free billing plan")),
        "the invalidated fact should not be recalled"
    );

    Ok(())
}

examples/memory_basic.rs (line 32)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = Store::open_in_memory().await?;
    let agent = AgentId::new("demo-agent").expect("non-empty id");
    let memory = Memory::open(store, Box::new(FakeEmbedder), agent).await?;

    memory
        .remember("The Eiffel Tower is in Paris.", MemoryLayer::Semantic)
        .await?;
    memory
        .remember("Paris is the capital of France.", MemoryLayer::Semantic)
        .await?;
    memory.remember("Bonjour!", MemoryLayer::ShortTerm).await?;

    println!("=== recall (top 2) ===");
    let results = memory.recall("What city is the Eiffel Tower in?", 2).await?;
    for r in &results {
        println!(
            "  [{layer}] {score:.3}  {text}",
            layer = r.layer.table(),
            score = r.score,
            text = r.text
        );
    }

    let first_id = results[0].id.clone();
    memory.invalidate(&first_id).await?;
    println!("\nInvalidated id={first_id}");

    let after = memory.recall("Eiffel Tower", 5).await?;
    println!("Recall after invalidation: {} result(s)", after.len());

    let stats = memory.stats().await?;
    println!(
        "\nStats: {} semantic, {} short-term (valid).",
        stats.semantic, stats.short_term
    );

    Ok(())
}

pub fn agent(&self) -> &AgentId

L’agent propriétaire de cette mémoire.

pub fn watch( &self, agent_id: &str, layer: Option<MemoryLayer>, ) -> MemorySubscription

S’abonne au flux d’événements mémoire de cet agent (et d’une couche donnée, si layer est fourni). L’abonnement renvoyé n’expose jamais le canal brut : l’isolation par agent/couche est appliquée côté serveur dans MemorySubscription::recv, jamais déléguée à l’appelant.

agent_id est capturé tel quel : un appelant qui passe l’identifiant d’un autre agent ne reçoit que les événements de cet autre agent — il ne peut pas remonter au-delà de ce que Memory émet, et chaque Memory n’émet que pour son propre agent. La sécurité multi-tenant repose sur l’isolation SQL en amont (ADR-006) ; ce filtre la prolonge au flux.

pub fn graph(&self) -> Graph

Façade graphe sur le même moteur, scellée par le même agent.

Permet aux consommateurs externes (MCP, REST, bindings) de traverser le graphe entités/relations (recall_graph) sans accéder au moteur, tout en conservant l’isolation par agent au niveau SQL (ADR-006).

pub async fn remember(&self, text: &str, layer: MemoryLayer) -> Result<String>

Mémorise un texte dans une couche, valide dès maintenant et sans expiration. Renvoie l’identifiant (UUID v4) du souvenir créé.

Errors

Propage les erreurs d’embedding/stockage.

Examples found in repository

examples/llm_consolidation.rs (lines 59-62)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = Store::open_in_memory().await?;
    let agent = AgentId::new("consolidation-demo").expect("non-empty id");
    let memory = Memory::open(store, Box::new(FakeEmbedder), agent).await?;

    // Store a raw episode (what happened).
    memory
        .remember(
            "Alice attended a conference in Paris, the capital of France.",
            MemoryLayer::Episodic,
        )
        .await?;

    // Consolidate: extract facts + populate graph via FakeLlm.
    let report = consolidate(&memory, &FakeLlm).await?;
    println!(
        "Consolidation: {} episode(s) seen, {} fact(s) added, {} entity(ies) upserted, {} relation(s).",
        report.episodes_seen, report.facts_added, report.entities_upserted, report.relations_upserted,
    );

    // The extracted fact should now be searchable in semantic layer.
    let facts = memory
        .recall_by_layer("What is the capital of France?", MemoryLayer::Semantic, 5)
        .await?;
    println!("\nSemantic facts after consolidation ({}):", facts.len());
    for f in &facts {
        println!("  • {}", f.text);
    }

    Ok(())
}

examples/temporal_replacement.rs (line 49)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = Store::open_in_memory().await?;
    let agent = AgentId::new("temporal-demo").expect("non-empty id");
    let memory = Memory::open(store, Box::new(DemoEmbedder), agent).await?;

    let old_id = memory
        .remember("The user is on the Free billing plan.", MemoryLayer::Semantic)
        .await?;

    println!("Initially remembered: Free plan ({old_id})");

    memory.invalidate(&old_id).await?;
    let new_id = memory
        .remember("The user is on the Pro billing plan.", MemoryLayer::Semantic)
        .await?;

    println!("Invalidated old fact and remembered: Pro plan ({new_id})");

    let hits = memory.recall_hybrid("current billing plan", 5).await?;
    println!("\nRecall for `current billing plan`:");
    for hit in &hits {
        println!("  [{layer}] {text}", layer = hit.layer.table(), text = hit.text);
    }

    assert!(
        hits.iter().any(|r| r.text.contains("Pro billing plan")),
        "the current fact should be recalled"
    );
    assert!(
        hits.iter().all(|r| !r.text.contains("Free billing plan")),
        "the invalidated fact should not be recalled"
    );

    Ok(())
}

examples/memory_basic.rs (line 35)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = Store::open_in_memory().await?;
    let agent = AgentId::new("demo-agent").expect("non-empty id");
    let memory = Memory::open(store, Box::new(FakeEmbedder), agent).await?;

    memory
        .remember("The Eiffel Tower is in Paris.", MemoryLayer::Semantic)
        .await?;
    memory
        .remember("Paris is the capital of France.", MemoryLayer::Semantic)
        .await?;
    memory.remember("Bonjour!", MemoryLayer::ShortTerm).await?;

    println!("=== recall (top 2) ===");
    let results = memory.recall("What city is the Eiffel Tower in?", 2).await?;
    for r in &results {
        println!(
            "  [{layer}] {score:.3}  {text}",
            layer = r.layer.table(),
            score = r.score,
            text = r.text
        );
    }

    let first_id = results[0].id.clone();
    memory.invalidate(&first_id).await?;
    println!("\nInvalidated id={first_id}");

    let after = memory.recall("Eiffel Tower", 5).await?;
    println!("Recall after invalidation: {} result(s)", after.len());

    let stats = memory.stats().await?;
    println!(
        "\nStats: {} semantic, {} short-term (valid).",
        stats.semantic, stats.short_term
    );

    Ok(())
}

pub async fn remember_with( &self, text: &str, layer: MemoryLayer, validity: Validity, ) -> Result<String>

Mémorise un texte avec une fenêtre de validité explicite. Renvoie l’identifiant (UUID v4) du souvenir créé — les consommateurs (MCP, REST, bindings) le retournent à l’appelant pour invalidation/effacement ultérieurs.

L’insertion memory + miroir FTS est atomique (Store::begin_write) : jamais de souvenir visible par vecteur mais invisible en BM25, ou l’inverse.

Errors

MemoryError::TextTooLong si text dépasse MAX_TEXT_LEN. Propage aussi les erreurs d’embedding/stockage.

pub async fn remember_batch( &self, texts: &[String], layer: MemoryLayer, ) -> Result<Vec<String>>

Mémorise un lot de textes dans une couche, valides dès maintenant et sans expiration. Renvoie les identifiants créés, dans l’ordre des textes.

Errors

Propage les erreurs d’embedding/stockage.

pub async fn remember_batch_with( &self, texts: &[String], layer: MemoryLayer, validity: Validity, ) -> Result<Vec<String>>

Mémorise un lot avec une fenêtre de validité explicite : une passe d’embedding (Embedder::embed_batch) et une transaction — le lot devient visible d’un coup, ou pas du tout. C’est le chemin de l’ingestion initiale (import d’historique, seed de connaissances).

Errors

MemoryError::TextTooLong si un texte du lot dépasse MAX_TEXT_LEN (fail-fast : le premier texte trop long stoppe le lot, rien n’est inséré puisque la validation précède l’embedding/la transaction). Propage aussi les erreurs d’embedding/stockage.

pub async fn recall(&self, query: &str, k: usize) -> Result<Vec<Record>>

Recall temporel : pertinent ET valide, borné à cet agent.

L’isolation (agent_id) et le filtre temporel sont appliqués par le moteur de stockage (MemoryStore::recall_vector) — Memory ne connaît plus le SQL, seulement le vecteur de requête et l’agent.

Errors

Propage les erreurs d’embedding/recherche.

Examples found in repository

examples/memory_basic.rs (line 43)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = Store::open_in_memory().await?;
    let agent = AgentId::new("demo-agent").expect("non-empty id");
    let memory = Memory::open(store, Box::new(FakeEmbedder), agent).await?;

    memory
        .remember("The Eiffel Tower is in Paris.", MemoryLayer::Semantic)
        .await?;
    memory
        .remember("Paris is the capital of France.", MemoryLayer::Semantic)
        .await?;
    memory.remember("Bonjour!", MemoryLayer::ShortTerm).await?;

    println!("=== recall (top 2) ===");
    let results = memory.recall("What city is the Eiffel Tower in?", 2).await?;
    for r in &results {
        println!(
            "  [{layer}] {score:.3}  {text}",
            layer = r.layer.table(),
            score = r.score,
            text = r.text
        );
    }

    let first_id = results[0].id.clone();
    memory.invalidate(&first_id).await?;
    println!("\nInvalidated id={first_id}");

    let after = memory.recall("Eiffel Tower", 5).await?;
    println!("Recall after invalidation: {} result(s)", after.len());

    let stats = memory.stats().await?;
    println!(
        "\nStats: {} semantic, {} short-term (valid).",
        stats.semantic, stats.short_term
    );

    Ok(())
}

pub async fn recall_with_metric( &self, query: &str, k: usize, metric: Metric, ) -> Result<Vec<Record>>

Recall sémantique temporel avec métrique explicite (Metric).

Metric::Cosine emprunte le chemin natif ; Metric::Euclidean et Metric::Hamming sur-échantillonnent les candidats cosinus puis sont re-classées en Rust (ADR-012). Met à jour last_access sur les résultats.

Errors

Propage les erreurs d’embedding/recherche.

pub async fn recall_hybrid(&self, query: &str, k: usize) -> Result<Vec<Record>>

Recall hybride (ADR-014) : fusionne le classement vectoriel et le classement BM25 (full-text natif libSQL) par Reciprocal Rank Fusion (rrf_fuse). Un terme exact que l’embedding rate (sigle, identifiant rare, nom propre) remonte par BM25 ; une reformulation que les mots-clés ratent remonte par le vecteur. Borné à l’agent et à la validité. Met à jour last_access sur les résultats.

Le score du Record retourné porte le score RRF fusionné, pas la similarité cosinus.

Errors

Propage les erreurs d’embedding/recherche/stockage.

Examples found in repository

examples/temporal_replacement.rs (line 61)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = Store::open_in_memory().await?;
    let agent = AgentId::new("temporal-demo").expect("non-empty id");
    let memory = Memory::open(store, Box::new(DemoEmbedder), agent).await?;

    let old_id = memory
        .remember("The user is on the Free billing plan.", MemoryLayer::Semantic)
        .await?;

    println!("Initially remembered: Free plan ({old_id})");

    memory.invalidate(&old_id).await?;
    let new_id = memory
        .remember("The user is on the Pro billing plan.", MemoryLayer::Semantic)
        .await?;

    println!("Invalidated old fact and remembered: Pro plan ({new_id})");

    let hits = memory.recall_hybrid("current billing plan", 5).await?;
    println!("\nRecall for `current billing plan`:");
    for hit in &hits {
        println!("  [{layer}] {text}", layer = hit.layer.table(), text = hit.text);
    }

    assert!(
        hits.iter().any(|r| r.text.contains("Pro billing plan")),
        "the current fact should be recalled"
    );
    assert!(
        hits.iter().all(|r| !r.text.contains("Free billing plan")),
        "the invalidated fact should not be recalled"
    );

    Ok(())
}

pub async fn recall_by_layer( &self, query: &str, layer: MemoryLayer, k: usize, ) -> Result<Vec<Record>>

Recall filtré sur une couche unique. Met à jour last_access sur chaque souvenir retourné (l’oubli adaptatif en dépend).

Errors

Propage les erreurs d’embedding/recherche.

Examples found in repository

examples/llm_consolidation.rs (line 74)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = Store::open_in_memory().await?;
    let agent = AgentId::new("consolidation-demo").expect("non-empty id");
    let memory = Memory::open(store, Box::new(FakeEmbedder), agent).await?;

    // Store a raw episode (what happened).
    memory
        .remember(
            "Alice attended a conference in Paris, the capital of France.",
            MemoryLayer::Episodic,
        )
        .await?;

    // Consolidate: extract facts + populate graph via FakeLlm.
    let report = consolidate(&memory, &FakeLlm).await?;
    println!(
        "Consolidation: {} episode(s) seen, {} fact(s) added, {} entity(ies) upserted, {} relation(s).",
        report.episodes_seen, report.facts_added, report.entities_upserted, report.relations_upserted,
    );

    // The extracted fact should now be searchable in semantic layer.
    let facts = memory
        .recall_by_layer("What is the capital of France?", MemoryLayer::Semantic, 5)
        .await?;
    println!("\nSemantic facts after consolidation ({}):", facts.len());
    for f in &facts {
        println!("  • {}", f.text);
    }

    Ok(())
}

pub async fn invalidate(&self, id: &str) -> Result<()>

Invalide un souvenir en fixant valid_until = now(). Il n’apparaît plus dans les recalls futurs mais reste physiquement en base.

Errors

Propage les erreurs de stockage.

Examples found in repository

examples/temporal_replacement.rs (line 54)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = Store::open_in_memory().await?;
    let agent = AgentId::new("temporal-demo").expect("non-empty id");
    let memory = Memory::open(store, Box::new(DemoEmbedder), agent).await?;

    let old_id = memory
        .remember("The user is on the Free billing plan.", MemoryLayer::Semantic)
        .await?;

    println!("Initially remembered: Free plan ({old_id})");

    memory.invalidate(&old_id).await?;
    let new_id = memory
        .remember("The user is on the Pro billing plan.", MemoryLayer::Semantic)
        .await?;

    println!("Invalidated old fact and remembered: Pro plan ({new_id})");

    let hits = memory.recall_hybrid("current billing plan", 5).await?;
    println!("\nRecall for `current billing plan`:");
    for hit in &hits {
        println!("  [{layer}] {text}", layer = hit.layer.table(), text = hit.text);
    }

    assert!(
        hits.iter().any(|r| r.text.contains("Pro billing plan")),
        "the current fact should be recalled"
    );
    assert!(
        hits.iter().all(|r| !r.text.contains("Free billing plan")),
        "the invalidated fact should not be recalled"
    );

    Ok(())
}

examples/memory_basic.rs (line 54)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = Store::open_in_memory().await?;
    let agent = AgentId::new("demo-agent").expect("non-empty id");
    let memory = Memory::open(store, Box::new(FakeEmbedder), agent).await?;

    memory
        .remember("The Eiffel Tower is in Paris.", MemoryLayer::Semantic)
        .await?;
    memory
        .remember("Paris is the capital of France.", MemoryLayer::Semantic)
        .await?;
    memory.remember("Bonjour!", MemoryLayer::ShortTerm).await?;

    println!("=== recall (top 2) ===");
    let results = memory.recall("What city is the Eiffel Tower in?", 2).await?;
    for r in &results {
        println!(
            "  [{layer}] {score:.3}  {text}",
            layer = r.layer.table(),
            score = r.score,
            text = r.text
        );
    }

    let first_id = results[0].id.clone();
    memory.invalidate(&first_id).await?;
    println!("\nInvalidated id={first_id}");

    let after = memory.recall("Eiffel Tower", 5).await?;
    println!("Recall after invalidation: {} result(s)", after.len());

    let stats = memory.stats().await?;
    println!(
        "\nStats: {} semantic, {} short-term (valid).",
        stats.semantic, stats.short_term
    );

    Ok(())
}

pub async fn forget(&self, id: &str) -> Result<()>

Suppression physique d’un souvenir (RGPD, droit à l’effacement). Atomique : la ligne memory et son miroir FTS disparaissent ensemble.

Errors

Propage les erreurs de stockage.

pub async fn purge_agent(&self) -> Result<()>

Purge toutes les données de cet agent : souvenirs (memory), entités (entity) et relations (edge). Irréversible (RGPD, droit à l’oubli). Idempotent : ne renvoie pas d’erreur si l’agent n’a aucune donnée. Atomique : pas de purge partielle possible (tout ou rien).

Errors

Propage les erreurs de stockage.

pub async fn stats(&self) -> Result<AgentStats>

Statistiques des souvenirs valides de cet agent, par couche.

Errors

Propage les erreurs de stockage.

Examples found in repository

examples/memory_basic.rs (line 60)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = Store::open_in_memory().await?;
    let agent = AgentId::new("demo-agent").expect("non-empty id");
    let memory = Memory::open(store, Box::new(FakeEmbedder), agent).await?;

    memory
        .remember("The Eiffel Tower is in Paris.", MemoryLayer::Semantic)
        .await?;
    memory
        .remember("Paris is the capital of France.", MemoryLayer::Semantic)
        .await?;
    memory.remember("Bonjour!", MemoryLayer::ShortTerm).await?;

    println!("=== recall (top 2) ===");
    let results = memory.recall("What city is the Eiffel Tower in?", 2).await?;
    for r in &results {
        println!(
            "  [{layer}] {score:.3}  {text}",
            layer = r.layer.table(),
            score = r.score,
            text = r.text
        );
    }

    let first_id = results[0].id.clone();
    memory.invalidate(&first_id).await?;
    println!("\nInvalidated id={first_id}");

    let after = memory.recall("Eiffel Tower", 5).await?;
    println!("Recall after invalidation: {} result(s)", after.len());

    let stats = memory.stats().await?;
    println!(
        "\nStats: {} semantic, {} short-term (valid).",
        stats.semantic, stats.short_term
    );

    Ok(())
}

pub async fn search_graph(&self, query: &str, k: usize) -> Result<Vec<Record>>

Recall vectoriel limité aux souvenirs dont le contenu mentionne une entité du graphe (P2). Met à jour last_access sur les résultats.

Errors

Propage les erreurs d’embedding/recherche.