Conversation Memory

BindAI provides a flexible memory system that applications can use to preserve useful information across agent executions. Memory is exposed through the Memory abstraction and can be attached to an agent through its memory configuration. The current memory system is record-based. It is not limited to a specific conversation-history format, which allows applications to decide what information should be stored and how it should be retrieved.

What is Conversation Memory?

Conversation-related information can be stored as MemoryRecord objects and retrieved during later executions. A memory record contains a key, value, namespace, and additional memory information.

from bindai import MemoryRecord

record = MemoryRecord(
    key="favorite_language",
    value="Python",
)

The record can then be stored in a Memory instance:

from bindai import Memory

memory = Memory()

memory.set(record)

Conversation memory therefore provides application-level persistence for information that should remain available beyond a single interaction.

Attaching Memory to an Agent

An agent can be configured with a Memory instance using Agent.builder().

from bindai import Agent, Memory

memory = Memory()

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .memory(memory)
    .build()
)

The memory implementation remains separate from the agent itself.

Agent
  |
  v
Memory
  |
  v
Memory Provider

This separation allows the same agent architecture to work with different memory providers.

Storing Conversation Information

Applications can explicitly store useful conversation-related information. For example:

from bindai import Memory, MemoryRecord

memory = Memory()

memory.set(
    MemoryRecord(
        key="favorite_language",
        value="Python",
        namespace="user-123",
    )
)

The namespace can be used to separate information belonging to different users, conversations, tenants, or other logical scopes. Conversation memory is therefore controlled by the application rather than requiring a fixed transcript format.

Reading Memory

Stored information can be retrieved using get().

result = memory.get(
    "favorite_language",
    namespace="user-123",
)

The result is returned through BindAI’s memory result interface. Applications can use the retrieved value in subsequent application logic, prompt construction, workflow execution, or other processing. For example, an application can check whether a result was found and then use the stored value:

if result.value is not None:
    favorite_language = result.value

The exact result state should be handled according to the configured memory provider and the MemoryResult interface.

Searching Memory

Memory also provides a query-based search() operation.

results = memory.search(
    "favorite programming language",
    namespace="user-123",
)

The search operation accepts:

A query
A namespace
A result limit
Optional metadata filtering

For example:

results = memory.search(
    "programming preferences",
    namespace="user-123",
    limit=5,
)

The exact retrieval behavior depends on the configured memory provider. Providers may use different underlying strategies, including local storage, database-backed retrieval, or vector-oriented retrieval.

Namespaces

Namespaces provide logical isolation between groups of memory records. For example:

MemoryRecord(
    key="favorite_language",
    value="Python",
    namespace="user-123",
)

and:

MemoryRecord(
    key="favorite_language",
    value="JavaScript",
    namespace="user-456",
)

These records use the same key but belong to different namespaces. An application can retrieve the record belonging to a specific namespace:

memory.get(
    "favorite_language",
    namespace="user-123",
)

Namespaces are useful for separating:

Users
Conversations
Tenants
Agents
Projects
Applications
Other logical memory scopes

Namespaces are particularly important when a single memory provider serves multiple independent users or application contexts.

Conversation Memory Pattern

A typical application-level conversation-memory pattern looks like this:

User Message
     |
     v
Identify Useful Information
     |
     v
Store MemoryRecord
     |
     v
Later User Message
     |
     v
Get / Search Memory
     |
     v
Build Application or Model Request
     |
     v
Generate Response

For example, an application might decide that a user’s company is useful information to retain:

MemoryRecord(
    key="company",
    value="Acme",
    namespace="user-123",
)

Later, application code can retrieve it:

result = memory.get(
    "company",
    namespace="user-123",
)

The application can then use the retrieved value when preparing a model request or performing another application operation. This pattern gives the application control over what becomes long-term memory.

Conversation History vs Memory Records

Memory records should not automatically be treated as a complete conversation transcript. A memory record represents structured information such as:

key
value
namespace
metadata

For example:

MemoryRecord(
    key="company",
    value="Acme",
)

This is different from storing an entire sequence of:

User message
Assistant message
User message
Assistant message

Applications that require complete conversation transcripts should explicitly implement that storage pattern using the available memory primitives or another application-level persistence system. Memory is therefore best understood as a mechanism for storing useful information derived from conversations, rather than as an automatic replacement for a complete chat-history database.

Memory Records and Metadata

Conversation-related records can contain metadata that helps applications organize and retrieve information.

record = MemoryRecord(
    key="favorite_language",
    value="Python",
    namespace="user-123",
    metadata={
        "source": "conversation",
    },
    tags=["preference"],
)

Records can also contain information such as:

Importance
Access count
Expiration
Tags
Source
Relationships
Timestamps
Embeddings
Search score

This allows applications to build richer memory systems without changing the core storage API. For example, importance can be used by an application to distinguish information that should be retained from information that is less important.

