Memory

A Touba memory is a logical resource, not a native backend. It names something that tools may read or write; the real access goes through a tool, a manifest, and a handler.

Structure

source .tb -> AIR -> resource binding + manifest -> handler -> real backend

Shape

source.tb

memory ProjectKnowledge

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

uses memory <Name> read (or write) declares the logical access required by the tool. requires memory_read (or memory_write) declares the corresponding capability.

Simple Case

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

This tool declares that it needs read access to ProjectKnowledge. It does not say which backend (file, database, vector store) actually responds; that wiring belongs to the resource binding and manifest.

Advanced Case

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

The memory ProjectKnowledge read scope is declared on both the skill and the agent: this scope, crossed with the tool (uses memory ... read), the manifest (memories grants), and the resource binding, is what the runtime verifies before dispatch.

What memory Carries

Without memory, access to an external store would be a hidden effect inside an ordinary tool, with no scope declaration and no cross-check between owner, tool, and manifest.

With memory, the logical access becomes a visible contract: who may request it (scope on skill / agent), who may execute it (tool with uses memory ... read/write), and what the manifest actually grants.

Runtime Contract

• memory contains no content: it is a logical reference, not a store.
• Memory backends are implemented by handlers: file, database, vector store, internal service, or another governed host system.
• The runtime does not read .env, implicit configuration, or workspace scans to resolve a memory.
• Content provenance and integrity for memories (metadata, digests) are covered separately in Memory Provenance and Integrity.
• Real backend wiring (resource binding, manifest, detailed scopes) is covered in Memories and Scopes.