Memory Overview

BindAI Memory provides a provider-based system for storing, retrieving, searching, and managing application memory. Memory is separate from ordinary conversation history. Conversation state belongs to an agent’s conversational execution, while Memory provides an explicit storage and retrieval layer for records that can persist beyond an individual interaction. The same Memory abstraction can work with different storage implementations, allowing applications to change providers without changing the basic memory API.

What is Memory?

A Memory object provides access to stored MemoryRecord objects. A basic example is:

from bindai import Memory, MemoryRecord

memory = Memory()

record = MemoryRecord(
    key="user_name",
    value="Alice",
)

memory.set(record)

result = memory.get("user_name")

print(result.value)

A memory record can contain a key and value together with additional information such as:

Namespace
Memory type
Metadata
Importance
Access information
Expiration
Embeddings
Tags
Source information
Relationships
Timestamps

Memory Architecture

BindAI separates the memory interface from its storage implementation. Conceptually:

Application
     |
     v
  Memory
     |
     v
MemoryProvider
     |
     +------------------+
     |        |         |
     v        v         v
 In-Memory  SQLite   Vector / Database

The application interacts primarily with Memory. The configured MemoryProvider determines how records are stored and retrieved.

Attaching Memory to an Agent

Memory can be explicitly configured on an agent. Using the current builder API:

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()
)

Memory can also be attached through the agent’s memory configuration API where supported:

agent.use_memory(memory)

Memory is therefore an explicit agent capability rather than something tied to a particular model provider.

Memory Providers

BindAI currently provides multiple memory storage implementations. The current provider set includes:

InMemoryProvider
SQLiteMemoryProvider
PostgreSQLMemoryProvider
VectorMemoryProvider
PineconeMemoryProvider
ChromaMemoryProvider

The common provider abstraction is represented by MemoryProvider. The purpose of the provider abstraction is to allow the same memory operations to work across different storage systems.

In-Memory Storage

InMemoryProvider stores records in the running Python process.

from bindai import InMemoryProvider, Memory

memory = Memory(
    provider=InMemoryProvider(),
)

In-memory storage is useful when:

Persistence is not required.
Tests need isolated storage.
An application only needs memory for its current process.
Fast local storage is more important than durability.

The records are lost when the process and its in-memory state are discarded.

SQLite Storage

SQLiteMemoryProvider provides file-backed memory storage using SQLite.

from bindai import Memory, SQLiteMemoryProvider

provider = SQLiteMemoryProvider(
    "memory.db",
)

memory = Memory(
    provider=provider,
)

SQLite is useful for applications that need local persistence without running a separate database service. Typical use cases include:

Local applications
Development environments
Prototypes
Small deployments
Persistent test environments

PostgreSQL Storage

BindAI also provides PostgreSQLMemoryProvider. PostgreSQL is appropriate when memory needs to be stored in a shared relational database environment. A provider can be configured for a PostgreSQL-backed application using the provider’s connection configuration. Conceptually:

from bindai import Memory, PostgreSQLMemoryProvider

provider = PostgreSQLMemoryProvider(...)

memory = Memory(
    provider=provider,
)

PostgreSQL is particularly useful when multiple application processes need access to the same persistent memory store. Connection details should be managed securely through application configuration or environment variables rather than being hard-coded into source code.

Vector Memory

VectorMemoryProvider provides memory operations that can work with vector representations.

from bindai import Memory, VectorMemoryProvider

memory = Memory(
    provider=VectorMemoryProvider(),
)

Vector memory is useful when applications need similarity-oriented memory retrieval in addition to ordinary record storage. The exact search behavior depends on the configured vector-memory implementation and its embedding configuration.

Pinecone Memory

BindAI includes PineconeMemoryProvider for Pinecone-backed memory storage. Pinecone is useful when memory needs to be stored in a managed vector database. Conceptually:

from bindai import Memory, PineconeMemoryProvider

provider = PineconeMemoryProvider(...)

memory = Memory(
    provider=provider,
)

Pinecone configuration should be supplied through secure application configuration. Vector dimensions and embedding configuration must be compatible with the Pinecone index being used.

Chroma Memory

BindAI also provides ChromaMemoryProvider. Chroma can be used for vector-oriented memory storage in applications that want a dedicated vector database implementation. Conceptually:

from bindai import Memory, ChromaMemoryProvider

provider = ChromaMemoryProvider(...)

memory = Memory(
    provider=provider,
)

The appropriate configuration depends on whether Chroma is being used locally or through a configured service.

Choosing a Provider

The appropriate memory provider depends on the application’s requirements.

Provider	Typical use
`InMemoryProvider`	Temporary state and tests
`SQLiteMemoryProvider`	Local persistent applications
`PostgreSQLMemoryProvider`	Shared relational persistence
`VectorMemoryProvider`	Vector-oriented memory
`PineconeMemoryProvider`	Managed vector storage
`ChromaMemoryProvider`	Vector storage and retrieval

Provider choice should consider:

Persistence requirements
Deployment environment
Search requirements
Scale
Operational complexity
Existing infrastructure

Memory Records

The fundamental unit of memory is MemoryRecord. A record requires:

key
value

It also supports additional fields such as:

namespace
type
metadata
importance
access_count
last_accessed
expires_at
embedding
score
tags
source
relationships
related_keys
created_at
updated_at

For example:

from bindai import MemoryRecord

record = MemoryRecord(
    key="user_name",
    value="Alice",
    namespace="users",
)

A record can therefore represent both simple key-value memory and richer application memory.

Namespaces

Memory records can be organized into namespaces.

record = MemoryRecord(
    key="user_name",
    value="Alice",
    namespace="users",
)

Memory operations can specify the namespace:

result = memory.get(
    "user_name",
    namespace="users",
)

Namespaces help separate logically different collections of memory. For example:

users
preferences
sessions
projects

The exact namespace strategy is application-specific.

Memory Types

Memory records have a memory type. The default type is long_term. For example:

record = MemoryRecord(
    key="user_name",
    value="Alice",
    type="long_term",
)

BindAI exposes MemoryType for representing memory categories. Applications can use memory types to distinguish different classes of stored information where appropriate.

Storing Memory

Use set() to store a MemoryRecord.

record = MemoryRecord(
    key="favorite_color",
    value="blue",
)

result = memory.set(record)

The operation returns a MemoryResult. The provider determines how the record is persisted.

Retrieving Memory

Use get() to retrieve a record by key.

result = memory.get(
    "favorite_color",
)

print(result.value)

A namespace can also be specified:

result = memory.get(
    "favorite_color",
    namespace="users",
)

Applications should handle the result according to the configured memory provider and result state.

Searching Memory

Memory supports search operations. A basic search is:

results = memory.search(
    "favorite color",
)

Additional parameters can be supplied:

results = memory.search(
    query="favorite color",
    namespace="users",
    limit=10,
)

Metadata can also be supplied where supported:

results = memory.search(
    query="favorite color",
    metadata={
        "source": "profile",
    },
)

Search behavior depends on the configured provider. In particular, vector-backed providers can use embeddings and similarity-oriented retrieval, while other providers may use different search mechanisms.

Checking for Memory

Use exists() to determine whether a record exists.

exists = memory.exists(
    "favorite_color",
)

print(exists)

A namespace can also be specified:

exists = memory.exists(
    "favorite_color",
    namespace="users",
)

This is useful when an application needs to check for a record before creating or updating it.

Deleting Memory

Use delete() to remove a specific record.

result = memory.delete(
    "favorite_color",
)

A namespace can be specified when necessary:

result = memory.delete(
    "favorite_color",
    namespace="users",
)

Deletion behavior ultimately depends on the configured provider.

Clearing Memory

Use clear() to remove records from a logical memory collection.

result = memory.clear(
    namespace="users",
)

This can be useful for resetting a namespace or clearing test data. Use clearing operations carefully in production applications because they can remove multiple records at once.

Memory Results

Memory operations use MemoryResult for result handling. Conceptually:

Memory Operation
       |
       v
 MemoryResult

The memory result abstraction is separate from:

AgentResult
ToolResult

Do not assume that the fields of one result type are identical to another.

Memory Lifecycle Management

BindAI includes MemoryManager for managing memory-record lifecycle information.

from bindai import MemoryManager

manager = MemoryManager()

The manager provides lifecycle operations including:

touch()
reinforce()
weaken()
decay()
promote()
forget()
should_promote()
should_forget()
set_expiration()
clear_expiration()

These operations allow applications to implement memory lifecycle policies without putting all lifecycle logic directly into storage providers.

Importance

Memory records contain an importance value. For example:

record = MemoryRecord(
    key="important_fact",
    value="...",
    importance=0.9,
)

The memory manager can adjust the importance of a record. To reinforce a memory:

manager.reinforce(record)

To weaken it:

manager.weaken(record)

A decay operation can also be applied:

manager.decay(record)

The exact lifecycle policy is determined by the memory-management implementation and application requirements.

Promotion and Forgetting

The memory manager can determine whether a record should be promoted or forgotten. For example:

if manager.should_promote(record):
    manager.promote(record)

Similarly:

if manager.should_forget(record):
    manager.forget(record)

