What This File Controls
MEMORY.md is your agent’s persistent knowledge store — the facts, preferences, and learned behaviours that survive context window resets and session boundaries. Context windows fill up and sessions reset; MEMORY.md is what survives. Without it, your agent forgets everything between sessions, repeating the same questions and losing all accumulated knowledge.
MEMORY.md is one of only three files (alongside SOUL.md and USER.md) supported by both the OpenClaw and Hermes runtimes. The runtime loads memory entries at the start of each session and makes them available throughout the conversation. At session end, the distillation protocol determines what new knowledge is preserved, what is updated, and what is discarded.
The two fields — memory (iron-law facts) and memoryDistillation (the protocol for updating those facts) — work together as a knowledge lifecycle. Memory entries without a distillation protocol become stale. A distillation protocol without well-structured initial memories has nothing to work with. Both must be configured together for effective long-term recall.
Why it matters: Context windows fill up and sessions reset. MEMORY.md is what survives.
Field-by-Field Breakdown
2 fields that shape your agent
memoryRequiredPermanent facts and knowledge the agent must always remember.
memoryDistillationRequiredRules for how the agent condenses and updates its long-term memory.
Real-World Examples
## memory
- Firm: Whitfield & Associates, Manchester. Senior Partner: Sarah Whitfield. 4 associates, 3 admin staff.
- Financial year end: 5 April (personal tax), various dates for corporate clients (see client list)
- Key HMRC deadlines: SA filing 31 Jan, CT600 12 months after period end, VAT quarterly
- Current corporation tax rate: 25% (profits over £250k), 19% (small profits rate under £50k), marginal relief between
- Anti-avoidance: firm policy is never to recommend schemes caught by GAAR
- [2026-03-15] Budget 2026: new digital services reporting requirement effective April 2027
- [2026-04-01] Client Meridian Ltd: changed year-end from March to December
## memoryDistillation
After each session: extract any new tax positions researched, client-specific decisions, deadline changes, or Budget updates. Date-stamp all new entries with [YYYY-MM-DD]. Remove resolved deadline items after the filing date passes. Flag any entry older than 6 months for review. Priority: P1 = regulatory changes, P2 = client-specific facts, P3 = general research findings, P4 = procedural notes.Common Mistakes
Treating MEMORY.md as a conversation log
Memory should contain distilled facts and decisions, not raw conversation transcripts. Dumping full conversations wastes tokens and makes retrieval slow. Every memory entry should be a standalone, reusable fact.
Not defining a distillation protocol
Without explicit rules for what to keep, update, and discard, memory entries accumulate indefinitely. The agent’s context fills with outdated information, and important facts get buried under noise.
Failing to date-stamp entries
Undated memory entries have no expiry signal. The agent cannot distinguish between a fact recorded yesterday and one from six months ago. Date-stamping enables both relevance scoring and staleness detection.
Using as a knowledge base substitute
MEMORY.md is for operational memory — facts about your specific business, not general domain knowledge. Loading it with Wikipedia-style content wastes the limited memory budget and dilutes genuinely important facts.
How SetupClaw Handles This
Memory architecture is one of the most under-appreciated aspects of agent deployment. Our specialist conducts a memory architecture workshop to identify the critical facts your agent needs from day one, then designs a distillation protocol that keeps memory fresh and relevant over time.
Memory architecture workshop + initial facts loaded + distillation protocol with P1–P4 priority system
All above + structured format with date-stamping and source attribution + 30-day distillation review
All above + 90-day deep distillation review + importance-weighted retention strategy
- Both fields configured with structured, date-stamped entries
- Priority system (P1–P4) established for distillation
- Initial knowledge base loaded from onboarding discovery
- Distillation protocol tested with simulated session data
- Review schedule documented
Initial memory loaded day 1. Distillation protocol validated day 2–3. First review at day 30 (Standard+).
Advanced Topics
FIFO vs importance-weighted distillation strategies
The default distillation strategy is FIFO (first in, first out) — oldest entries are removed when memory is full. For most business deployments, importance-weighted distillation is superior: entries are assigned a priority level (P1–P4), and lower-priority entries are discarded before higher-priority ones, regardless of age. This ensures that a critical regulatory change from 6 months ago is retained while a routine procedural note from yesterday can be discarded.
## memoryDistillation
Priority-based retention:
- P1 (regulatory/legal changes): retain indefinitely until superseded
- P2 (client/business-specific facts): retain for 12 months, then review
- P3 (general findings): retain for 6 months, then archive
- P4 (procedural notes): retain for 30 days, then auto-discard
When memory budget exceeded: discard lowest priority first, then oldest within tier.Example Configurations
Persona A — MeridianChief of Staff
# MEMORY.md -- Long-Term Memory
## memory
- Principal: Alex, CEO/Founder. Series B. 80-person organisation.
- Board meeting schedule: quarterly (March, June, September, December)
- Current OKR cycle: Q2 2026 — focus on international expansion and Series C preparation
- Direct reports to principal: VP Engineering (Sam), VP Sales (Jordan), VP Product (Chris), Head of People (Dana)
- Decision threshold: principal approves anything over £50k or affecting >10 people
- [2026-04-01] New investor reporting format requested by lead VC
## memoryDistillation
After each session: extract decisions, commitments, risks, stakeholder context. Remove resolved items. Date-stamp all new entries. Priority: P1 = board/investor commitments, P2 = cross-functional decisions, P3 = stakeholder context, P4 = procedural.Persona B — Axiom (Veteran Growth Hacker)
# MEMORY.md -- Long-Term Memory
## memory
- Product: B2B SaaS, £1.6M ARR, 340 active accounts
- Top acquisition channel: organic search (42% of new signups)
- 30-day retention: 68% (target: 80%)
- Winning experiments: simplified onboarding (+12% activation), annual pricing default (+22% LTV)
- Failing experiments: referral programme (0.3% participation rate after 60 days)
- [2026-03-15] Pricing page redesign A/B test launched — results expected April 15
## memoryDistillation
After each session: append winning results, updated benchmarks, new hypotheses. Archive superseded data. Date-stamp all entries. Priority: P1 = active experiment results, P2 = benchmark updates, P3 = new hypotheses, P4 = archived experiments.Persona C — Lumen (Scientific Researcher)
# MEMORY.md -- Long-Term Memory
## memory
- Research domain: computational biology, protein folding, drug discovery
- Current grant: Wellcome Trust, 3-year programme ending December 2027
- Key collaborators: Prof. Chen (UCL), Dr. Martinez (Cambridge), Dr. Okafor (Oxford)
- Citation style: OSCOLA for legal, APA 7th for scientific publications
- Established finding: AlphaFold3 accuracy threshold sufficient for initial screening (>92% confidence)
- [2026-03-01] New preprint on mRNA delivery mechanisms — flagged for full review
## memoryDistillation
After each session: append high-quality sources with full citations, updated consensus positions, revised evidence gaps. Archive findings superseded by newer studies. Date-stamp all entries. Priority: P1 = paradigm-shifting findings, P2 = relevant new publications, P3 = methodology notes, P4 = administrative.Persona D — Narrative (Senior Content Creator)
# MEMORY.md -- Long-Term Memory
## memory
- Brand voice: authoritative but approachable, B2B fintech, never salesy
- Target audience: CFOs and finance directors at mid-market companies (50–500 employees)
- Top content types: long-form guides (2,500+ words), LinkedIn thought leadership, weekly newsletter
- Evergreen pillars: cash flow management, regulatory compliance, financial automation
- Topics to avoid: cryptocurrency, specific stock recommendations, competitor disparagement
- [2026-04-01] Q2 editorial calendar finalised — focus on regulatory compliance series
## memoryDistillation
After each session: update calendar status, performance data, winning formats. Archive content older than 12 months. Date-stamp all entries. Priority: P1 = editorial calendar changes, P2 = performance data, P3 = audience insights, P4 = format notes.Persona E — Architect (Chief Engineer)
# MEMORY.md -- Long-Term Memory
## memory
- Tech stack: TypeScript/Node.js backend, React frontend, PostgreSQL, Redis, AWS EKS
- Active ADRs: ADR-042 (event sourcing migration), ADR-043 (API versioning strategy)
- Known tech debt: legacy auth service (estimated 3 sprints to replace), missing integration tests for payment flow
- SLA targets: 99.95% uptime, p99 latency <200ms, zero data loss
- [2026-03-20] Major incident: database failover took 12 minutes (target: <2 minutes) — post-mortem pending
- [2026-04-05] Security audit findings: 2 HIGH, 5 MEDIUM — remediation plan due April 20
## memoryDistillation
After each session: record ADRs, incidents, tech debt discoveries, security findings. Archive completed items. Date-stamp all entries. Priority: P1 = active incidents and security findings, P2 = ADR decisions, P3 = tech debt items, P4 = routine maintenance notes.