← Blog · · 10 min read

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.

Tutorial Memory Production Code

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?

Your Situation
Level
Setup Time
Weekend project, <50 facts
Level 1: Markdown
5 min
Solo agent, <30 days
Level 2: Daily Notes
30 min
Scaling past 1000 facts
Level 3: Vector DB
2 hours
Production 24/7 agent
Level 4: Scored Memory
1 day

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 →