Deleting Memory

A specific memory record can be deleted.

memory.delete(
    "favorite_language",
    namespace="user-123",
)

Applications can use this when information is no longer relevant or when a user requests that stored information be removed. Deletion is especially important for applications that provide user-controlled memory.

Clearing Memory

Memory can also be cleared for a namespace.

memory.clear(
    namespace="user-123",
)

This provides a simple way to remove the memory associated with a particular namespace. Applications can use namespace clearing when:

A conversation is reset
A user requests memory deletion
A tenant is removed
An application context is discarded
Temporary memory should be cleaned up

Checking for Memory

Applications can check whether a record exists.

exists = memory.exists(
    "favorite_language",
    namespace="user-123",
)

This can be useful before retrieving, updating, or conditionally creating a memory record.

Conversation Memory and Providers

Conversation-related memory uses the same provider architecture as the rest of BindAI’s memory system.

Application
    |
    v
Agent
    |
    v
Memory
    |
    v
MemoryProvider
    |
    v
Storage

The current memory package includes:

InMemoryProvider
SQLiteMemoryProvider
PostgreSQLMemoryProvider
VectorMemoryProvider
PineconeMemoryProvider
ChromaMemoryProvider

The application can therefore choose a storage implementation according to its persistence and retrieval requirements. For example, local development may use InMemoryProvider or SQLiteMemoryProvider, while a server application may use PostgreSQL or a managed vector provider.

Conversation Memory with Different Providers

The memory API remains consistent when changing providers. For example, an application can use in-memory storage:

from bindai import InMemoryProvider, Memory

memory = Memory(
    provider=InMemoryProvider(),
)

The same application can use SQLite:

from bindai import Memory, SQLiteMemoryProvider

memory = Memory(
    provider=SQLiteMemoryProvider("conversation.db"),
)

Or PostgreSQL:

from bindai import Memory, PostgreSQLMemoryProvider

memory = Memory(
    provider=PostgreSQLMemoryProvider("postgresql://postgres:postgres@localhost:5432/bindai"),
)

The application can continue using:

memory.set(record)

result = memory.get("company")

results = memory.search("customer preferences")

The underlying persistence and retrieval behavior is handled by the configured provider.

Conversation Memory in Workflows

Memory can also be used by application workflows. A workflow can store information under a namespace and later retrieve it.

Workflow Step
     |
     v
MemoryRecord
     |
     v
Memory
     |
     v
Later Workflow Step
     |
     +----> Memory.get()
     |
     +----> Memory.search()

For example, a workflow could store an identifier or preference during one step and retrieve it during a later step. The persistence of that information depends on the selected memory provider. This allows workflows and agents to share information through the same memory abstraction when the application chooses to do so.

Managing Long Conversations

Long conversations can produce large amounts of information. BindAI’s memory API provides primitives that applications can use to manage retained information, including:

Namespaces
Search
Deletion
Clearing
Metadata
Tags
Expiration
Importance
Relationships
Memory lifecycle management

Applications can build their own policies for deciding:

What information should be retained
What information should be discarded
How long information should remain available
Which information should be considered important
Which namespace a memory belongs to

A practical strategy is to retain useful facts, preferences, identifiers, and other durable information rather than storing every conversational detail as long-term memory.

Memory Lifecycle

Memory records contain lifecycle-related information that applications can use to manage retention. MemoryManager provides operations for working with memory lifecycle and importance, including:

Reinforcing records
Weakening records
Increasing or decreasing importance
Setting expiration
Clearing expiration
Touching records
Promoting records
Forgetting records
Checking promotion conditions
Checking forgetting conditions

For example:

from bindai import MemoryManager

manager = MemoryManager()

manager.set_expiration(
    record,
    days=30,
)

Applications can use these operations to implement retention policies for conversation-related information. For example, temporary preferences or session-specific information can be given a limited lifetime, while durable user information can be retained longer.

Conversation Memory and Agent Context

Conversation memory and the agent’s immediate execution context serve different purposes. A simplified distinction is:

Execution Context
    |
    +-- Information needed during the current execution

Conversation Memory
    |
    +-- Information intentionally retained across executions

Memory should therefore not be treated as a replacement for every form of runtime state. Applications can use execution state for information needed during one operation and memory for information that should persist beyond that operation.

Conversation Memory and Knowledge

Conversation memory is also different from knowledge or RAG.

Conversation Memory
    |
    +-- Information specific to application users,
        conversations, agents, or application state


Knowledge / RAG
    |
    +-- Documents and external information
        retrieved for model responses

For example:

A user’s preferred programming language may belong in memory.
A company’s product manual may belong in a knowledge base.
A document retrieved to answer a question belongs to the knowledge/RAG workflow.

Applications can use both systems together. An agent can have memory for user-specific information while also using knowledge retrieval for external documents.

