memory-and-plans
Skill2 starsChanged 2 months agoMITView on GitHub
How the two memory systems on this machine resolve on disk, why per-agent stores are project-scoped and must never be consolidated upward or committed, and why claude-mem was removed. Load before creating, moving, consolidating or gitignoring any memory store, or before proposing a third place to keep session knowledge.
In this repository11 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- ci-and-branch-protectionSkill
- claude-md-hygieneSkill
- design-critiqueSkill
- design-directionSkill
- design-tellsSkill
- portfolio-conventionsSkill
- python-uvSkill
- scheduled-jobsSkill
- testing-conventionsSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
Do not duplicate across them.
- Very specific: line 59
Every repo with a store needs .claude/agent-memory/ in .gitignore — that path, never the whole .claude/ directory.
- Distinctive: line 68
Check both directions after narrowing:
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Memory and plans — the reasons
The rules live in ~/.claude/CLAUDE.md. This skill holds the mechanics.
Two systems, one role each
| system | location | holds |
| auto-memory | ~/.claude/projects/-Users-{username}-Dev/memory/, indexed by MEMORY.md | session handoffs, durable cross-session knowledge — user preferences, project state, feedback |
| per-agent memory | <project root>/.claude/agent-memory/<agent>/ | operational knowledge scoped to ONE agent: patterns, past corrections in that agent's domain |
Do not duplicate across them.
Do not call auto-memory "agent memory". The bare phrase collides with the per-agent system's actual name and has caused real confusion.
Plans are not a memory system. They live in ~/.claude/plans/, never in a repo
(project repos under ~/Dev; the private my-config-backup repo is the plans backup).
How the memory: frontmatter key resolves
An agent definition's memory: key resolves as:
| value | resolves to |
user | ~/.claude/agent-memory/<agent>/ |
project | <project root>/.claude/agent-memory/<agent>/ |
local | <project root>/.claude/agent-memory-local/<agent>/ |
Every agent that declares it declares project. None declares user.
Why per-agent stores are scattered, and why that is correct
Because the key resolves against the project root of the session that ran, a store appears wherever a session's project root happened to be:
- one per repo
- plus one per nested working directory a session was launched from (e.g.
<repo>/client/) - plus one per worktree
Anything under ~/.claude/agent-memory/ is residue from sessions whose project
root was ~/.claude — not a separate tier.
Do not "consolidate" them upward. That fights the resolver, and the agent will simply not find what you moved.
Per-agent memory must never be committed
The harness default-ignores only agent-memory-local/, not agent-memory/. So a
repo trusting that default will happily stage its memory files.
Every repo with a store needs .claude/agent-memory/ in .gitignore — that path,
never the whole .claude/ directory.
Repos that deliberately track other .claude/ content are the model here: a
committed project CLAUDE.md, shared commands, or project skills. Ignore
.claude/agent-memory/ specifically rather than the whole directory. A wholesale
.claude/ ignore silently makes any project skill written there untracked and lost
on a fresh clone.
Check both directions after narrowing:
git check-ignore -v .claude/skills/x/SKILL.md # must report NOTHING
git check-ignore -v .claude/agent-memory/x # must still report a matchsettings.local.json is already covered globally by ~/.config/git/ignore.
claude-mem was removed on 2026-07-25 (decision M13)
It was a third system holding session narrative and observation history.
It went unretrieved through a five-hour, 27-repo review while costing ~1.4 GB on disk
and a $CMEM injection at every session start.
Do not reinstall it. And do not compensate by writing session narrative into the two systems above — that narrative already lives in the transcripts.
The portrait is a third place, and why it is not claude-mem
~/.claude/portrait.md is a stable portrait of the owner: who he is, how he works,
what he likes. The global CLAUDE.md imports it into every session with
@portrait.md, inside a SYNC-PRIVATE region.
It is retrieved by import, not by search — the opposite of claude-mem, which stored session narrative and was never retrieved. Same rule as above: session narrative still never goes there; it lives in the transcripts.
The import is a tax on every session, and claude-md-weight.sh does not follow
imported files. So ~/.claude/scripts/portrait-check.sh bounds it, and owns the
threshold: read the number there, never restate it here.
The weekly consolidation (portrait-consolide.sh) only proposes changes drawn
from the week's auto-memories; it never writes the portrait. The owner applies or
dismisses each proposal from /portrait, where the size check runs after the write.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.