Skip to main content

​
Conversation Memory

Conversation memory allows an Agent to reuse stored conversation context during execution. BindAI’s memory package provides a common API for storing, retrieving, searching, and managing memory records. The Agent runtime integrates with this API to load and persist conversation context in the standard execution pipeline.

​
Memory Records

The memory package works with MemoryRecord objects through the Memory facade and its selected provider. The facade exposes these operations:
  • set(record) — store a record.
  • get(key, namespace="default") — retrieve a record.
  • search(query, namespace="default", limit=10, metadata=None) — search records.
  • exists(key, namespace="default") — check whether a record exists.
  • delete(key, namespace="default") — delete a record.
  • clear(namespace="default") — clear a namespace.
The selected provider determines the underlying storage behavior. Persistence across process restarts depends on the provider and its configuration.

​
How Agent Conversation Memory Works

The standard Agent execution pipeline uses a memory step to load stored context and a finish step to persist the conversation.

​
Loading stored context

During standard execution, MemoryStep retrieves the record with the key __context__ through agent.memory.get(). If the retrieval succeeds and returns a record, its value is added to the Agent conversation as a system message prefixed with Relevant memory:. If retrieval fails or no record is returned, the memory step continues without adding that message.

​
Saving conversation context

When the standard pipeline reaches FinishStep, it builds a text transcript from the messages in the Agent’s conversation. Each line contains the message role and content. If agent.memory is configured, the finish step stores the transcript as a MemoryRecord with the key __context__. The saved record uses the default namespace because the finish step does not specify another namespace. This means the key and namespace used for context storage matter when multiple Agents or conversations share a memory provider. Applications that need separate histories should configure and use memory isolation deliberately.

​
Execution-path limitations

The memory behavior described above applies to the standard pipeline. The streaming pipeline also includes the memory-loading step, but the inspected implementation does not establish that streaming execution saves the transcript in the same way. Studio graph execution follows a separate path. Do not assume it has the same loading and saving behavior without verifying that execution path.

​
Memory and Workflow State

Memory and workflow state have different responsibilities. Configuring memory does not automatically configure workflow-state persistence, and configuring workflow state does not automatically configure conversation memory.

​
Memory and Knowledge

Memory and Knowledge are separate framework capabilities.
  • Memory provides operations for storing and retrieving memory records and, in the standard Agent pipeline, conversation context.
  • Knowledge provides the framework’s knowledge and retrieval functionality.
Do not assume that Knowledge documents are automatically stored in conversation memory or that both systems use the same backend.

​
Memory and Tools

Tools perform operations that an Agent or workflow can invoke. Memory provides record-management operations through its provider interface. These responsibilities are distinct. The presence of tools in a workflow does not determine how conversation context is stored.

​
Multiple Agents and Memory Isolation

The memory package supports namespaces in its record operations. The standard Agent pipeline uses the __context__ key without explicitly specifying a namespace when loading and saving context. As a result, Agents that share a provider and the same effective namespace may access the same context record. Do not assume that different Agent names automatically create separate conversation histories. For applications requiring isolated histories, use separate storage or namespace/key conventions and verify that the chosen configuration is applied consistently.

​
Memory Lifecycle Operations

The MemoryManager provides explicit record-level operations, including:
  • Updating access information.
  • Reinforcing a record’s importance.
  • Promoting eligible records to semantic memory.
  • Checking record expiration.
  • Setting or clearing expiration metadata.
  • Reducing record importance through decay.
These are explicit package-level operations. Their existence does not establish automatic scheduled cleanup or automatic forgetting of expired records.

​
Persistence and Storage

The memory package registers provider implementations under these names:
  • memory
  • sqlite
  • vector
  • postgresql
  • pinecone
  • chroma
The available implementations do not guarantee that every provider is configured or operational in every environment. Storage behavior and persistence depend on the provider and its configuration. For conversation memory across separate executions or process restarts, verify the selected provider, its configuration, and the lifecycle of the Agent’s conversation object.

​
Privacy and Data Retention

Conversation memory may contain sensitive application information. The standard pipeline stores message roles and content in the __context__ record. When using memory, consider:
  • Who can access the selected storage backend.
  • What information should be retained.
  • How records can be deleted.
  • Whether stored data is included in backups.
  • How credentials and database files are protected.
Memory persistence is not an authorization mechanism. Applications remain responsible for access control and data-retention requirements.

​
Testing Conversation Memory

For basic provider operations:
  1. Select a provider.
  2. Store a MemoryRecord.
  3. Retrieve it using the same key and namespace.
  4. Verify the returned record and operation result.
  5. Test deletion and namespace clearing where appropriate.
For Agent conversation memory, test the standard execution path by verifying that a previous __context__ record is loaded and that the resulting transcript is stored after execution. Also test namespace isolation and persistence across restarts if the application requires those behaviors. Test streaming and Studio execution separately if those paths are used by the application.

​
Summary

BindAI provides provider-based memory operations and integrates conversation-context loading and transcript persistence into the standard Agent execution pipeline. The pipeline uses the __context__ key and the default namespace unless the surrounding configuration or implementation changes the effective storage behavior. Streaming and Studio execution follow distinct paths, so do not assume they have identical memory-saving behavior.