Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Memory Model

This page defines how Toolang uses memory during runtime execution.

Memory is a plugin concern. Toolang core does not define a separate public memory-strategy system.

Core rule

Toolang has one external memory concept:

  • memory plugin

If memory behavior needs to change, that change should happen by:

  • selecting a different memory plugin
  • changing that plugin's configuration

Runtime boundary

Toolang runtime is responsible for:

  • deciding when memory is used
  • passing explicit recall and write requests
  • recording memory diagnostics in prompt traces and run traces

The memory plugin is responsible for:

  • recalling memory
  • writing memory
  • reporting health

The memory plugin must not:

  • mutate runtime scheduling
  • rewrite prompt text directly
  • decide turn admission
  • append bus events by itself

Minimal interface

class MemoryPlugin(Protocol):
    def recall(self, request: MemoryRecallRequest) -> MemoryRecallResult: ...
    def remember(self, batch: MemoryWriteBatch) -> MemoryWriteResult: ...
    def health(self) -> PluginHealth: ...

The plugin returns structured data. Prompt rendering remains a Toolang runtime responsibility.

Recall

Recall happens before the final prompt is built.

Suggested request fields:

  • agent_uri
  • agent_id
  • thread_id
  • turn_id
  • origin
  • sender
  • query_text
  • execution_strategy
  • limits
  • meta

Suggested response fields:

  • items
  • facts
  • summaries
  • provider
  • diagnostics

Remember

Remember happens after a turn completes and local state is saved.

Suggested write fields:

  • agent_uri
  • agent_id
  • thread_id
  • turn_id
  • origin
  • entries
  • meta

Suggested result fields:

  • written
  • provider
  • diagnostics

Failure and ordering

Memory is an augmentation layer, not the execution truth.

Rules:

  • recall failure may degrade a turn, but should not crash the runtime by default
  • write failure should not retroactively fail a completed turn
  • failures should be visible in diagnostics and traces

Recommended order:

  1. write local turn state
  2. write prompt trace
  3. perform memory write
  4. append shared bus projection events
  5. perform outbound delivery

Configuration and diagnostics

Memory configuration should identify:

  • plugin name
  • plugin instance settings

Prompt traces and run traces should record:

  • selected memory plugin
  • recall request summary
  • recall diagnostics
  • write diagnostics
  • degraded mode indicators

Read next

© 2026 Toolang