Memory & Storage

Memory is a core component of Cleo’s architecture, enabling agents to recall past interactions, retain factual context, and adapt over time. It transforms agents from reactive tools into stateful collaborators. This section explains how memory works, how to configure it, and how to implement custom storage backends.

---

Why Memory Matters

Stateless agents reset after every task. This limits their ability to:

• Maintain long-term conversations

• Refer to earlier instructions or facts

• Improve over time

With memory enabled, Cleo agents can:

• Log interactions across sessions

• Reference previous user intents

• Develop a behavioral profile (when designed to do so)

Memory is opt-in and fully modular.

---

Memory Interface

All memory modules implement the same interface:

pythonCopyEditclass MemoryInterface:
    def add_entry(self, input_text: str, output_text: str) -> None: ...
    def retrieve(self, query: str, limit: int = 5) -> List[str]: ...
    def clear(self) -> None: ...

This abstraction allows agents to switch memory backends without modifying their logic.

---

Available Memory Backends

1. FAISS (Vector-Based Memory)

FAISS stores past interactions as dense vector embeddings. It allows fast similarity search and contextual retrieval.

Install:

bashCopyEditpip install faiss-cpu

Config:

pythonCopyEditfrom core.memory import FaissMemory

memory = FaissMemory(index_path="data/memory.index")

2. ChromaDB

An alternative vector memory backend with a built-in REST API and persistent storage.

Install:

bashCopyEditpip install chromadb

Config:

pythonCopyEditfrom core.memory import ChromaMemory

memory = ChromaMemory(collection="cleo-agent")

3. File-Based Memory (Lightweight)

Stores logs and interactions in plain JSON files. Best for debugging or development.

pythonCopyEditfrom core.memory import JSONMemory

memory = JSONMemory(filepath="logs/atlas_memory.json")

---

Integration with Agents

To enable memory for an agent, set memory: true in the config or pass a memory object when initializing the agent.

pythonCopyEditagent = Agent(
    name="Atlas",
    persona="Data Analyst",
    tools=["WebScraper", "Summarizer"],
    memory=FaissMemory(index_path="data/atlas.index")
)

In code, every task execution will now add to memory:

pythonCopyEditresponse = agent.run_task("What are the trends in Q1 reports?")
agent.memory.add_entry("Q1 trends?", response)

Agents will also automatically query memory for relevant context before each task (configurable).

---

Configuration via .env

You can set the memory backend and location via environment variables for portability:

iniCopyEditCLEO_MEMORY_BACKEND=faiss
CLEO_MEMORY_PATH=data/cleo.index

In core/memory/loader.py:

pythonCopyEditbackend = os.getenv("CLEO_MEMORY_BACKEND", "json")
path = os.getenv("CLEO_MEMORY_PATH", "logs/default.json")

---

Clearing Memory

Each backend supports a .clear() method to wipe stored context.

pythonCopyEditagent.memory.clear()

Use this cautiously, as it permanently removes interaction history.

---

Future Directions

Planned upgrades include:

• Support for hybrid memory (vector + symbolic)

• Context weighting based on usage frequency

• Agent-shared memory across multiple instances

• TTL-based memory decay

Memory is not just a log — it's a core part of long-term agent intelligence. Tuning it well can drastically improve performance on multi-step or evolving tasks.