# Backends for Semantic Memory Retrieval and Structured Storage in the `mem` Extra

> Explore backends for semantic memory retrieval and structured storage in the mem extra. Discover mem0ai[nlp] for vector search and memobase for persistent data.

- Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book)
- Tags: api-reference
- Published: 2026-08-23

---

**The `mem` extra in bojieli/ai-agent-book configures two distinct backends: `mem0ai[nlp]` for semantic vector search and `memobase` for persistent structured storage.**

The `mem` extra declared in [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml) equips AI agents with both episodic memory retrieval and profile-based structured storage capabilities. According to the bojieli/ai-agent-book source code, these backends are wired through optional dependencies that install high-performance NLP utilities alongside a lightweight key-value store. Together, they enable retrieval-augmented generation workflows and persistent user state management.

## The `mem` Extra Architecture

The dual-backend architecture separates concerns between **semantic memory retrieval** (vector similarity search) and **structured storage** (schema-flexible persistence). This distinction appears in [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml) lines 13–15, where the `mem` extra lists both packages as co-dependencies.

```toml
mem = [
    "mem0ai[nlp]>=2.0,<3",
    "memobase>=0.0.27; python_version >= '3.11'",
]

```

The `mem0ai[nlp]` package provides embedding generation and relevance ranking, while `memobase` offers fast lookups for JSON-like records. Both versions are locked in `uv.lock`—specifically lines 3901–3916 for `mem0ai` and lines 3925–3935 for `memobase`—ensuring reproducible builds across environments.

## Semantic Retrieval with `mem0ai[nlp]`

The `mem0ai` backend acts as a high-performance semantic vector store for retrieval-augmented generation. When installed with the `[nlp]` extra, it pulls in Sentence-Transformers and related utilities for automatic text embedding.

Initialize the vector store and ingest documents as shown in the repository's reference patterns:

```python
from mem0ai import Mem0AI

# Initialise the vector store (the NLP extra pulls in Sentence‑Transformers)

mem = Mem0AI(
    api_key="YOUR_MEM0AI_KEY",   # placeholder – actual key is supplied at runtime

    collection="my_documents"
)

# Add documents (text will be automatically embedded)

mem.add_documents([
    {"id": "doc1", "text": "The quick brown fox jumps over the lazy dog."},
    {"id": "doc2", "text": "Artificial intelligence drives modern research."},
])

# Retrieve the most relevant chunk for a query

results = mem.search("What does a fox do?", top_k=2)
print(results)   # → list of matching documents with similarity scores

```

The `search()` method returns ranked results with similarity scores, enabling agents to inject relevant context into LLM prompts.

## Structured Storage with `memobase`

For persistent, schema-flexible data, the `memobase` backend provides a lightweight key-value store. It writes to `~/.memobase` by default and supports arbitrary JSON structures for user profiles, session states, or agent configuration.

Instantiate the store and manage structured records as follows:

```python
from memobase import Store

# Create a persistent JSON store (writes to ~/.memobase by default)

store = Store(namespace="user_profiles")

# Write a structured record

store.set("user:1234", {
    "name": "Alice",
    "preferences": {"language": "en", "theme": "dark"},
    "last_login": "2026-08-23T12:34:56Z"
})

# Retrieve the same record later

profile = store.get("user:1234")
print(profile["preferences"]["language"])   # → "en"

```

The `Store` class offers fast lookups by primary key, making it suitable for latency-sensitive agent loops that require immediate access to user context.

## Dependency Locking and Reproducibility

Exact versions and source URLs for both backends are pinned in `uv.lock`. This lockfile records `mem0ai` metadata at lines 3901–3916 and `memobase` at lines 3925–3935, preventing drift across deployments. The constraints also appear in [`chapter3/mem0/requirements.txt`](https://github.com/bojieli/ai-agent-book/blob/main/chapter3/mem0/requirements.txt), demonstrating how chapter-specific examples share the same dependency specifications as the core package.

## Summary

- The `mem` extra installs **`mem0ai[nlp]`** for semantic vector search and **`memobase`** for structured key-value storage.
- Dependency declarations live in [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml) lines 13–15, with version locks enforced in `uv.lock`.
- `mem0ai[nlp]` enables retrieval-augmented generation through automatic embedding and similarity ranking.
- `memobase` provides persistent JSON storage with fast primary-key lookups for agent state and user profiles.
- Both backends require Python 3.11+ for the `memobase` component, as specified by the environment marker in the dependency specification.

## Frequently Asked Questions

### What is the difference between mem0ai and memobase in the `mem` extra?

**mem0ai[nlp]** is a semantic vector store designed for retrieval-augmented generation; it embeds text and performs similarity search. **memobase** is a structured key-value store for persistent JSON data like user profiles or session state. They serve complementary roles—semantic retrieval versus structured persistence.

### How do I install the backends for semantic memory retrieval and structured storage?

Install both backends by running `pip install bojieli-ai-agent-book[mem]` or `pip install .[mem]` from the repository root. This reads the `mem` extra definition in [`pyproject.toml`](https://github.com/bojieli/ai-agent-book/blob/main/pyproject.toml) and resolves `mem0ai[nlp]>=2.0,<3` alongside `memobase>=0.0.27` for Python 3.11+ environments.

### Where are the exact backend versions locked in the repository?

Concrete versions and source URLs are locked in `uv.lock`: lines 3901–3916 for `mem0ai` and lines 3925–3935 for `memobase`. This ensures that every installation uses identical dependency trees, preventing version drift that could affect embedding models or storage formats.

### Can I use these backends outside of the AI Agent Book examples?

Yes. Both `mem0ai` and `memobase` are standalone packages importable in any Python project. The `mem` extra simply bundles them with compatible version constraints, but you can initialize `Mem0AI` or `Store` independently in custom agent architectures.