From f0925e4901d91f3c9b586709d6cf38b49925023e Mon Sep 17 00:00:00 2001
From: Evgeny Safronov <division494@gmail.com>
Date: Mon, 4 May 2026 22:34:59 +0300
Subject: [PATCH] chore: improve memory rules to save context

---
 CLAUDE.md | 66 ++++++++++++++++++-------------------------------------
 1 file changed, 21 insertions(+), 45 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 725c7c4ca..eb041987d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -292,64 +292,40 @@ Web UI lives in `web/` (`package.json`, `index.html`, `dist/`).
 
 ## Agent Memory & Feedback
 
-**`.claude/agent-memory/<agent>/`** — per-agent persistent memory (corrections, confirmed approaches, project notes).
-Each agent's directory already exists — agents write to it directly with the Write tool.
-Anything codified in this `CLAUDE.md` should be removed from agent memory to avoid duplication; agent memory holds the "Why" and lessons that are still settling.
+**`.claude/agent-memory/<agent>/MEMORY.md`** — single flat file per agent. No backing files, no YAML frontmatter. The file is auto-loaded into conversation context, so keep it tight.
 
-### Memory file format
-
-Each memory is a standalone `.md` file with frontmatter:
+### Format
 
 ```markdown
----
-name: {{memory name}}
-description: {{one-line description — used to decide relevance, so be specific}}
-type: {{user | feedback | project | reference}}
----
-
-{{memory content}}
-```
+# <agent> memory
 
-### Memory index
+## Rules
+- <imperative rule>. Why: <one-clause reason>.
 
-Each agent maintains a `MEMORY.md` index in its memory directory. `MEMORY.md` is loaded into conversation context automatically — keep it under 200 lines. Each entry is one line under ~150 characters:
+## Project context
+- <fact / pattern>. Why: <one-clause reason>.
 
+## References
+- <external resource>: <where>.
 ```
-- [Title](file.md) — one-line hook
-```
-
-Never write memory content directly into `MEMORY.md` — it is only an index.
-
-### Memory types
-
-| Type | What to store | When to save |
-|------|--------------|--------------|
-| **user** | User's role, goals, preferences, knowledge level | When you learn details about the user that affect how you should respond |
-| **feedback** | User corrections AND confirmed approaches | When user says "don't do X" or confirms a non-obvious approach worked |
-| **project** | Ongoing work, goals, decisions, constraints not in code/git | When you learn who/what/why/when about project work. Convert relative dates to absolute |
-| **reference** | Pointers to external systems (Linear, Grafana, Slack, etc.) | When you learn about external resources and their purpose |
-
-### Feedback and project memory structure
-
-Lead with the rule/fact, then:
 
-- **Why:** the motivation or incident behind it.
-- **How to apply:** when/where this kicks in.
+- One bullet per rule, ≤ 200 chars. No multi-line bodies, no examples, no code fences.
+- All sections optional — omit empty ones.
+- Section determines memory type (rule = feedback, project context = project, references = reference). User-profile facts go under `## Rules` prefixed `User: …`.
 
 ### What NOT to save
 
-- Code patterns, conventions, architecture, file paths — derivable from the codebase.
-- Git history, recent changes — use `git log` / `git blame`.
-- Debugging solutions — the fix is in the code, context is in the commit message.
-- Anything already documented in this CLAUDE.md.
-- Ephemeral task details or current conversation context.
+- Anything already in this `CLAUDE.md` (Coding Conventions, Architecture, etc.) — duplicates waste tokens.
+- Code patterns, file paths, architecture — derivable from the codebase.
+- Git history or recent changes — use `git log` / `git blame`.
+- Debugging fix recipes — the fix is in the code; the commit message has the context.
+- Ephemeral task state.
 
-### Memory hygiene
+### Hygiene
 
-- Check for existing memories before creating new ones — update rather than duplicate.
-- Verify memories before acting on them: file paths may have moved, functions may have been renamed.
-- If a memory conflicts with current code state, trust the code and update or remove the stale memory.
-- A memory that summarizes repo state is frozen in time — prefer `git log` or reading code for current state.
+- Update an existing line in place; never duplicate.
+- Before acting on a memory, verify the referenced file/symbol still exists — trust the code over a stale line.
+- Promote a recurring lesson into this `CLAUDE.md` after 3+ occurrences, then delete its line from agent memory.
 
 ## Key Dependencies