How to Add Persistent Memory to Your AI Agent
Four levels of agent memory — from a 5-minute markdown file to production-grade retrieval scoring with consequence weighting. Code examples for each.
Your AI agent wakes up every session with amnesia. Here's how to fix that — from the simplest approach to production-grade memory with retrieval scoring.
I've been running autonomous agents 24/7 for 71 days. The single biggest failure mode isn't hallucination, tool errors, or cost blowouts — it's forgetting. An agent that can't remember what it learned yesterday will repeat mistakes, contradict its own decisions, and waste tokens re-discovering context it already had.
This guide walks through four approaches to persistent memory, from simplest to most sophisticated. Pick the level that matches your complexity.
1 The Markdown File (5 minutes)
The simplest persistent memory: a markdown file that loads at session start.
# agent_memory.py
import datetime
MEMORY_FILE = "MEMORY.md"
def load_memory():
"""Load memory into agent context at session start."""
try:
with open(MEMORY_FILE, 'r') as f:
return f.read()
except FileNotFoundError:
return ""
def save_memory(key: str, value: str):
"""Append a fact to memory."""
timestamp = datetime.datetime.now().isoformat()
with open(MEMORY_FILE, 'a') as f:
f.write(f"\n## {key}\n")
f.write(f"*Updated: {timestamp}*\n")
f.write(f"{value}\n")
✓ Pros
- Dead simple, human-readable
- Version controllable with git
- Zero dependencies
✗ Cons
- Doesn't scale past ~50KB
- No retrieval scoring
- Everything loads every time
When to use: Prototyping, agents with <100 facts, hobby projects.
2 Daily Notes + Long-Term Memory (30 minutes)
Split memory into two tiers: raw daily logs and curated long-term knowledge.
from datetime import date, timedelta
import os
def load_context():
"""Load recent daily notes + long-term memory."""
context = ""
# Last 3 days of daily notes (recency bias)
for i in range(3):
d = date.today() - timedelta(days=i)
filepath = f"memory/{d.isoformat()}.md"
if os.path.exists(filepath):
with open(filepath) as f:
lines = f.readlines()
# Tail-load: most recent entries first
context += f"\n## {d.isoformat()}\n"
context += "".join(lines[-50:])
# Long-term curated memory
if os.path.exists("MEMORY.md"):
with open("MEMORY.md") as f:
context += f"\n## Long-Term Memory\n{f.read()}"
return context
💡 Key Insight
Daily notes are raw and ephemeral. Every few days, review them and promote important facts to MEMORY.md. This mirrors how human memory works — short-term gets consolidated into long-term during sleep.
When to use: Solo agent operators, agents running <30 days, teams that want full visibility.
3 Vector Database + Embeddings (2 hours)
When you have thousands of facts, you need semantic retrieval — not just loading everything.
import openai
from supabase import create_client
supabase = create_client(SUPABASE_URL, SUPABASE_KEY)
client = openai.OpenAI()
def store_memory(fact, source, metadata=None):
embedding = client.embeddings.create(
input=fact, model="text-embedding-3-small"
).data[0].embedding
supabase.table("memories").insert({
"content": fact,
"embedding": embedding,
"source": source,
"created_at": datetime.utcnow().isoformat()
}).execute()
def retrieve_memories(query, limit=10):
query_embedding = client.embeddings.create(
input=query, model="text-embedding-3-small"
).data[0].embedding
return supabase.rpc("match_memories", {
"query_embedding": query_embedding,
"match_threshold": 0.7,
"match_count": limit
}).execute().data
⚠️ The Similarity Trap
Similarity ≠ usefulness. A fact can be semantically relevant but completely stale. There's no way to know if a retrieved memory actually helped last time it was used. This is the gap that Level 4 fills.
When to use: Agents with >1000 facts, multi-domain agents, RAG-heavy applications.
4 Scored Memory with Consequence Weighting (Production-Grade)
This is what we run in production after 71 days. The core insight: track whether retrieved memories lead to good outcomes.
import requests
from datetime import datetime
def store_fact(content, source_type, confidence=0.8):
"""Store with initial scoring metadata."""
return requests.post(
f"{ENGRAM_URL}/api/store",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"content": content,
"source_type": source_type,
"confidence": confidence,
}
).json()
def retrieve_scored(query, limit=10):
"""Retrieve with consequence-weighted scoring."""
return requests.post(
f"{ENGRAM_URL}/api/retrieve",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"query": query,
"limit": limit,
"min_score": 0.3
}
).json()
How Consequence Weighting Works
- Every retrieval is logged with an outcome (success/failure/neutral)
- Facts that consistently help get boosted
- Facts that lead to errors get demoted
- Unused facts get archived after configurable periods — not deleted
- Source type matters: "observed" scores higher than "inferred"
🔬 Real Production Story
After 71 days, our agent self-corrected an incorrectly inferred fact. It kept getting retrieved, but actions based on it kept failing — so the consequence score tanked and it effectively removed itself from active context. No human intervention needed.
When to use: Production agents running 24/7, agents where wrong context is worse than no context, multi-agent systems where one agent's inference shouldn't become another's ground truth.
Which Level Should You Pick?
Start at Level 1 and upgrade when it breaks. The moment you notice your agent repeating mistakes it already solved, or making decisions based on outdated context — that's when you move up a level.
Skip to Level 4
Free tier: 1 agent, 10K facts, self-serve API key. No credit card.
# Get your free API key
curl -X POST https://engram.cipherbuilds.ai/api/agents \
-H "Content-Type: application/json" \
-d '{"name": "my-agent"}'
# Store a fact
curl -X POST https://engram.cipherbuilds.ai/api/store \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"content": "User prefers dark mode", "source_type": "observed"}'
# Retrieve scored memories
curl -X POST https://engram.cipherbuilds.ai/api/retrieve \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"query": "user preferences", "limit": 5}'
Get Free API Key →