Mémoire (memory)

Une memory Touba est une ressource logique, pas un backend natif. Elle nomme quelque chose que des tool peuvent lire ou écrire ; l’accès réel passe par un tool, un manifest et un handler.

Structure

source .tb -> AIR -> resource binding + manifest -> handler -> backend réel

Forme

source.tb

memory ProjectKnowledge

tool ReadProjectKnowledge
    uses memory ProjectKnowledge read
    takes query as Query
    gives KnowledgeResult
    requires memory_read

uses memory <Name> read (ou write) déclare l’accès logique requis par le tool. requires memory_read (ou memory_write) déclare la capacité correspondante.

Cas simple

memoire_simple.tb

module examples.memoire_simple

memory ProjectKnowledge

type Query
    text is Text

type KnowledgeResult
    summary is Text

tool ReadProjectKnowledge
    uses memory ProjectKnowledge read
    takes query as Query
    gives KnowledgeResult
    requires memory_read

Ce tool déclare qu’il a besoin d’un accès en lecture à ProjectKnowledge. Il ne dit pas quel backend (fichier, base de données, vectoriel) répond réellement, ce câblage appartient au resource binding et au manifest.

Cas avancé

memoire_advanced.tb

module examples.memoire_advanced

memory ProjectKnowledge

type Query
    text is Text

type KnowledgeResult
    summary is Text

tool ReadProjectKnowledge
    uses memory ProjectKnowledge read
    takes query as Query
    gives KnowledgeResult
    requires memory_read

skill SummarizeKnowledge
    takes query as Query
    gives KnowledgeResult
    uses ReadProjectKnowledge
    memory ProjectKnowledge read
    do
        ReadProjectKnowledge
            with query as query
            into result
        give result

agent Researcher
    responsibility "Fulfill the declared Researcher responsibility using only authorized capabilities."
    uses SummarizeKnowledge
    memory ProjectKnowledge read
    callable_by strategy RunKnowledgeReview

strategy RunKnowledgeReview
    takes query as Query
    uses Researcher
    do
        Researcher

Le scope memory ProjectKnowledge read est déclaré à la fois sur la skill et sur l’agent : c’est ce périmètre, croisé avec le tool (uses memory ... read), le manifest (memories accordées) et le resource binding, que le runtime vérifie avant dispatch.

Ce que memory porte

Sans memory, un accès à un store externe resterait hors contrat dans un tool ordinaire, sans déclaration de scope, sans vérification croisée owner/tool/manifest.

Avec memory, l’accès logique devient un contrat visible : qui peut le demander (scope sur skill/agent), qui peut l’exécuter (tool avec uses memory ... read/write), et ce que le manifest accorde réellement.

Contrat runtime

• memory ne contient aucun contenu : c’est une référence logique, pas un store.
• Les backends mémoire sont implémentés par handlers : fichier, base de données, base vectorielle, service interne ou autre système hôte gouverné.
• Le runtime ne lit ni .env, ni configuration implicite, ni scan workspace pour résoudre une memory.
• La provenance et l’intégrité du contenu mémoire (métadonnées, digests) sont un sujet séparé, voir le guide Provenance et intégrité des mémoires.
• Pour le câblage backend réel (resource binding, manifest, scopes détaillés), voir le guide Mémoires et scopes.