agd-memory
Per-project persistent memory for Claude Code,
stored in AGD format with selective
retrieval and graph traversal.
Each project gets its own memory file. The session never loads it whole:
it scans a Table of Contents, picks the relevant blocks, and fetches
them in a single batched call. Typical access costs 6-15x fewer
tokens than loading the whole memory file.
What you get
- SessionStart hook — at session start, injects the TOC of the
project memory into the system context. If the project has no
memory, the hook is a silent no-op.
- Skill (
/agd-memory:memory) — when the user asks "ricordi…",
"what do you remember…", or you need project context, the skill
documents how to read and write the memory.
- MCP server — exposes four tools (
agd_memory_toc,
agd_memory_search, agd_memory_get, agd_memory_save) so the
model can interact with memory through structured calls instead of
shelling out.
All three components are backed by the same agd CLI binary. No
daemon, no broker, no embeddings — a single line-oriented file on
disk.
Prerequisites
-
Claude Code 2.1.138 or newer. Older versions reject the
marketplace github source with This plugin uses a source type your Claude Code version does not support. Run claude update to upgrade,
then claude --version to confirm.
-
agd CLI (>= v0.3.1):
cargo install --git https://github.com/Pinperepette/agd --tag v0.3.1
Verify: agd --version prints agd 0.3.1 or newer.
-
Python 3.10 or newer (for the MCP server). The plugin auto-creates a
private venv under ${CLAUDE_PLUGIN_DATA}/venv on first launch and
installs the mcp package into it — no manual pip step. The venv is
removed automatically on uninstall.
Install
The plugin is distributed through a Claude Code marketplace defined in
the same repo. From a Claude Code session:
/plugin marketplace add Pinperepette/agd-memory
/plugin install agd-memory@agd-memory
Restart the session for the SessionStart hook and MCP server to load.
How it works
Memory file path
Each project's memory lives at:
~/.claude/projects/<sanitized-cwd>/memory/memory.agd
sanitized-cwd is the working directory with / replaced by -. The
hook and MCP server derive this path from pwd automatically — no
configuration needed.
Block format
A memory entry is one AGD block with a stable id and an optional
desc= attribute that is surfaced in the TOC:
@x-feedback desc="no Co-Authored-By in commits" refs="#user-role" [#feedback-no-coauthored]
~~~
Mai aggiungere Co-Authored-By o trailer nei commit Git.
Reason: regola globale del progetto, perduta se la dimentichi.
~~~
Four conventional kinds keep the memory navigable:
x-user — facts about the user (role, blog, style)x-feedback — rules of collaboration (preferences, anti-patterns)x-project — current state of work (decisions, artifacts)x-reference — pointers to external resources (repos, paths)
Preferred access patterns
The wrong pattern is to call get repeatedly in sequence and pay one
parse per call. Three patterns that fold a multi-step retrieval into a
single round-trip:
Scope query — every rule that applies to a topic:
agd get memory.agd '#user-blog' --with-backlinks
Returns the anchor block plus every block that declares
refs="#user-blog". Useful when the user asks about a scoped activity
("I am about to write a blog post — what rules apply?").
Provenance chain — where does this fact come from:
agd get memory.agd '#numbers-block' --follow-refs --depth 3
Walks refs= outbound transitively, cycle-safe.
Topic discovery — when you do not know the id:
agd search memory.agd "blog" -i
Returns matching ids and short excerpts. Feed those ids to a single
agd get batch.
Token economy
Measured on a 37-entry memory file (~4.7k tokens total, 2026-05-09):
| pattern | tokens | savings |
|---|
| whole-doc load | 4,743 | 1x |
| TOC only | ~750 | ~6x |
| TOC + batch of 3 typical blocks | ~340 | ~14x |
| TOC + single-block fetch | ~64 | ~74x |
The ratio scales with corpus size: at 1k entries it sits around 12x
on a 1-block selective fetch; at 10k entries closer to 14x.
Local viewer
A bundled single-page viewer turns the same .agd file into three
views that target three habits people already have:
