Memory System — Persistent Cross-Session Memory

Enables agents to remember across sessions. Never re-discover what was already learned.

Overview

The Memory System provides persistent, searchable memory that survives across sessions. Instead of re-explaining preferences, conventions, and past decisions every time, agents read a structured MEMORY.md index and topic files.

Token Impact: +1,000 tokens to load index, but saves 3,000-10,000 tokens by eliminating re-discovery.

Architecture

.agents/memory/
├── MEMORY.md              ← Lightweight index (max 200 lines)
├── user-preferences.md    ← Topic file: user role, style, tools
├── project-conventions.md ← Topic file: coding standards, patterns
├── tech-decisions.md      ← Topic file: past architectural decisions
├── feedback-history.md    ← Topic file: what user liked/disliked
└── [topic-name].md        ← Additional topic files as needed

MEMORY.md Index Format

The index is a lightweight pointer file — short entries that reference topic files for details.

Rules:

• Maximum 200 lines total
• Each entry: ~150 characters max
• Format: - [type] summary → topic-file.md
• Types: [user] [feedback] [project] [reference]

Example:

# Memory Index

## User
- [user] Prefers dark mode, uses Windows 11, PowerShell → user-preferences.md
- [user] Senior DevOps engineer, 8 years experience → user-preferences.md
- [user] Primary language: English, sometimes Turkish → user-preferences.md

## Project
- [project] Always use bun instead of npm → project-conventions.md
- [project] Tailwind v4 preferred, no v3 → tech-decisions.md
- [project] No purple/violet colors in UI → project-conventions.md

## Feedback
- [feedback] User likes concise responses, no filler → feedback-history.md
- [feedback] User dislikes verbose explanations → feedback-history.md
- [feedback] User prefers tables over bullet lists → feedback-history.md

## Reference
- [reference] Squid proxy runs on port 3128 → infrastructure-notes.md
- [reference] Git workflow: feature branches → main → project-conventions.md

Topic File Format

Each topic file has frontmatter and structured content:

---
type: user | feedback | project | reference
created: 2026-04-01
updated: 2026-04-01
---

# User Preferences

## Development Environment
- OS: Windows 11
- Shell: PowerShell
- Editor: Cursor / Windsurf
- Package Manager: bun (NOT npm)

## Communication Style
- Prefers concise responses
- Likes tables for comparisons
- Dislikes verbose explanations

Memory Taxonomy

What NOT to Save

Operations

Save (Trigger: user says "remember", "save", "don't forget")

1. Identify the information type (user/feedback/project/reference)
2. Check if relevant topic file exists
3. If yes → append to existing topic file
4. If no → create new topic file with frontmatter
5. Update MEMORY.md index with one-line pointer
6. Confirm to user: "Saved to memory: [summary]"

Recall (Trigger: session start, or "what do you remember about X")

1. Read .agents/memory/MEMORY.md index
2. Scan for relevant entries matching the current task
3. If match found → read the referenced topic file
4. Apply recalled context silently (don't recite memories unless asked)

Search (Trigger: "do I have any notes about X")

1. Grep across .agents/memory/*.md for the search term
2. Return matching entries with file references
3. Offer to read full topic file if user wants details

Prune (Trigger: index exceeds 200 lines)

1. Warn: "Memory index is getting large (X lines). Review recommended."
2. Suggest merging related entries
3. Suggest archiving old entries to memory/archive/
4. Never auto-delete — always ask user first

Session Start Protocol

At the start of every session:

1. Check: Does `.agents/memory/MEMORY.md` exist?
   → YES: Read index. Apply relevant context silently.
   → NO: Continue without memory. Create on first "remember" trigger.

2. Apply memory WITHOUT reciting it.
   ❌ WRONG: "I remember you prefer dark mode and use bun..."
   ✅ RIGHT: (silently apply preferences, use bun in commands)

3. Exception: If user asks "what do you remember?" → recite relevant memories.

Memory vs. Plan vs. Task

Memory = what you KNOW. Plan = what you'll DO. Task = what you're DOING NOW.