Letta Memory

Three-layer persistent memory for agents. No more starting from zero every session.

Architecture

Core Memory (memory/core.md)

Compact (~500-1000 words), always loaded. The agent's "working memory".

Structure

# Core Memory

## Identity
- Agent name, personality, role

## User
- Name, preferences, communication style, key facts

## Active Context
- Current projects, recent events, pending tasks

## Quick Reference
- Frequently needed info (medications, schedule, credentials refs)

Rules

• Keep under 1000 words — trim when it grows
• Edit directly when learning something new about user or context
• Move stale items to archival (don't delete, archive)

Archival Memory (memory/archival/)

Long-term storage organized by topic. Searched, not loaded.

Structure

memory/archival/
├── people/          # People and relationships
├── projects/        # Project details and decisions
├── decisions/       # Important decisions made
├── learnings/       # Lessons learned
└── reference/       # Facts, procedures, how-tos

Writing archival entries

# [Topic] — YYYY-MM-DD

## Summary
One-line description

## Details
Full context

## Tags
comma, separated, tags

Reading archival

Use memory_search to find relevant archival entries. Never load all archival files at once.

Automatic Behaviors

On session start

1. Read memory/core.md
2. Read today's memory/YYYY-MM-DD.md if exists
3. If user context seems incomplete, search archival for relevant info
4. Never ask questions that core memory already answers

During conversation

• When user shares new personal info → update core immediately
• When important decision made → write to archival
• When user says "remember this" → write to appropriate layer
• When correcting a mistake → update core or archival

On heartbeat

• Review recent memory/YYYY-MM-DD.md files
• Promote repeated archival entries to core
• Trim core when >1000 words
• Consolidate duplicate archival entries

Memory Operations

Core → Archival (demotion)

When core grows too large or items become stale:

1. Move item to appropriate archival file
2. Replace in core with brief reference (e.g., "See archival: projects/locatering")
3. Keep core scannable

Archival → Core (promotion)

When archival info is needed repeatedly:

1. Move or copy key facts to core
2. Keep archival entry with cross-reference
3. Promotion triggers: mentioned 3+ times in a week, needed at session start

Session → Archival (consolidation)

At natural breakpoints or heartbeat:

1. Read today's daily notes
2. Extract decisions, new info, lessons
3. Write to archival with proper tags
4. Update core if warranted

Initialization

First run? Set up the structure:

mkdir -p memory/archival/{people,projects,decisions,learnings,reference}

Create memory/core.md if it doesn't exist:

# Core Memory

## Identity
- [Agent fills this in]

## User
- [Agent fills this in]

## Active Context
- [Agent fills this in]

## Quick Reference
- [Agent fills this in]

Scripts

scripts/consolidate.py

Consolidates daily notes into archival entries. Run during heartbeats or manually.

python3 scripts/consolidate.py --days 7 --workspace /path/to/workspace

Options:

• --days N — look back N days of daily notes (default: 7)
• --workspace PATH — workspace root (default: current dir)
• --dry-run — show what would be written without writing

scripts/core-trim.py

Trims core.md when it exceeds the word limit.

python3 scripts/core-trim.py --max-words 1000 --workspace /path/to/workspace

Options:

• --max-words N — maximum words for core.md (default: 1000)
• --workspace PATH — workspace root
• --dry-run — show what would be demoted without editing

Anti-Patterns

• Don't duplicate — same info in core AND archival = waste. Core has summary, archival has detail.
• Don't skip archival — dumping everything in core defeats the purpose.
• Don't forget to consolidate — daily notes pile up. Run consolidation regularly.
• Don't ask what you already know — if core says "Renate takes Desvenlafaxina", never ask about medications.
• Don't store secrets in core — use archival/reference at minimum, prefer TOOLS.md for credentials.