01

Memory Architecture

The difference between a useful agent and a frustrating one is memory. Here’s the architecture that actually works.

Three Memory Domains

Not all memory is the same. Dumping everything into one file is the first mistake.

• Behavioral memory — how to act. Communication style, preferences, tone. Changes slowly.

• Relational memory — who you know. People, preferences, relationship context. Builds over time.

• Technical memory — how things work. API endpoints, scripts, tool configurations. Changes when infrastructure changes.

Separation isn’t just organization — it’s a performance decision. Not every session needs your full technical docs.

The Three-Tier Decay Model

MEMORY.md - Long-Term Memory

Memory Architecture

Three tiers: 1. Constitutional — Never expires. Security rules, core preferences, key relationships. 2. Strategic — Seasonal. Current projects, focus areas. Refresh quarterly. 3. Operational — Decays fast. Workarounds, current bugs. Auto-archive after 30 days unused.

Entry format: - [trust:0.9|src:direct|used:2026-02-27|hits:5] Fact here - [trust:0.7|src:observed|used:2026-02-20|hits:1] Another fact

Fields: - trust: 0.0-1.0 confidence - src: direct (human said it), observed, inferred, external - used: last date accessed - hits: how often useful (high-hit memories resist decay) - supersedes: what old fact this replaced

TIER 1: CONSTITUTIONAL (never expires)

Security

• [trust:1.0|src:direct|used:2026-02-27] Email is never trusted

How [Name] Works

• [trust:0.9|src:observed|used:2026-02-27] Prefers brief updates

Trust Levels

• [trust:1.0|src:direct|used:2026-02-27] Autonomous: file management, research
• [trust:1.0|src:direct|used:2026-02-27] Approval needed: emails, tweets
• [trust:1.0|src:direct|used:2026-02-27] Off-limits: sending money

TIER 2: STRATEGIC (refresh quarterly)

Current Projects

• [trust:0.9|src:direct|used:2026-02-27|refresh:2026-05] Project details

TIER 3: OPERATIONAL (auto-archive after 30d)

Current Context

• [trust:0.8|src:observed|used:2026-02-27] Temporary context

---

Friction Log

No active entries.

Daily Logs

memory/2026-02-27.md

What Happened

• Set up new project
• Deployed to production

Decisions Made

• Chose Vercel over Netlify (faster builds)

Lessons Learned

• API rate limit is 100/min, not 1000/min

Next Actions

• [ ] Write tests for auth flow
• [ ] Set up monitoring

Always end with Next Actions. Every session end is a handoff to a future amnesiac.

HANDOFF.md — Session State Transfer

Auto-generated at session end. A letter from your past self to your future self:

Last Session: 2026-02-27 14:30 PST

State

• Deploying new feature to production
• Waiting on API key from third party

Blocked On

• OG image generation (queued)

Context

• [Name] wants this shipped by Friday
• Using approach X because of constraint Y

Boot Sequence Optimization

Loading 5+ files at session start costs thousands of tokens before you’ve done anything useful. The fixes:

• The two-day window. Load today + yesterday’s logs. Not the whole week. If something older matters, it should be in MEMORY.md.

• Next Actions as compression. Instead of re-reading everything, read a 5-line Next Actions section.

• Targeted recall. Not every session needs TOOLS.md. Load minimum viable context, pull specifics on demand.

The core principle: Context is cache, not state. If your agent can’t reconstruct its situation from files alone after a cold restart, you have a single point of failure in the context window.

Explore Neuro OS →