These operations provide a foundation for memory lifecycle policies. Applications can use them to decide which memories should become more persistent or which should eventually be removed.

Expiration

Memory records support expiration. For example:

manager.set_expiration(
    record,
    days=30,
)

Expiration can later be removed:

manager.clear_expiration(
    record,
)

Records also expose an expires_at field. Expiration is useful for information that should only remain relevant for a limited period. Examples include:

Temporary preferences
Session-related information
Short-lived application state
Time-sensitive records

Access Tracking

Memory records track access information. Relevant fields include:

record.access_count
record.last_accessed

A record can be touched explicitly:

record.touch()

The memory manager also provides:

manager.touch(record)

This allows applications to track how frequently memories are accessed and when they were last used. Access information can be useful when designing promotion, decay, or forgetting strategies.

Relationships

Memory records can represent relationships with other records. For example:

record.add_relationship(
    "related_to",
    "other_record",
)

Relationships can be retrieved:

related = record.get_relationships(
    "related_to",
)

Records also provide convenience operations for managing relationships. Relationships are useful when memory records represent connected application concepts rather than isolated values.

Metadata

Memory records support arbitrary metadata. For example:

record = MemoryRecord(
    key="user_name",
    value="Alice",
    metadata={
        "source": "profile",
        "confidence": 0.95,
    },
)

Metadata can provide additional information about where a memory came from or how it should be interpreted. Metadata can also participate in search filtering where supported by the configured provider.

Embeddings

MemoryRecord supports an optional embedding field. For example:

record = MemoryRecord(
    key="document",
    value="BindAI is an agent framework.",
    embedding=[0.12, 0.45, 0.78],
)

Vector-oriented providers can use embeddings as part of similarity-based search. Embedding dimensions must be compatible with the vector storage and embedding configuration used by the application.

Serialization

Memory records can be converted to dictionaries.

data = record.to_dict()

They can also be reconstructed:

record = MemoryRecord.from_dict(data)

This makes records easier to:

Serialize
Inspect
Test
Store in other systems
Move between application boundaries

Serialization is particularly useful when memory records need to cross process or storage boundaries.

Memory Registry

BindAI provides a MemoryRegistry abstraction for registering and resolving memory providers. Conceptually, a registry maps provider names to provider implementations:

Provider Name
     |
     v
MemoryRegistry
     |
     v
MemoryProvider

A custom provider can be registered by name when using the registry API:

registry.register(
    "custom",
    CustomMemoryProvider,
)

It can then be resolved by name:

provider = registry.provider(
    "custom",
)

Available providers can be inspected through the registry API. Provider registration is useful when applications need to extend the supported memory implementations with their own provider types.

Memory and Execution Context

Memory and execution context represent different kinds of state.

Memory	Execution Context
Stores memory records	Carries runtime execution state
Can be backed by a persistent provider	Belongs to an execution
Supports retrieval and search	Coordinates information during execution
Can outlive an individual interaction	Is associated with the current execution

Use Memory for information that belongs in the application’s memory system. Use execution context for temporary information needed while an operation is running. They should not be treated as interchangeable storage mechanisms.

Memory vs Conversation History

Memory is also different from conversation history. Conversation history represents messages exchanged during a conversational interaction. Memory stores explicit records that can be retrieved independently. Conceptually:

Conversation
    |
    +-- User messages
    +-- Assistant messages
    +-- Tool interactions


Memory
    |
    +-- Records
    +-- Metadata
    +-- Tags
    +-- Relationships

An agent can use both conversation history and memory.

Memory vs Knowledge

Memory and Knowledge are separate BindAI concepts. Memory stores application memory records. Knowledge is primarily concerned with external information ingestion and retrieval. For example:

Memory
  |
  +-- User preferences
  +-- Long-term facts
  +-- Application state


Knowledge
  |
  +-- Documents
  +-- Chunks
  +-- Embeddings
  +-- Retrieved information

An agent can use both systems in the same application.

Memory with Agents

Memory can be combined with the other major agent capabilities. For example:

                    Agent
                      |
        +-------------+-------------+
        |             |             |
        v             v             v
     Memory       Knowledge       Tools
        |             |             |
        +-------------+-------------+
                      |
                      v
                  Execution

Memory provides stored application information. Knowledge provides retrieved external information. Tools provide executable capabilities. The agent can coordinate these capabilities during execution.

Memory with Workflows

Memory can also be used alongside workflows. A workflow can read memory, perform operations, and write updated records. Conceptually:

Workflow
    |
    v
Read Memory
    |
    v
Process Data
    |
    v
Write Memory

This is useful for applications where workflow execution needs to persist information between runs.

Memory with Multi-Agent Systems

