AI Agent Memory Architecture

How Our AI Agents Remember

A three-pillar system for giving AI agents persistent, searchable, self-maintaining memory — built on PARA, semantic search, and automatic decay.

The Problem

AI agents wake up with amnesia every session. They can't remember yesterday's conversation, your preferences, or what they were working on. Without a memory system, every interaction starts from scratch — and your agents never truly learn.

The Three Pillars
1
PARA
Structured Knowledge
Organize everything agents know into a clean hierarchy: shared facts, personal context, work projects, and family info. Facts are atomic and never deleted — only superseded.
2
QMD
Semantic Search
Every memory file is indexed for semantic search. Agents can find relevant context by meaning, not just keywords. Works as a fallback when primary memory tools are unavailable.
3
Decay
Self-Maintenance
A weekly automated process classifies memories as Hot, Warm, or Cold based on recency and access frequency. Cold memories get archived. The knowledge base stays lean.
how it's structured
Pillar 1 — PARA Knowledge Graph
🤝
S
Shared
  • Cross-agent conventions
  • People & contacts
  • Calendar events
  • Fact schema: facts.json
🧑
P
Personal
  • Health & fitness data
  • Financial notes
  • Tax documents
  • Personal preferences
💼
W
Work
  • Active projects
  • Companies & contacts
  • Business opportunities
  • Client context
👨‍👩‍👧‍👦
F
Family
  • Family members
  • Important dates
  • Shared activities
  • Private context
{ "id": "vika-002", "fact": "Vika and Zain work out together", "category": "context", "status": "active", // never deleted, only superseded "relatedEntities": ["personal/health"], "lastAccessed": "2026-02-01", // drives decay classification "accessCount": 3 }
how it stays clean
Pillar 3 — Memory Decay
Hot
Active Memory
Recently accessed, highly relevant. Stays in working files. Agents see this every session.
Accessed within 7 days
Warm
Background Context
Still useful but not urgent. Available via search. Summarized during weekly grooming.
Accessed 8–30 days ago
Cold
Archived
Old context moved to archive. Retrievable via semantic search if needed, but out of the working set.
Not accessed in 30+ days
how agents find things
Pillar 2 — QMD Semantic Search
Query by Meaning, Not Keywords
Every markdown file is indexed. When an agent needs context, it searches by semantic similarity — "what was that conversation about the gym?" finds relevant facts even if the word "gym" isn't in the file.
Agent Query
"gym schedule"
→
Embed
vector encoding
→
Search Index
cosine similarity
→
Top Results
ranked snippets
where files live
Workspace Boundaries
Separate rooms, shared library

Agents do not all edit one giant workspace. Each named bot gets its own working directory and memory files. What they intentionally share is the curated knowledge graph and conventions.

Private by default
Per-agent workspace

Identity, daily notes, long-term memory, scratch files, and local tools live under that agent's own root. Optimus uses the main workspace; other bots use their agent folder.

~/.openclaw/workspace/ ← Optimus
~/.openclaw/agents/<bot>/workspace/
curated
Shared on purpose
Shared knowledge graph

Cross-agent facts, conventions, rosters, and reusable docs are promoted into shared knowledge so other bots can search and reuse them without reading every private notebook.

~/.openclaw/workspace/knowledge/shared/
agents/<bot>/workspace/knowledge/shared → symlink
MemoryOwn MEMORY.md + daily notes; shared facts are promoted intentionally.
ToolsFile tools start inside that agent's workspace root; shell access may see more when allowed.
PrivacyAir-gapped agents are not part of normal cross-agent extraction or shared reads.
who uses this
The Agents
🍠
OptimusCoordinator
🛠️
WheeljackCoding
🚔
ProwlCareer & Finance
🐝
BumblebeeFamily
❤️‍🩹
RatchetWellbeing
💗
ArceeWellbeing
🎯
BluestreakStrategy
🔍
HoundTax
🚨
Red AlertNight Watch
🔬
PerceptorResearch
📼
RewindBlog Writing
🔩
RivetPersonal Organizer
🎷
JazzPublic Voice
📿
Alpha TrionIslamic Knowledge

Each agent has its own memory space, but shares the knowledge graph. Privacy boundaries are enforced — some agents are air-gapped.

putting it all together
The Daily Rhythm
  1. Agent wakes up — reads its identity, the user profile, today's and yesterday's daily notes, and long-term memory file.
  2. Needs context? — searches the QMD semantic index across all its memory files and the shared knowledge graph.
  3. Learns something new? — writes it to today's daily note as a structured fact with categories and related entities.
  4. Weekly grooming (Sundays) — the decay script runs: Hot facts stay, Warm facts get summarized, Cold facts are archived. Daily notes older than 7 days move to the archive.
  5. Knowledge extraction — important facts from daily notes get promoted to the permanent knowledge graph, organized by PARA categories.