mirror of
https://github.com/alirezarezvani/claude-skills.git
synced 2026-09-07 08:26:02 +00:00
733e897402
New engineering/memory-engineering/ plugin. The repo had no skill for designing, pricing, or auditing an agent memory system: llm-wiki maintains one vault, skillopt-sleep runs a consolidation loop, agent-harness bounds a task loop. This bounds a store. Four stdlib scripts, one per lens: - memory_cost_profiler.py — construction vs query split, cost per correct answer, amortization ratio, construction co-location warning - memory_architecture_picker.py — scores the four paradigm families, disqualifies on hard constraints, names the cost the choice makes you pay, and refuses to pick when the top two tie (exit 2 + tie-breaking question) - memory_density_auditor.py — classifies records FACT/SKILL/LOG/PROSE, finds near-duplicates, flags staleness and time-relative wording, scores density; runs on a real --dir or --jsonl - forgetting_policy_linter.py — the gate. 8 checks; F1 (explicit forgetting rule) and F4 (contradictions surfaced, never auto-merged) block at exit 4 Evidence discipline: the four-lens framing is synthesized from @N01ennn's "How to be a Memory Engineer", but every quantitative claim is re-cited to the primary source, and two of the article's paraphrases are corrected in the references rather than propagated — the 47x energy figure is the spread across ten evaluated systems (not an accuracy-matched pair), and the 97% first-pass-error figure is Rakuten's named vendor testimonial (not a controlled study). Per-claim confidence levels throughout. Three classifier defects found and fixed during the build, each of which would have produced garbage on a real repo: markdown headings inside fenced code blocks were splitting records (258 phantom records -> 107 on a real directory); short fragments matched trivially at 1.00 Jaccard (41 false-positive duplicates); and signal-less prose was labeled LOG, firing LOG_HEAVY at 74% on a documentation folder — now its own PROSE class. Also ships 4 references (7 sources each), a seven-question forcing worksheet, a combined example spec consumed by all three spec-taking scripts, an F1–F8 policy template, cs-memory-engineer, /cs:memory-engineering and /cs:forgetting-audit. Verified: all 4 scripts pass --help / --sample / --output json, stdlib-only, correct exit codes on error paths; SKILL.md 6/6 PASS on the write-a-skill checklist; check_plugin_json.py --all and derive_counters.py --check both pass. Counters: skills 362->363, tools 644->648, refs 741->745, agents 102->103, commands 116->118, plugins 88->89. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Jt1sqt5kQmopyfXu2Hhjnv
121 lines
5.5 KiB
Markdown
121 lines
5.5 KiB
Markdown
# memory-engineering
|
||
|
||
> Your agent's problem was never that it forgets. It's that it never forgets
|
||
> **on purpose**.
|
||
|
||
A storer optimizes what a system remembers. A memory engineer optimizes what it
|
||
forgets. This plugin makes that shift executable: four deterministic stdlib
|
||
scripts that price the write path, choose which cost to pay, audit what a store
|
||
actually holds, and **refuse a design with no forgetting policy**.
|
||
|
||
## Why this exists
|
||
|
||
Everyone building agent memory optimizes retrieval. Almost nobody engineers
|
||
what it costs to build, what is worth keeping, who can delete it, and where it
|
||
lands on the hardware. Stanford's systems characterization of ten memory systems
|
||
found the gap concretely:
|
||
|
||
- **Construction energy exceeds total query-phase energy across 300 queries** —
|
||
the bill is paid on the write path you never watch.
|
||
- Energy per correct answer **spreads more than 47×** across systems (BM25 at
|
||
4,145 J; MIRIX at ~197 kJ).
|
||
- At 1M tokens, footprint varies **up to 9×** — and **"none of the evaluated
|
||
systems prune or forget by default."**
|
||
|
||
If you did not build forgetting, you do not have it.
|
||
|
||
## Install
|
||
|
||
```bash
|
||
/plugin marketplace add alirezarezvani/claude-skills
|
||
/plugin install memory-engineering
|
||
```
|
||
|
||
## Use
|
||
|
||
```bash
|
||
/cs:memory-engineering ~/.claude/memory # full four-lens pass
|
||
/cs:forgetting-audit design.json # just the blocking gate
|
||
```
|
||
|
||
Or run the scripts directly — each has `--help`, `--sample`, and `--output json`:
|
||
|
||
```bash
|
||
cd skills/memory-engineering
|
||
|
||
python scripts/memory_cost_profiler.py --sample
|
||
python scripts/memory_architecture_picker.py --sample
|
||
python scripts/memory_density_auditor.py --dir ~/.claude/memory
|
||
python scripts/forgetting_policy_linter.py --sample-failing
|
||
```
|
||
|
||
## The four scripts
|
||
|
||
| Script | Lens | What it does | Exit codes |
|
||
|---|---|---|---|
|
||
| `memory_cost_profiler.py` | Stanford — *what does it cost?* | Splits construction vs query spend, computes **cost per correct answer**, flags under-amortized writes and construction co-located with live queries | 0 · 2 finding · 3 bad input |
|
||
| `memory_architecture_picker.py` | Stanford — *which cost to pay?* | Scores long-context / flat RAG / structure-augmented RAG / agentic against constraints, disqualifies on hard limits, **names the cost you're choosing**, refuses to pick on a tie | 0 · 2 ambiguous · 3 bad input · 4 none viable |
|
||
| `memory_density_auditor.py` | Microsoft — *what's worth keeping?* | Classifies records **FACT / SKILL / LOG / PROSE**, finds near-duplicates, flags stale and time-relative wording, scores knowledge density. Runs on a real directory or JSONL | 0 dense · 2 finding · 3 bad input |
|
||
| `forgetting_policy_linter.py` | Anthropic + the gate | 8 checks; **F1** (explicit forgetting rule) and **F4** (contradictions surfaced, never auto-merged) are **blocking** | 0 PASS · 2 CONDITIONAL · **4 FAIL** |
|
||
|
||
Stdlib only. No network, no LLM calls, no dependencies.
|
||
|
||
## The gate
|
||
|
||
```
|
||
$ python scripts/forgetting_policy_linter.py --sample-failing
|
||
|
||
VERDICT: FAIL (0/8 checks pass)
|
||
This design does not forget on purpose. F1 failed. F4 failed.
|
||
|
||
FAIL F1 explicit forgetting rule [BLOCKING]
|
||
No TTL, no capacity bound, no decay. The store only grows.
|
||
FAIL F4 contradictions surfaced, never auto-merged [BLOCKING]
|
||
Contradiction policy is 'newest_wins', which resolves conflicts silently.
|
||
```
|
||
|
||
**F4 is blocking on purpose.** Two memories that disagree may both have been
|
||
true in different contexts — "deploys go through Jenkins" and "deploys go
|
||
through GitHub Actions" is not a contradiction to resolve, it is a migration to
|
||
record. Auto-merging destroys the only evidence the conflict existed.
|
||
|
||
## Evidence discipline
|
||
|
||
The four-lens framing synthesizes *"How to be a Memory Engineer, from the
|
||
perspective of Stanford, Microsoft, Anthropic and Nvidia"* by
|
||
[@N01ennn](https://x.com/N01ennn/status/2083971749079581120).
|
||
|
||
**Every quantitative claim is cited to the primary source, not to that
|
||
article,** and each carries an explicit confidence level. Two of the article's
|
||
paraphrases are corrected in the references:
|
||
|
||
- The **47×** energy figure is the spread across ten evaluated systems, not
|
||
"two systems with identical accuracy" (`memory_cost_canon.md` §2).
|
||
- The **97%** first-pass-error reduction is Rakuten's named, vendor-published
|
||
customer testimonial — not a controlled study or a general property of
|
||
building memory this way (`memory_control_and_governance.md` §4).
|
||
|
||
## Not this plugin
|
||
|
||
| You want | Use |
|
||
|---|---|
|
||
| Build and maintain one markdown knowledge vault | `llm-wiki` |
|
||
| A nightly self-improvement loop over transcripts | `skillopt-sleep` |
|
||
| Bound an agent's *task loop* | `agent-harness` |
|
||
| Price inference generally | `llm-cost-optimizer` |
|
||
|
||
This bounds a **store**, not a loop and not a vault.
|
||
|
||
## Primary sources
|
||
|
||
- Omri, Y. et al. — *Agent Memory: Characterization and System Implications of Stateful Long-Horizon Workloads*, [arXiv:2606.06448](https://arxiv.org/abs/2606.06448)
|
||
- Microsoft Research — [*PlugMem: A Task-Agnostic Plugin Memory Module for LLM Agents*](https://www.microsoft.com/en-us/research/publication/plugmem-a-task-agnostic-plugin-memory-module-for-llm-agents/)
|
||
- Kontonis, V. et al. — *MEMENTO: Teaching LLMs to Manage Their Own Context*, [arXiv:2604.09852](https://arxiv.org/abs/2604.09852)
|
||
- Anthropic — [*Built-in memory for Claude Managed Agents*](https://claude.com/blog/claude-managed-agents-memory)
|
||
|
||
Full citation lists (7 sources each) are in
|
||
[`skills/memory-engineering/references/`](skills/memory-engineering/references/).
|
||
|
||
## License
|
||
|
||
MIT.
|