Build Persistent AI Agent Memory with AIrecall

What Is AIrecall?

AIrecall is a drop-in long-term memory layer for AI agents. It preserves useful information across sessions instead of forcing an agent to rely only on its current context window. The project combines a Python SDK, a Go memory server, SQLite storage, and an in-process vector index.

AIrecall is designed to keep prompts focused. Rather than inserting an entire interaction history into every request, your agent can retrieve the memories most relevant to the current turn.

Core Memory Types and Features

• Episodic memory: Stores events in order, including conversations, actions, and outcomes.
• Semantic memory: Preserves durable facts and preferences distilled from past episodes.
• Hybrid retrieval: Combines keyword matching with vector similarity across episodic and semantic memory.
• Automatic summarization: Periodically compresses older episodes and extracts durable facts instead of simply deleting history.
• Persistent local storage: Uses SQLite with an in-process vector index.
• Flexible operation: The memory server can run locally or as a sidecar.

How AIrecall Works

On each turn, the Python SDK sends the current query to AIrecall Core through a local call or gRPC. The core searches episodic and semantic memory using keyword and vector similarity, ranks the results, and returns the top relevant memories for injection into the agent's prompt.

In the background, a summarizer processes older episodes. It extracts durable information into semantic memory and compacts the remaining history, helping long-running agents retain useful knowledge without continually expanding their active context.

Installation and Setup

Install the Python SDK

Install the package imported by your Python agent:

pip install airecall-sdk

Initialize Local Storage

Scaffold a local SQLite-backed memory store with the command-line interface:

airecall init

This setup lets you begin storing and recalling memories immediately without requiring a separate service.

Install or Run the Memory Server

If you want the core memory server available locally or as a sidecar, install the server extra:

pip install airecall-sdk[server]

You can then run the server as a standalone process:

airecall serve

The SDK itself is standard-library-only. The server uses one pure-Go dependency, according to the project README.

Basic Usage

Create a Memory Instance

Import Memory and assign an identifier to the agent:

from airecall import Memory

memory = Memory(agent_id="support-bot")

The agent_id identifies the agent whose memories are being stored and retrieved. Use the same identifier when you want later sessions to access the same memory collection.

Store an Episodic Memory

Use remember to record something that happened during an interaction:

memory.remember(
    "User asked about refund policy for order ORD-9921, told 30-day window applies."
)

This is an episodic memory because it records a specific event and its outcome.

Recall Relevant Context

In a later session, call recall with the current question:

context = memory.recall(
    "what did we tell this user about refunds?"
)

AIrecall searches its stored memories and returns the relevant episode ranked by relevance. Your application can then add that returned context to the prompt sent to the model.

Store a Durable Fact

Information that should remain useful beyond one event can be promoted explicitly with remember_fact:

memory.remember_fact(
    key="preferred_contact",
    value="email, not phone"
)

This creates semantic memory for a stable preference rather than recording only another chronological episode.

Using the LangChain Adapter

AIrecall includes a LangChain adapter named MemoryRetriever. Wrap an existing Memory instance to create the retriever:

from airecall import Memory
from airecall.adapters.langchain import MemoryRetriever

memory = Memory(agent_id="support-bot")
retriever = MemoryRetriever(memory)

The README demonstrates constructing the adapter but does not specify further chain or retriever configuration. Follow the adapter's current API when integrating the resulting object into a larger LangChain application.

Practical Integration Pattern

1. Create a Memory instance for the agent.
2. Before generating a response, call recall with the user's current query.
3. Insert the returned relevant memories into the model prompt as supporting context.
4. After the interaction, call remember to save the important event, action, or outcome.
5. Use remember_fact when your application identifies a durable preference or fact that should be retained explicitly.

This pattern avoids placing the complete history into every prompt while still giving the agent access to prior decisions and user preferences when they matter.

Advanced Tips

Separate Events from Durable Knowledge

Use episodic memory for what happened during a particular interaction. Use semantic memory for stable facts and preferences. For example, a refund discussion belongs in an episode, while a user's preference for email communication is a durable fact.

Keep Agent Identifiers Consistent

Choose a stable agent_id for sessions that need to share memory. Changing the identifier creates a different memory scope from the application's perspective.

Choose the Appropriate Deployment Mode

For a simple local workflow, initialize the SQLite-backed store with airecall init. For an architecture that needs a dedicated memory process, install the server extra and run airecall serve locally or as a sidecar.

Allow the Index to Warm Up

If the first query raises RecallTimeout, the vector index may still be warming. Retry after the health endpoint reports status: ready.

Use a Reliable Storage Path

If memories appear to be missing after a restart, inspect the storage.backend path. A relative path is resolved against the working directory of the server process, so launching the server from a different directory can point it at another store. Use a consistent working directory or storage path.

Conclusion

AIrecall gives AI agents persistent episodic and semantic memory without requiring every old interaction to remain in the prompt. With a small Python API, SQLite-backed storage, hybrid retrieval, and automatic summarization, it provides a practical way to preserve relevant context across sessions. Start with airecall init, record episodes with remember, retrieve them with recall, and save lasting knowledge with remember_fact.