Mémoires et scopes

Le compilateur vérifie les portées résolubles statiquement, y compris les tools atteints via les skills du catalogue d'un agent et les imports. La portée d'un skill ne prête pas son autorité à l'agent actif. Une délégation établit la frontière propre du destinataire. Les contrôles runtime restent obligatoires pour l'AIR direct, les bindings hôtes et les décisions dynamiques.

Dans Touba, une memory Touba est une ressource logique. Ce n’est pas un backend natif.

source.tb

memory ProjectKnowledge

Principe

Le lien entre Touba et une mémoire réelle passe par quatre couches :

Structure

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

Le resource binding dit quel backend hôte correspond à la mémoire logique. Le manifest dit quel handler peut exécuter le tool d’accès. Le runtime vérifie les deux avant dispatch.

Scope owner

Un owner peut déclarer un scope :

source.tb

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

Le scope dit que cet owner peut demander un accès logique.

Tool d’accès

L’accès effectif passe par un tool :

source.tb

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

Le handler du tool réalise l’accès concret : fichier, base de données, PostgreSQL, base vectorielle ou service interne. Les backends mémoire restent des composants hôtes reliés par contrat.

Resource binding

Le resource binding relie la mémoire logique à un câblage hôte non secret.

touba.resources.json

{
  "resource_bindings_schema_version": "touba-resource-bindings-v1",
  "resources": {
    "memory:examples/ProjectKnowledge": {
      "kind": "memory_backend",
      "provider": "host.http.memory_backend",
      "config": {
        "endpoint_url": "http://127.0.0.1:39123"
      },
      "grants": ["memory.read"],
      "secrets": ["MEMORY_BACKEND_TOKEN"],
      "required_secrets": ["MEMORY_BACKEND_TOKEN"],
      "limits": {
        "max_payload_bytes": 65536
      }
    }
  }
}

config ne doit pas contenir de token, DSN, clé API, payload brut ou valeur secrète. Les valeurs sensibles restent dans le système de secrets et sont référencées par handles.

Manifest

Le manifest doit accorder l’accès mémoire au binding de tool.

touba.manifest.json

"memories": [
  { "ref": "memory:examples/ProjectKnowledge", "access": "read" }
]

Le runtime croise l’accès déclaré par le tool, le grant manifest, le binding mémoire et le scope de l’owner actif.

Avec la transmission des resource bindings (RB-2), le runtime transmet ensuite au handler seulement les resource bindings des ressources effectivement utilisées par le tool appelé. Dans le SDK JavaScript, le handler les lit via context.resourceBindings.

Exemple PostgreSQL

Si PostgreSQL sert de mémoire, PostgreSQL reste côté handler ou côté service hôte.

Le programme Touba déclare la mémoire logique et le droit d’accès. Le resource binding indique le backend hôte et les handles attendus. Le manifest indique quel handler appeler. Le handler contient le code PostgreSQL ou appelle un service interne, et reçoit seulement les secrets explicitement accordés.

Pour un scénario HTTP rejouable, voir Mémoire avec backend hôte.

Pour un scénario avec PostgreSQL réel, agent actif, scopes read / write et refus avant écriture en base, voir Mémoire PostgreSQL avec agent et scopes.

Le backend hôte peut être lancé directement par votre application, par un service interne ou par Docker. Cela ne change pas la sémantique Touba : le runtime consomme toujours un resource binding explicite et ne découvre pas le backend par convention.

Périmètre

Touba fournit la déclaration de mémoire logique, les scopes owner, les déclarations d’accès tool, les grants manifest, les resource bindings et les vérifications runtime avant dispatch.

Les stores mémoire natifs, adaptateurs PostgreSQL ou vectoriels natifs, langages de politiques enrichis et écritures implicites dans le workspace relèvent des intégrations hôtes et couches plateforme ultérieures.

Mémoire commune à des branches parallèles

Les valeurs locales d'une branche ne fusionnent pas les mémoires persistantes. Les accès read compatibles à une même mémoire logique peuvent coexister ; une écriture write ou append prend un verrou exclusif pendant le dispatch. Les verrous sont acquis dans un ordre canonique lorsqu'un tool utilise plusieurs mémoires. Ils ne couvrent pas tout un sous-workflow ni ses appels modèle.

Cette protection est propre au runtime qui exécute le groupe. Un autre processus ou service peut écrire dans le même backend : le handler doit donc appliquer les contrôles de révision, transactions ou idempotence du backend quand nécessaires. Une jointure parallel n'est pas une transaction distribuée. Voir Strategy et Effets idempotents.