Autobiographical Memory#

Core Concepts#

Memory has two complementary layers:

LayerFileWhat it storesEpisodicmemory/YYYY-MM-DD.mdRaw daily events, conversations, decisions, observationsSemanticMEMORY.mdCurated knowledge: user preferences, facts, lessons, identity

The memory lifecycle: Capture → Consolidate → Recall → Review

Quick Start#

markdown

# Recording an event (episodic)
Append to `memory/YYYY-MM-DD.md`:
- Met with [person] about [topic]. Decision: [outcome].
- User prefers [preference]. Updated MEMORY.md.

# Recalling before responding
1. Run `memory_search` with relevant keywords
2. If results are thin, read recent `memory/YYYY-MM-DD.md` files
3. Check `MEMORY.md` for long-term facts

# Consolidating (periodic maintenance)
1. Read recent daily files (last 7-30 days)
2. Extract significant items → update MEMORY.md
3. Remove stale entries from MEMORY.md

Episodic Memory — Daily Notes#

What to Record#

Always write to daily notes for:

• Decisions with rationale: "Chose X over Y because Z"
• User preferences discovered implicitly or explicitly
• Important conversations — summary, not transcript
• Mistakes & lessons — what went wrong, what to do differently
• Project milestones — what was done, what's blocked
• Identity changes — if SOUL.md, USER.md, or other self-files changed

What to Skip#

• Routine operations ("checked email, nothing new")
• Transient states ("feeling tired")
• Content better stored elsewhere (code snippets in projects, API keys in config)
• Something the user explicitly said doesn't matter

Format Convention#

markdown

## Events
- [event description]

## Decisions
- [decision + rationale]

## Observations
- [insights or patterns noticed]

## Notes
- [anything else worth remembering]

Semantic Memory — MEMORY.md#

Structure#

text

## User Preferences
- Directly stated preferences without inference

## Project Context
- Active projects and their status

## Relationships & People
- Key people, roles, context

## Technical Environment
- Tools, config, quirks discovered

## Lessons Learned
- Mistakes to avoid, patterns that work

When to Update MEMORY.md#

• User states a clear preference
• A project direction is set
• A mistake teaches a lesson worth preserving
• Every few days during heartbeat: consolidate from daily notes

When to Remove from MEMORY.md#

• Project is done / abandoned
• Preference was explicitly reversed
• Information is now obvious context (e.g. "user speaks Chinese" — that's already in USER.md)
• Stale for >3 months without reference

Consolidation Workflow#

Suitable for heartbeat routines. Do this every 3-7 days:

text

1. List memory/*.md, sort by date (newest first)
2. Read files since last consolidation
3. For each significant item:
   a. Is it already in MEMORY.md? → Skip or update
   b. Is it transient? → Skip (leave in daily note)
   c. Is it important? → Add to MEMORY.md
4. Read MEMORY.md for stale entries → remove or archive
5. Write updated MEMORY.md

Recall Strategy#

Before answering questions about prior work, people, preferences, or context:

1. Search first: memory_search(query="relevant terms") — this searches both daily notes and MEMORY.md
2. Narrow scope: If search returns weak results, try multiple query phrasings
3. Deep dive: For specific periods, memory_get(path="memory/YYYY-MM-DD.md") to read raw daily notes
4. Cross-reference: Check USER.md, SOUL.md, TOOLS.md for identity/preference info

When Recall Fails#

• Say clearly "I checked my records and don't have information about that"
• Don't fabricate memories
• If the user says "don't you remember? I told you X" — apologize and record it properly this time

The Forgetting Curve#

Not everything needs to persist. Use these filters:

• Keep in daily notes: Everything noteworthy for 30-90 days
• Promote to MEMORY.md: Only what's likely to be needed again
• Delete/archive: What's clearly obsolete after review

References#

• For detailed consolidation scripts: see references/consolidation.md
• For memory search patterns: see references/recall-patterns.md

Scripts#

• scripts/consolidate.py — Scan recent daily notes and suggest MEMORY.md updates
• scripts/stats.py — Memory file statistics (sizes, dates, coverage)