User and Conversation Isolation

Applications serving multiple users should use clear namespace strategies. For example:

user-001
user-002
user-003

Or:

tenant-a/conversation-001
tenant-a/conversation-002
tenant-b/conversation-001

The exact namespace format is application-defined. A good namespace strategy should make it clear which application context owns each record and should prevent accidental cross-user retrieval. Namespace organization should be combined with application-level authorization. A namespace by itself should not be considered a complete security boundary.

Resource Management

Some memory providers own external resources such as database connections or other backend resources. Applications should close memory resources when they are no longer needed:

memory.close()

Memory can also be used as a context manager:

with Memory(
    provider=provider,
) as memory:
    result = memory.get("customer_name")

This is particularly useful for persistent providers that maintain external resources.

Privacy and Retention

Conversation memory can contain information derived from user interactions. Applications should therefore define appropriate retention and deletion policies. Useful practices include:

Store only information that provides application value.
Avoid storing unnecessary sensitive information.
Use namespaces to separate logical users or tenants.
Provide deletion mechanisms where appropriate.
Use expiration for temporary information.
Protect memory access with application-level authorization.
Keep provider credentials outside source code.
Treat memory storage as persistent application data when using persistent providers.

Memory providers provide storage capabilities; they do not automatically determine an application’s privacy policy or authorization model.

Best Practices

Use namespaces to isolate users, conversations, tenants, or other application contexts.
Store useful structured information rather than unnecessary conversational detail.
Use metadata and tags when records need additional organization.
Use search() when retrieval should be query-based.
Use get() when a specific key is known.
Use expiration for temporary information.
Use importance and lifecycle operations when retention policies require them.
Delete or clear information when it is no longer required.
Use persistent providers when memory must survive application restarts.
Use vector-oriented providers when semantic memory retrieval is appropriate.
Do not assume that a MemoryRecord is automatically a complete conversation transcript.
Do not use namespaces as the only authorization mechanism.
Protect stored memory as application data.
Close providers when they own external resources.

Summary

BindAI provides a flexible memory system that can be used to implement conversation-aware applications. The core primitives are:

Memory
  |
  +-- MemoryRecord
  |
  +-- get()
  |
  +-- set()
  |
  +-- search()
  |
  +-- delete()
  |
  +-- exists()
  |
  +-- clear()

Agents can attach memory through Agent.builder():

agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .memory(memory)
    .build()
)

Conversation memory is built around BindAI’s general memory abstraction rather than requiring the application to depend on a provider-specific storage API. The application decides what conversation information to store, how it is organized, how long it should remain available, and when it should be retrieved or removed. This makes conversation memory flexible enough to support simple user preferences, persistent application state, semantic memory, and more advanced agent workflows without forcing every application into a fixed conversation-history model.

Getting Started

Core

Tools

Memory

Knowledge

Connections

Automation

Workflows

Projects

Templates

Roadmap

API Reference

04.3 conversation memory

Conversation Memory

What is Conversation Memory?

Attaching Memory to an Agent

Storing Conversation Information

Reading Memory

Searching Memory

Namespaces

Conversation Memory Pattern

Conversation History vs Memory Records

Memory Records and Metadata

Deleting Memory

Clearing Memory

Checking for Memory

Conversation Memory and Providers

Conversation Memory with Different Providers

Conversation Memory in Workflows

Managing Long Conversations

Memory Lifecycle

Conversation Memory and Agent Context

Conversation Memory and Knowledge

User and Conversation Isolation

Resource Management

Privacy and Retention

Best Practices

Summary

​Conversation Memory

​What is Conversation Memory?

​Attaching Memory to an Agent

​Storing Conversation Information

​Reading Memory

​Searching Memory

​Namespaces

​Conversation Memory Pattern

​Conversation History vs Memory Records

​Memory Records and Metadata

​Deleting Memory

​Clearing Memory

​Checking for Memory

​Conversation Memory and Providers

​Conversation Memory with Different Providers

​Conversation Memory in Workflows

​Managing Long Conversations

​Memory Lifecycle

​Conversation Memory and Agent Context

​Conversation Memory and Knowledge

​User and Conversation Isolation

​Resource Management

​Privacy and Retention

​Best Practices

​Summary

Conversation Memory

What is Conversation Memory?

Attaching Memory to an Agent

Storing Conversation Information

Reading Memory

Searching Memory

Namespaces

Conversation Memory Pattern

Conversation History vs Memory Records

Memory Records and Metadata

Deleting Memory

Clearing Memory

Checking for Memory

Conversation Memory and Providers

Conversation Memory with Different Providers

Conversation Memory in Workflows

Managing Long Conversations

Memory Lifecycle

Conversation Memory and Agent Context

Conversation Memory and Knowledge

User and Conversation Isolation

Resource Management

Privacy and Retention

Best Practices

Summary