Multiple agents can use memory as part of a larger application architecture. For example:

                 Team
                  |
        +---------+---------+
        |         |         |
        v         v         v
    Research   Support   Operations
        |         |         |
        +---------+---------+
                  |
                  v
                Memory

The exact memory-sharing model should be chosen deliberately. Applications should consider whether agents should share:

A common namespace
Separate namespaces
Separate memory providers
Different record types
Different authorization boundaries

Shared memory should not automatically imply unrestricted access between agents.

Resource Management

Memory supports closing its underlying provider.

memory.close()

Memory can also be used as a context manager:

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

This is useful for providers that own resources such as database connections or other external resources. Applications should close memory providers when they are no longer needed.

Provider Selection Guidelines

A practical provider-selection approach is:

Use in-memory storage when

Persistence is unnecessary.
You are writing tests.
The application is short-lived.
Local simplicity is the priority.

Use SQLite when

Persistent local storage is required.
A separate database service is unnecessary.
The application is relatively small.

Use PostgreSQL when

Multiple processes need shared persistent memory.
The application already uses PostgreSQL.
Relational database infrastructure is available.

Use vector-oriented providers when

Similarity search is important.
Memory needs semantic retrieval.
The application has an embedding pipeline.
Vector storage infrastructure is appropriate.

Best Practices

Choose a memory provider appropriate for the application’s persistence and retrieval requirements.
Use namespaces to separate logical memory collections.
Use MemoryRecord as the standard memory representation.
Add metadata when records need additional context.
Use tags to classify records.
Use relationships when records need explicit links.
Use expiration for temporary information.
Use MemoryManager for lifecycle operations.
Track access when memory lifecycle depends on usage.
Use SQLite when local file-backed persistence is appropriate.
Use PostgreSQL for shared relational persistence.
Use vector providers when semantic similarity is required.
Keep embedding configuration compatible with the selected vector store.
Protect memory operations with appropriate authorization.
Do not treat memory as an implicit execution-context store.
Close providers when they own external resources.
Test memory behavior independently from model-provider behavior.

Complete Example

The following example uses the current Agent.builder() API:

from bindai import Agent, Memory, MemoryRecord, SQLiteMemoryProvider


provider = SQLiteMemoryProvider(
    "assistant-memory.db",
)

memory = Memory(
    provider=provider,
)

memory.set(
    MemoryRecord(
        key="user_name",
        value="Alice",
        namespace="users",
    )
)

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

result = agent.run("What do you remember about me?")

if result.success:
    print(result.output)
else:
    print(result.error)

memory.close()

The example separates persistent memory from the agent itself. The memory provider controls storage. The Memory abstraction provides access to the records. The agent receives the memory capability through its configuration.

Summary

BindAI Memory is a provider-based system for storing and retrieving MemoryRecord objects. The current implementation includes:

Memory
MemoryProvider
InMemoryProvider
SQLiteMemoryProvider
PostgreSQLMemoryProvider
VectorMemoryProvider
PineconeMemoryProvider
ChromaMemoryProvider
MemoryRecord
MemoryResult
MemoryManager
MemoryRegistry

Memory supports:

Key-based retrieval
Search
Namespaces
Memory types
Metadata
Tags
Relationships
Embeddings
Expiration
Access tracking
Lifecycle management
Serialization

Agents can explicitly configure memory through the current builder API:

agent = Agent.builder().memory(memory).build()

Memory is deliberately separated from conversation history, execution context, tools, and knowledge retrieval. This separation allows applications to choose an appropriate storage provider while keeping their application-level memory logic consistent.

​Memory Overview

​What is Memory?

​Memory Architecture

​Attaching Memory to an Agent

​Memory Providers

​In-Memory Storage

​SQLite Storage

​PostgreSQL Storage

​Vector Memory

​Pinecone Memory

​Chroma Memory

​Choosing a Provider

​Memory Records

​Namespaces

​Memory Types

​Storing Memory

​Retrieving Memory

​Searching Memory

​Checking for Memory

​Deleting Memory

​Clearing Memory

​Memory Results

​Memory Lifecycle Management

​Importance

​Promotion and Forgetting

​Expiration

​Access Tracking

​Tags

​Relationships

​Metadata

​Embeddings

​Serialization

​Memory Registry

​Memory and Execution Context

​Memory vs Conversation History

​Memory vs Knowledge

​Memory with Agents

​Memory with Workflows

​Memory with Multi-Agent Systems

​Resource Management

​Provider Selection Guidelines

​Use in-memory storage when

​Use SQLite when

​Use PostgreSQL when

​Use vector-oriented providers when

​Best Practices

​Complete Example

​Summary