Phase 27C

ZeroBot Memory Architecture

How your agents remember, validate, and self-heal. Every fact passes through 3 layers of protection before it becomes a memory. No duplicates, no contradictions, no garbage.

3
Write Gate Layers
~100%
Dedup Catch Rate
4
Storage Tiers
3
Agent Tools
24/7
Self-Healing
Request Pipeline

Message Flow

Every message goes through classification, filtering, the LLM, and a tool loop before responding. Click any step for details.

💬
User Message
Slack / Web / WhatsApp
🧭
Intent Classify
Regex-first, AI fallback
🔧
Tool Filter
Intent-based selection
🧠
LLM Router
8 models, best fit
🔄
Tool Loop
Max 5 calls
Response
+ background memory write
Core Innovation

Memory Write Gate — 3 Layers

Every potential memory passes through 3 deduplication layers before being written. No silent duplicates, ever. Click a layer for details.

Layer 1: Exact Match ~70% caught
Normalize content (lowercase, strip punctuation) and check D1 normalized_content column. Instant reject on exact match.
D1 query — <5ms
Layer 2: Embedding Similarity ~15% caught
Generate embedding, query Vectorize for cosine similarity > 0.92. Catches paraphrases like "Dara is my wife" vs "My wife is Dara".
Vectorize + Workers AI — ~50ms
Layer 3: LLM Decision ~15% caught
Workers AI evaluates: ADD / UPDATE / DELETE / NOOP. Compares meaning, context, and temporal relevance.
Workers AI (Llama 3.3 70B) — 3s timeout

⏰ On timeout — pending_memories queue

If Layer 3 can't decide within 3 seconds, the memory is queued for nightly batch processing. The system never silently creates duplicates.

Identity Protection

Ground-Truth Validation

Before any memory writes about the user, it's cross-checked against USER.md — the single source of truth. Prevents hallucinated facts.

🛡️

USER.md Cross-Check

USER.md is a protected identity file that only the user can edit. Before writing any memory that references personal facts (family, preferences, identity), the system compares the new claim against USER.md. Contradictions are rejected.

USER.md says: "Wife: Dara (I call her Puds)"
Agent hears in conversation: "Tell Sarah I said hi"
Memory: "Wife is Sarah"REJECTED (contradicts USER.md)
Memory: "Ben mentioned someone named Sarah"ALLOWED (no identity claim)

🔒 Agents Can Never Modify USER.md

Your agents can suggest updates to your profile but can never modify it themselves. This prevents AI hallucination from corrupting your identity. Only you can change who you are.

End to End

Memory Lifecycle

A memory's journey from extraction to injection back into the prompt. Click any step for details.

💡
Save
Extract fact from conversation
🛡️
Validate
USER.md cross-check
🔍
Dedup
3-layer write gate
💾
Store
D1 + Vectorize + KV cache
🔎
Recall
Semantic + keyword scoring
💉
Inject
Top 3 into system prompt
Infrastructure

Storage Architecture

Three active storage layers, each with a specific purpose. R2 file storage is removed — D1 is the source of truth. Click any card for details.

🗄️
D1 (SQLite)
Primary store. Structured entities, metadata, importance scores, provenance tracking. Query by user + bot + category.
🧲
Vectorize
Vector embeddings for semantic search. Cosine similarity matching. Per-user namespace isolation.
KV (Cache)
Hot cache. 7-day TTL, stale-while-revalidate. Query embeddings, personality, memory reads.
📦
R2 (Object Storage)
Previously held memory files. Migrated to D1. Still used for identity/knowledge files only.
Agent Capabilities

Agent Memory Tools

Agents use three tools to manage memories. Inspired by the Letta pattern — agents can update and forget, not just add. Click any tool for details.

update_memory
Create new or update existing memory by ID. Triggers the full 3-layer write gate.
Replaces save_memory
forget_memory
Soft-delete a memory. Removes from Vectorize index. Retained in D1 for audit.
New tool
list_memories
Browse memories with filters: category, date range, keyword. Returns structured results.
New tool

Why Update + Forget Instead of Just Save?

Traditional chatbots can only add memories. Your agents can also correct outdated information and remove irrelevant facts. This keeps the memory store clean and accurate over time — not just growing indefinitely.

Autonomous Maintenance

Nightly Self-Healing

Two cron jobs run every night to process deferred decisions and consolidate memory. Your agents maintain themselves while you sleep.

23:45 UTC
Pending Processor
Re-evaluates timed-out Layer 3 decisions from the day. Clears the pending queue. No memory is lost or silently duplicated.
23:50 UTC
Consolidation & Decay
Merges near-duplicates, resolves contradictions (newest wins), decays importance on stale memories. Keeps the memory store clean and relevant.

Memory Gets Better Over Time

Unlike traditional AI where memory degrades or fills with garbage, ZeroBot's nightly self-healing means your agent's memory improves with age. Stale facts fade, contradictions resolve, and duplicates merge — automatically.

Team Intelligence

Cross-Agent Shared Memory

Your agents share a common memory pool via D1. When one learns something, all can recall it. Create as many agents as you need — these four are examples.

🎯
Kit
Chief of Staff
Priorities, schedule, personal context
📡
Scout
Marketing Intel
Trends, competitor mentions, social data
🤝
Closer
Sales Pipeline
Deals, client prefs, follow-ups
🛡
Sentinel
Security
Permissions, alerts, anomalies
🗃️
D1 shared_memories table — visible to all agents

These are example agents. Yours can be anything.

A Customer Support agent. A Recruiter agent. A Legal Review agent. Whatever your business needs — create it, name it, and it immediately joins the shared memory pool. When one agent learns something, the whole team knows.