Memory Bank Pattern

The Memory Bank is a structured directory pattern for maintaining project context across agent sessions. It’s how your agent (and you) keep track of what’s happening, what’s been decided, and what to do next.

Why Memory Bank?

AI agents have no memory between sessions. Every conversation starts fresh. The Memory Bank solves this by:

Persisting context — Important decisions and state survive restarts
Structuring knowledge — Clear locations for different types of information
Enabling handoffs — Multiple agents (or humans) can pick up where others left off
Reducing repetition — Don’t re-explain the same context every session

Two types of memory banks

Global Memory Bank

Personal context spanning all projects. Lives at ~/global-memory-bank/:

global-memory-bank/
├── 00-core/                # Identity, systems (stable)
│   ├── identity.md         # Who you are, goals, working style
│   └── systems.md          # Tools, environments, key paths
├── 01-active/              # Current work (START HERE)
│   ├── currentWork.md      # What's happening NOW
│   ├── nextUp.md           # Prioritized cross-project backlog
│   └── blockers.md         # Active obstacles
├── 02-patterns/            # Reusable patterns across projects
├── 03-guides/              # Cross-project how-tos
├── 04-contacts/            # People, orgs, relationships
├── 05-ideas/               # Ideas, explorations
├── 06-learnings/           # Technical learnings (dated)
├── 07-projects/            # Cross-project summaries
├── 08-sessions/            # Archived session logs (dated)
└── 09-research/            # Deep dives, explorations

Project Memory Bank

Project-specific context. Lives at project/memory-bank/:

memory-bank/
├── 00-core/                # Identity, constraints
│   ├── projectBrief.md     # What we're building
│   ├── productContext.md   # Why it exists, mental model
│   └── README.md           # Project overview
├── 01-active/              # Current state (CHECK FIRST)
│   ├── currentWork.md      # What's happening NOW
│   ├── blockers.md         # What's stuck
│   └── nextUp.md           # Prioritized next actions
├── 02-architecture/        # System design
│   ├── architecture.md     # Full system overview
│   └── decisions.md        # Architectural decision records (ADRs)
├── 03-patterns/            # Reusable approaches
├── 04-business/            # Product & positioning
├── 05-sessions/            # Session logs (dated)
├── 06-learnings/           # Technical discoveries
├── 07-reference/           # Imported docs, specs
├── 08-history/             # Milestones, retrospectives
├── 09-research/            # Competitor analysis, explorations
├── 10-archive/             # Deprecated/superseded docs
└── README.md               # Quick start guide

The numbered prefix system

Directories are numbered for reading order and priority:

Prefix	Purpose	Read when…
`00-`	Core identity & constraints	Starting any work
`01-`	Active state	Every session start
`02-`	Architecture	Touching system design
`03-`	Patterns	Implementing something similar
`04+`	Reference material	As needed

Key files

00-core/projectBrief.md

The most important file. Contains project identity:

What we’re building (elevator pitch)
Why it exists (problem it solves)
Tech stack overview

01-active/ directory

Check this every session. Three files:

currentWork.md — What’s happening right now

Current focus
Recent changes
Quick commands

blockers.md — What’s stuck

Blocked issues
Waiting on external factors
Known bugs

nextUp.md — What to do next

Prioritized task list
Immediate vs. later items

Session workflow

Start a session

Read 01-active/ files to understand current state.

Read 01-active/currentWork.md
Read 01-active/blockers.md
Read 01-active/nextUp.md

Check constraints

If touching architecture, read 00-core/projectBrief.md and 02-architecture/.
Do work

Reference patterns in 03-patterns/ if implementing something similar.
Update state

Before ending, update 01-active/currentWork.md with:
- What you did
- What changed
- Any new blockers
Log significant sessions

Create 05-sessions/YYYY-MM-DD-topic.md for major work.

Creating a memory bank

For a new project:

mkdir -p memory-bank/{00-core,01-active,02-architecture,03-patterns,04-business,05-sessions,06-learnings,07-reference,08-history,09-research,10-archive}

Create the essential files:

touch memory-bank/README.md
touch memory-bank/00-core/{projectBrief.md,productContext.md,README.md}
touch memory-bank/01-active/{currentWork.md,blockers.md,nextUp.md}

Best practices

Keep 01-active/ current

This is the most-read directory. Stale information here wastes everyone’s time.

Be concise

Memory bank files should be scannable. Use:

Bullet points over paragraphs
Tables for structured data
Code blocks for commands

Date session logs

Use YYYY-MM-DD-topic.md format:

2024-12-28-auth-refactor.md
2024-12-27-fly-migration.md

Archive, don’t delete

Move outdated docs to 10-archive/ rather than deleting. Context is valuable.

Link between files

Cross-reference related docs:

See [architecture decisions](../02-architecture/decisions.md) for background.

Example: currentWork.md

# Current Work

**Last Updated:** 2024-12-28 04:30 UTC

## Current Focus

Migrating from CF Containers to Fly.io.

### What's Done
- ✅ Fly account setup
- ✅ Base image deployed
- ✅ Test machine running

### In Progress
- 🔄 Router integration with Fly Machines API
- 🔄 Provisioning endpoint update

### Next
- Email flow end-to-end test
- User migration script

## Quick Commands

\`\`\`bash
# Check Fly machines
fly machines list -a tinyfat-test

# Deploy base image
fly deploy --app fat-mom-base
\`\`\`

Integration with MEMORY.md

Your agent’s /data/MEMORY.md is personal context. Memory banks are shared context.

File	Scope	Updates
`/data/MEMORY.md`	Agent identity, preferences	Per-agent
`~/global-memory-bank/`	Cross-project personal context	Per-person
`project/memory-bank/`	Project state, architecture	Per-project, shared

For projects, point your agent to the memory bank:

Read memory-bank/01-active/ to understand current project state.

Global vs Project

Aspect	Global	Project
Location	`~/global-memory-bank/`	`project/memory-bank/`
Scope	All your work	Single project
Shared	No (personal)	Yes (team)
Identity	Who you are	What the project is
`00-core/`	identity.md, systems.md	projectBrief.md, productContext.md
`01-*`	active/ (current work)	active/ (current work)
`02-*`	patterns/	architecture/
Focus	Cross-project context	Deep project context

Next steps

Beads Issue Tracking — Pair memory bank with issue tracking
Agent Workspace — Your agent’s filesystem