agent-memory

Agent Memory (repo-level)

This skill installs a lightweight, git-tracked memory pattern into a repository so that learnings survive across fresh agent sessions. It sets up two things:

1. agent-memory.md at the repo root — a curated, high-signal log of learnings that a cold-start agent would have wanted to know (setup quirks, non-obvious invocations, resolved root causes, dead ends, repo conventions).
2. A block in CLAUDE.md instructing agents to read agent-memory.md at the start of non-trivial work and when stuck, and to append to it when they learn something durable — checking for and resolving duplicate or contradicting entries first, rather than stacking near-identical notes.

The division of labor matters: CLAUDE.md holds the always-loaded behavior (when to read and write), and agent-memory.md holds the accumulated content, read on demand.

Setting it up

Do this directly with your own file tools — read the bundled templates below, then create or edit the files in the target repo. No script is needed; you create the files yourself. Work at the repository root (the top of the project — confirm with git rev-parse --show-toplevel if git is available, otherwise use the project's top directory).

Both steps are deliberately non-destructive — check before you write:

1. Create agent-memory.md at the repo root — only if it's missing.

   • If ./agent-memory.md already exists, leave it untouched. It holds accumulated learnings, and overwriting it would throw them away.
   • If it does not exist, create it with the exact contents of assets/agent-memory.template.md.

2. Add the instruction block to CLAUDE.md — exactly once.

   • Read ./CLAUDE.md (create it if it doesn't exist).
   • If it already contains the marker <!-- agent-memory:start -->, leave it as-is so the block isn't duplicated.
   • Otherwise, append the full contents of assets/claude-md-block.md, preceded by a blank line if the file already has content.