← AgentAwake
🔮
Chapter 23 · 14 min read
𝕏

Memory That Scales

From markdown files to knowledge graphs — when your agent outgrows its notebook

Your flat files have been working beautifully. Then one day you ask: "What was the reasoning behind the pricing change we made after that customer complaint in November?" And your agent fumbles. It finds the pricing change. Finds a customer complaint. But can't connect them. Your flat files just hit their ceiling.

🍕 Real-life analogy
Think of agent memory like housing. A studio apartment (flat files) works great when you're starting out. A one-bedroom with a closet organizer (Obsidian) lets you find things. A house with a smart filing system (vector DB) finds the closest match. A house with a librarian who understands relationships (knowledge graph) — that's the upgrade.

The Memory Maturity Ladder

Level 1: Flat Files

MEMORY.md, daily notes, raw markdown. Simple, cheap, works great starting out.

Level 2: Structured Markdown + Obsidian

PARA method, wiki-links, visual graph. Same stuff, but you can find things.

Level 3: Vector DB + RAG

What OpenClaw already does under the hood. Describe what you want, it finds the closest match.

Level 4: Knowledge Graphs

Understands relationships. "The contract signed after the meeting where Bob disagreed." The librarian gets it.

Level 5: Tiered Cognitive Memory

Different rooms for different thinking: whiteboard (working), journal (episodic), encyclopedia (semantic), recipe book (procedural).

⚠️ Don't Upgrade Because It Sounds Cool
Most people reading this are at Level 1 or 2. That's fine. Don't upgrade until you hit a real wall. The best memory system matches your actual complexity, not your aspirational complexity.

The Three Triggers: When to Upgrade

Trigger 1: The Multi-Agent Tangle (>3 Agents)

Symptom: Agents contradict each other. Info gets lost. You're manually mediating between agent memories.

Upgrade: Shared vector DB or knowledge graph with read/write isolation.

Trigger 2: The Time Horizon Problem (>90 Days)

Symptom: Agent gives outdated answers. Search results feel random. You're manually pruning files.

Upgrade: Knowledge graph with temporal awareness, or aggressive consolidation pipeline.

Trigger 3: The Multi-Hop Failure

Symptom: Complex questions get wrong answers. Agent finds piece A and C but misses the connection through B.

Upgrade: Knowledge graph. Full stop.

Option 1: Vector DB + RAG (You Already Have This)

When your agent uses memory_search, it's doing vector search. Your markdown files are the source. Vector similarity is the retrieval.

✅ Where It Shines
  • • Simple to set up (already set up)
  • • Great for "find me things about X"
  • • Handles large volumes of text
  • • Cost-effective — embedding is cheap
❌ Where It Plateaus
  • • No understanding of relationships
  • • No temporal awareness
  • • Multi-hop queries fail
  • • Duplicate/conflicting info returned

Option 2: Graph Memory (Mem0, Graphiti/Zep)

🍕 Real-life analogy
Think of it as a detective's evidence board. Photos (nodes) connected by red string (edges), with dates on each connection. You can follow the string from suspect to crime to witness to alibi.
Example: Graph Relationships
Nodes:
  Alice (person)
  Q3 Review (event, date: 2024-09-15)
  Pivot to B2B (decision, date: 2024-09-16)
  Project Phoenix (project, started: 2024-09-20)

Edges:
  Alice → attended → Q3 Review
  Q3 Review → resulted in → Pivot to B2B
  Pivot to B2B → spawned → Project Phoenix
  Alice → leads → Project Phoenix

Now "What came out of the Q3 review?" follows the edges: Review → Decision → Project. Multi-hop? Easy.

Option 3: Tiered Cognitive Memory

🧠 Working Memory

What the agent thinks about right now. Small, fast, ephemeral. Your current conversation context.

📔 Episodic Memory

Specific experiences with timestamps. "On Jan 15th, the deploy failed because of a missing env var." Your daily notes.

📚 Semantic Memory

General knowledge and facts. "The production DB is on AWS us-east-1." No timestamp needed. MEMORY.md, knowledge base.

🔧 Procedural Memory

How to do things. "To deploy, run git push origin main then check Vercel." AGENTS.md, skill files.

The Pragmatic Recommendation

1-2 agents, <6 months of history

Keep markdown + Obsidian + OpenClaw's vector search. Stop here. This handles 90% of use cases.

Hit a trigger (3+ agents, >90 days, multi-hop failures)

Add Mem0. Keep markdown as source of truth backup. Sweet spot for power users.

Production systems (paying customers, SLAs)

Add Graphiti/Zep for temporal reasoning. Implement tiered memory. Use a proper vector DB. Enterprise territory.

Setting Up Mem0

lib/mem0.ts
import { MemoryClient } from 'mem0ai';

const mem0 = new MemoryClient({
  apiKey: process.env.MEM0_API_KEY,
});

// Store a memory
export async function addMemory(
  content: string,
  userId: string,
  metadata?: Record<string, any>
) {
  return await mem0.add(
    [{ role: 'user', content }],
    { user_id: userId, metadata }
  );
}

// Search memories
export async function searchMemory(query: string, userId: string) {
  return await mem0.search(query, {
    user_id: userId,
    limit: 10,
  });
}

The Bridge Pattern: Gradual Migration

Don't rip out markdown to add a graph. Use the bridge pattern:

1️⃣
Keep writing to markdown — source of truth and backup
2️⃣
Sync to your graph — nightly job pushes new notes
3️⃣
Query the graph first — complex questions hit graph; simple ones hit files
4️⃣
Fall back gracefully — if graph is down, agent still works with markdown
The bridge pattern in code
async function agentSearch(query: string, agentId: string) {
  // Try graph first for complex queries
  if (isComplexQuery(query)) {
    try {
      const graphResults = await searchMem0(query, agentId);
      if (graphResults.length > 0) return graphResults;
    } catch (e) {
      console.warn('Graph search failed, falling back');
    }
  }
  // Fall back to vector/markdown search
  return await vectorSearch(query, agentId);
}

function isComplexQuery(query: string): boolean {
  const indicators = [
    'before', 'after', 'because', 'led to',
    'resulted in', 'changed', 'decided',
    'when did', 'why did', 'how did',
  ];
  return indicators.some(i =>
    query.toLowerCase().includes(i)
  );
}

Cost Comparison

Markdown + Vector Search
Free — $5/mo

Already done. Minimal maintenance. Good for single agent, <90 days.

Mem0 (Managed)
Free — $49/mo

30 min setup. Near zero maintenance. Good for 1-3 agents, production.

Graphiti/Zep (Self-Hosted)
$50 — $100/mo

Half-day setup. High maintenance. Good for temporal reasoning, multi-agent.

Full Tiered Cognitive Memory
$100 — $500/mo

1-2 weeks setup. Enterprise territory. Hire someone who's done this before.

The Decision Framework

Ask these in order. Stop at the first "yes":

1. "1-2 agents, <90 days?" → Stay with markdown + Obsidian.
2. "Multi-hop failures or temporal confusion?" → Add Mem0.
3. "Need point-in-time queries?" → Add Graphiti/Zep.
4. "Building a product with memory as core feature?" → Tiered cognitive memory.
5. "10+ agents serving paying customers?" → Go enterprise. Hire help.
🧠 Quick Check
Your agent has been running for 2 months with a single workspace and answers past questions correctly. Should you add Mem0?
🧠 Quick Check
You ask 'Why did we change pricing after the October meeting?' and the agent gives you the pricing change but not the connection to the meeting. What type of failure is this?
Memory Scaling Checklist
0/6 complete

Share this chapter

𝕏

Chapter navigation

24 of 36