memory-system

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

Type	What to Store	Example
user	Role, preferences, tools, communication style	"Senior DevOps, prefers dark mode"
feedback	What user liked/disliked about agent output	"User said 'too verbose', prefers tables"
project	Coding standards, tech choices, conventions	"Use bun not npm, Tailwind v4"
reference	Non-sensitive infrastructure notes, public URLs, configs	"Prod API hostname and port"

---

What NOT to Save

Don't Save	Why
Secrets, credentials, tokens, passwords, private keys, or API keys	Memory is persistent and may be shared across sessions
Information derivable from code	Read package.json instead of memorizing deps
Temporary debug context	Clutters memory, not useful later
Exact code snippets	Code changes — memory becomes stale
File paths that may move	Use glob patterns or descriptions instead
Entire conversation transcripts	Memory is for distilled insights only

---

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

Artifact	Purpose	Lifespan	Location
Memory	Cross-session knowledge	Permanent until pruned	.agents/memory/
Plan	Task breakdown for current project	Until project complete	Project root
Task	Progress tracker for current session	Until session ends	Artifact directory

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