From 8d08f9650c233d663b791bf78aa54b5b747dbcd6 Mon Sep 17 00:00:00 2001
From: Bryan Ramos <bryan@ramos.codes>
Date: Thu, 2 Apr 2026 08:04:44 -0400
Subject: [PATCH] docs(README): clarify manual memory vs agent memory systems

---
 README.md | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 3424b74..6ca7fb7 100644
--- a/README.md
+++ b/README.md
@@ -69,6 +69,11 @@ Each project repo can extend the team with local config in `.claude/`:
 
 Commit `.claude/` with the project so the team has context wherever it runs.
 
-## Agent memory
+## Memory
 
-Agents with `memory: project` scope write persistent memory to `.claude/agent-memory/` in the project directory. This memory is project-scoped and can be committed with the repo so future sessions pick up where prior ones left off.
+Two memory systems coexist:
+
+- **Manual memory** (`.claude/memory/`) — curated context files with YAML frontmatter, indexed by `MEMORY.md`. Loaded as part of the CLAUDE.md hierarchy on every session. Use this for project decisions, user preferences, and reference pointers.
+- **Agent memory** (`.claude/agent-memory/`) — Claude Code's built-in runtime memory, written automatically by agents with `memory: project` scope. Excluded from CLAUDE.md context via `claudeMdExcludes` to avoid polluting the context window.
+
+Commit both directories with the repo so memory persists across machines and sessions.