fabricatio-memory

MIT

Memory management for Fabricatio agents — persistent, searchable long-term memory backed by a Tantivy full-text index in Rust.

Installation

pip install fabricatio[memory]
# or
uv pip install fabricatio[memory]

For a full installation including all optional packages:

pip install fabricatio[full]
# or
uv pip install fabricatio[full]

Overview

fabricatio-memory provides a persistent memory system for LLM agents. It combines a Rust-backed Tantivy search engine with Python-level agent capabilities to record, search, and recall information across sessions.

Memories are stored in named stores (independent Tantivy indexes). Each memory carries content, an importance score, tags, and is tracked for access frequency and recency — enabling relevance-boosted retrieval.

The Python layer wraps recording and recall through LLM integration: raw text is structured into a Note by the agent's LLM before storage, and recall queries return LLM-summarized results from the top matching memories.

Architecture

Python (capabilities)          Rust (storage engine)
┌─────────────────────┐       ┌──────────────────────┐
│ Remember            │──▶    │ MemoryStore          │
│  .record(raw)       │       │  .add_memory()       │
│  .recall(query)     │       │  .search_memories()  │
│ SelectiveRemember   │       │  .get_memory()       │
│  .sremember(…)      │       │  .update_memory()    │
└─────────────────────┘       │  .stats()            │
                              └──────────────────────┘
                                        │
                              ┌──────────────────────┐
                              │ MemoryService        │
                              │  .get_store(name)    │
                              │  .list_stores()      │
                              └──────────────────────┘

Key APIs

Rust backend (fabricatio_memory.rust)

MemoryStore methods:

All mutation methods accept an optional write=False parameter; when False, changes are buffered for performance. Call write() to commit.

Python capabilities (fabricatio_memory.capabilities)

Models (fabricatio_memory.models)

Configuration (fabricatio_memory.config)

MemoryConfig controls template paths, store root directory (~/.fabricatio-memory by default), writer buffer size (50 MB default), and index cache size (10 stores).

Service singleton (fabricatio_memory.inited_memory_service)

get_memory_service() returns a lazily-initialized MemoryService using the global MemoryConfig.

Usage

Direct store operations

from fabricatio_memory.rust import MemoryService

service = MemoryService("/path/to/store_root")
store = service.get_store("my_agent")

# Store a memory
mem_id = store.add_memory("User prefers dark mode", importance=70, tags=["preferences", "ui"])

# Search
results = store.search_memories("dark mode", top_k=5, boost_recent=True)
for mem in results:
    print(f"{mem.uuid}: {mem.content} (importance={mem.importance})")

# Stats
stats = store.stats()
print(stats.display())
# total: 42, avg importance: 55.3, avg access: 3.1, avg age: 12.4d

# Commit buffered writes
store.write()

Agent capability (LLM-integrated)

from fabricatio_memory.capabilities.remember import Remember
from fabricatio_memory.inited_memory_service import get_memory_service

class MyAgent(Remember, SomeBaseAgent):
    ...

agent = MyAgent(memory_store_name="agent_memories")
agent.mount_memory_store()

# Record — LLM extracts structured Note from raw text
note = await agent.record("The user said their name is Alice and they work at Acme Corp.")
# note.content = "User name is Alice, works at Acme Corp."
# note.importance = 60
# note.tags = ["user_info", "employment"]

# Recall — semantic search + LLM summarization
summary = await agent.recall("What do we know about Alice?")
# summary = "Alice works at Acme Corp. She prefers dark mode."

Selective memory

from fabricatio_memory.capabilities.selective_remember import SelectiveRemember

class MyAgent(SelectiveRemember, SomeBaseAgent):
    ...

# Only record if the agent judges it's worth remembering
note = await agent.sremember(
    prerequisite="Only remember if this contains personal user information",
    raw="The weather is sunny today."
)
# note is None — weather isn't personal info

Configuration

All options below are read through the fabricatio configuration chain (see the Configuration Guide). Set them under the [ext.memory] table in fabricatio.toml, equivalently under [tool.fabricatio.ext.memory] in pyproject.toml, or via FABRICATIO_EXT__MEMORY__<FIELD_UPPER> environment variables.

[ext.memory]
memory_store_root = "~/.fabricatio-memory"

Access at runtime: from fabricatio_memory.config import memory_config.

Dependencies

• fabricatio-core — core interfaces, configuration, template management
• Optional: fabricatio-judge — required by SelectiveRemember for conditional recording

License

MIT — see LICENSE