The Three-Layer Memory System

Why memory matters

Every session starts amnesiac. Without memory you re-explain the same background every time: what the project is, what you prefer, where you left off.

Three layers exist to make continuity across sessions possible.

The structure

Layer	Location	Scope	Written by
Cloud	Server-side	All projects	System-maintained
User	`~/.workbuddy/MEMORY.md`	Across projects	On your explicit request
Workspace	`.workbuddy/memory/`	Current project	After substantive work

Layer 1: Cloud memory

Auto-injected profile: generated from your long-term usage, prepended to each session. Read-only — manual edits get overwritten.

Conversation search: find a past discussion across sessions. It searches history, so your query must be self-contained — it cannot see the current conversation.

Good for: “what was that approach we discussed for X?” Bad for: your general preferences (those belong in user-level memory).

Layer 2: User-level memory

~/.workbuddy/MEMORY.md applies everywhere.

Write:

Hardware environment
Communication preferences (language, format, how much preamble)
Cross-project constraints (proxy ports, platform account limits)
General workflow habits

Don’t write: details of one specific project — that’s workspace memory.

Keep it to a few thousand characters. This is a set of precise rules, not a log.

Layer 3: Workspace memory

.workbuddy/memory/
├── 2026-09-08.md      # daily log, append-only
└── MEMORY.md          # distilled long-term project notes

Log these (append after substantive work):

What you built or changed
Which technical approach you chose and why
What broke and how you fixed it

Don’t log: raw search results, stack traces, temporary paths. If it has no value three months from now, skip it.

When writing is required

Write after any of:

Built or modified a site/application
Fixed a bug
Wrote a report or document
Completed a refactor or architecture change
Chose a technical approach
The user stated a convention or preference

Skip it for greetings, quick lookups, and short Q&A.

Common mistakes

Mistake 1: treating the log as scratch paper “Fixed a bug” is useless. “Fixed Y in module X — cause was Z, fix was W” is useful.

Mistake 2: overwriting instead of appending Daily logs are append-only. Overwrite today and yesterday is gone.

Mistake 3: not writing at all “I’ll do it later” means rediscovering the same problem next session.

Maintenance cadence

Logs older than 30 days get distilled into MEMORY.md by topic, then deleted. Keep memory small and precise — a 50,000-character memory file is one the AI can’t effectively use either.

The test

What do you wish the AI already knew next time you open a session? That belongs in memory.

Advanced track complete

You now have the four productivity levers — skills, subagents, MCP, automation — plus the memory layer that makes them persist.

Next: the Hands-on track.