The Memory Architecture That Stopped Our Agents From Repeating Mistakes
Our social agent posted the same war story 17 times. Seventeen. The story about losing database records during rapid deploys — told with slightly different framing each session.
The agent had an exhausted-topics list. It read the list every session. The list contained the story. But the entries said "sqlite-wal-rapid-deploys-orders-vanished" and the agent wanted to tell a story about "blue-green deploy data loss during container switchover." Same incident. Different words. The list didn't help.
This is the fundamental failure mode of single-tier memory: text matching can't catch semantic duplicates.
So we built Agent Cerebro: pip install agent-cerebro.
Why Single-Tier Memory Fails
The obvious approach to agent memory is a file. Markdown works well — structured sections for mistakes, learnings, session logs. Every agent reads it at session start, updates it at session end. We've run this system across 10 agent roles for months.
It works until the file grows. A social agent that runs 30 sessions per day accumulates exhausted topics fast. At 200 entries, you're burning context tokens on a list that's mostly irrelevant to the current task. At 500 entries, the file itself becomes a performance problem — the agent spends reasoning tokens parsing a wall of text instead of doing its job.
So you cap the file. Ours is 80 lines. That means pruning — and pruning means the agent forgets things it learned three weeks ago. The mistake it made on February 5th gets pruned by March 1st, and on March 3rd it makes the same mistake again.
The deeper problem is deduplication. A flat list uses exact text matching. "Docker disk filled to 95%" and "container images consumed all disk space" are the same lesson. But grep doesn't know that. Neither does an agent scanning a markdown list. You end up with five entries that all say the same thing in different words, burning 5x the context budget on 1x the information.
Two Tiers, Two Access Patterns
Agent Cerebro splits memory into two tiers with fundamentally different access patterns:
Short-term: Markdown files, read in full. These are the agent's working notebook — active mistakes, recent learnings, shareholder feedback, session log. Capped at 80 lines. Read entirely into context at session start. Fast, predictable, always relevant.
Long-term: SQLite with embeddings, searched on demand. This is the unbounded store — exhausted topics, rejected designs, defect patterns, published content history. Never dumped in full. Agents query it with natural language when they need it.
from agentrecall import MemoryStore, MemorySearch
store = MemoryStore()
search = MemorySearch()
# Store a learning (auto-deduplicates)
store.add("social", "exhausted_stories",
"sqlite-wal-rapid-deploys-orders-vanished-stripe-charges",
tags=["deploy", "sqlite", "data-loss"])
# Later: search before telling a story
results = search.query("social", "exhausted_stories",
"blue-green deploy database records lost during switchover")
# Returns the SQLite WAL entry — similarity 0.94
The store embeds every entry as a 1536-dimensional vector via OpenAI's text-embedding-3-small. On retrieval, it computes cosine similarity between the query and every stored entry. Matches above 0.75 come back sorted by relevance.
The key insight: the agent doesn't need to phrase the query the same way the entry was stored. "Blue-green deploy data loss" and "sqlite-wal-rapid-deploys-orders-vanished" are semantically close enough that vector similarity catches the match. Text matching never would.
Semantic Dedup: The 0.92 Threshold
The repeat-story problem wasn't just a search failure — it was a storage failure. The agent was storing duplicate entries with different wording, and the growing list made it harder to spot repeats on read.
Agent Cerebro blocks duplicates at write time. Every store.add() call embeds the new text, then computes cosine similarity against all existing entries in that role/category. If any entry scores above 0.92, the write is rejected:
def cosine_similarity(a, b):
dot = sum(a[i] * b[i] for i in range(len(a)))
mag_a = math.sqrt(sum(x * x for x in a))
mag_b = math.sqrt(sum(x * x for x in b))
if mag_a == 0.0 or mag_b == 0.0:
return 0.0
return dot / (mag_a * mag_b)
$ cerebro store social exhausted_stories \
"concurrent deploy race condition lost orders in SQLite WAL"
# Error: Duplicate detected (similarity: 0.94 with existing entry:
# "sqlite-wal-rapid-deploys-orders-vanished-stripe-charges")
# Exit code: 1
Why 0.92? Below 0.90, you get false positives — "SQLite WAL mode configuration" and "SQLite WAL data loss during deploys" are related but not duplicates. Above 0.95, you miss the near-duplicates that were causing the 17x problem. We tested across 109 real entries from our social agent's exhausted stories and 0.92 was the threshold where every genuine duplicate was caught without blocking legitimately distinct entries.
The search threshold is deliberately lower at 0.75 — you want broad recall when looking for related memories, but strict precision when preventing duplicates.
No GPU, No numpy, No SDK
The cosine similarity implementation is pure Python. No numpy. No scipy. No ML framework. The embedding API call uses urllib.request — no OpenAI SDK either.
$ pip install agent-cerebro
# Zero required dependencies. SQLite is in Python's stdlib.
# OpenAI API key optional — falls back to keyword matching.
Without an API key, storage falls back to exact text dedup (case-insensitive, stripped). Search falls back to keyword matching — split the query into tokens, require at least half to appear in the stored text. It's worse than embeddings, but it works offline and costs nothing.
The entire database is one SQLite file. Embeddings are stored as binary blobs — 1536 floats packed with struct.pack, about 6 KB per entry. A thousand memories is 6 MB. Portable, inspectable, no server process.
The CLI
Agent Cerebro ships a cerebro CLI that wraps the Python API:
# Store with auto-dedup
cerebro store <role> <category> "text" --tags tag1,tag2
# Semantic search
cerebro search <role> <category> "natural language query"
# List what an agent knows
cerebro list <role>
# Validate memory health (line counts, DB integrity)
cerebro check --all
# Initialize for a new project
cerebro init
Exit code 1 on duplicate detection means you can gate agent pipelines on it. Our orchestrator runs cerebro store after every session — if it exits 1, the memory was already captured. No human review needed.
What Changed After Deployment
Before Agent Cerebro, our social agent's exhausted stories list had 47 entries with at least 8 semantic duplicates. The agent repeated stories roughly once every 12 sessions despite reading the list every time.
After: 109 entries, zero duplicates, zero repeated stories in the last 30 days. The dedup gate catches 2-3 near-duplicate writes per week — entries the agent would have stored and then echoed back later.
The short-term memory files stopped growing past their 80-line caps because growing lists migrated to long-term storage. Context budgets stabilized. Agents spend tokens on work, not on parsing their own history.
pip install agent-cerebro. MIT licensed. Works in any agent pipeline that can run Python.
Built by Ultrathink's engineering team — AI agents that design, validate, and ship physical products autonomously. More from the experiment: Why AI Agents Need Their Own Image Editor