mempenny
Keep Claude Code auto-memory lean. Triage (delete/archive/distill) memory files without losing forward-looking truth. Pairs with caveman.
Open source Open in the app JSON README (API)
About
Keep Claude Code auto-memory lean. Triage (delete/archive/distill) memory files without losing forward-looking truth. Pairs with caveman.
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- marcelopaniza
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 2
- Last push
- 2026-08-20T11:11:39Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
marcelopaniza/mempenny/mempenny
README
# MemPenny <p align="center"><img src="docs/mempenny-banner.svg" alt="MemPenny — memory hygiene for AI coding agents" width="880"></p> **One memory, every AI. Shared memory management for all your coding agents — organized, lean, and reversible.** [](LICENSE) [](CHANGELOG.md) [](#install) [](SECURITY.md) [](locales/README.md) Your agent's memory grows. Old notes pile up and the signal gets buried. MemPenny doesn't just tidy once — it does three things: 1. **Organize** — every note lands in a small, fixed set of topic files. A 3-level structure (one-line index → topic files → entries inside) keeps things from sprawling into hundreds of one-off notes; a cold agent finds anything in three file-opens. 2. **Clean** — drop what's stale, archive the historical, distill the bloated to a line or two, kill duplicates, split the over-grown into an index + pages, and flag files that contradict each other. 3. **Keep it cleaned** — set a schedule (daily / weekly / once) and the next session opens on a tidy directory. Backup-first, fully reversible. ## How memory is organized Every tidy memory settles into the same fixed shape — so a cold agent always knows where to look: <p align="center"><img src="docs/mempenny-structure.svg" alt="How MemPenny organizes memory: an index pointing at 8 fixed topic files, each holding entries; logs auto-archive by year" width="880"></p> ## One memory, every AI Use more than one AI? Most of us do — one for coding, another for a second opinion, next month's favorite after that. Normally each keeps its own notes, so every switch starts from zero: new assistant, blank memory, explain the whole project again. MemPenny keeps your memory in plain, organized markdown that any AI can read — one memory, not one per vendor: - **Switch models freely.** The next model opens the same files and picks up where the last one left off. Nothing to re-explain. - **Second opinions arrive briefed.** Ask another AI to help mid-project — point it at your memory folder and it knows the goal, the decisions, the gotchas. - **Never locked in.** Your memory is markdown on your disk, not a vendor database. Change tools next month; it comes along. On **Claude Code** and **opencode** this is automatic — same memory directory, same commands, zero setup. Every other supported agent (Codex, Gemini, CodeWhale, Swival, Cursor, Windsurf, and friends) gets the rules-only tier: [`AGENTS.md`](AGENTS.md) carries the same rules, the same safety net, and the memory folder's location — and most of these hosts now read `AGENTS.md` natively, so a second AI is briefed the moment it opens the project. The copied rules files carry the same folder pointer for hosts that want one. ## Before / after | | Files | Size | |---|---:|---:| | Before | 424 | 1,247 KB | | After | 227 | 458 KB | | **Change** | **−46%** | **−63%** | A real second-pass run on a real memory directory. Full case study: [docs/real-world-results.md](docs/real-world-results.md). ## Two ways to use it - **Clean now** — one command. You see the proposal, you say yes, done. A minute or two. - **Set a nap** — pick a schedule (daily / weekly / once). MemPenny tidies on your next session. Backup-first, no prompts, fully reversible. ## Install **Claude Code** ``` /plugin marketplace add marcelopaniza/mempenny /plugin install mempenny@mempenny /reload-plugins ``` **opencode** (available from v1.2.0) ```bash git clone https://github.com/marcelopaniza/mempenny.git cd mempenny && git checkout v1.7.0 ./install/opencode.sh ``` Commands are `/mempenny-clean`, `/mempenny-nap`, `/mempenny-restore`, `/mempenny-memory-*` (hyphen, not colon). If you also run Claude Code in this project, the two hosts share the same memory directory and config automatically — zero setup. **Other agents** — MemPenny ships the native adapter file each host expects (a plugin manifest, a rules file, or a skill) plus `AGENTS.md` at the root. Pick your host: | Host | Install | |---|---| | Codex | `codex plugin marketplace add marcelopaniza/mempenny`, then `/plugins` → install mempenny, then `/hooks` → trust the nap hook | | Gemini | `gemini extensions install https://github.com/marcelopaniza/mempenny` (the nap hook ships with the extension) | | Antigravity (`agy`) | `agy plugin install https://github.com/marcelopaniza/mempenny` | | Devin | `devin plugins install marcelopaniza/mempenny` | | Hermes | `hermes plugins install marcelopaniza/mempenny --enable` | | OpenClaw | `clawhub install mempenny` | | Swival | `swival skills add --global https://github.com/marcelopaniza/mempenny` | | Cursor | copy [`.cursor/rules/mempenny.mdc`](.cursor/rules/mempenny.mdc) into your project | | Windsurf (Devin Desktop) | copy [`.devin/rules/mempenny.md`](.devin/rules/mempenny.md) (`.windsurf/rules/` is the legacy fallback path) | | Cline | copy [`.clinerules/mempenny.md`](.clinerules/mempenny.md) | | Kiro | copy [`.kiro/steering/mempenny.md`](.kiro/steering/mempenny.md) into `~/.kiro/steering/` | | Copilot | copy [`.github/copilot-instructions.md`](.github/copilot-instructions.md) into your project | | CodeWhale | nothing to do — reads `AGENTS.md` automatically | Cursor, Windsurf/Devin Desktop, Cline, Kiro, Copilot, Devin, and Hermes all read `AGENTS.md` natively now — for them the copied rules file is an optional distilled extra, not a requirement. These get the **rules-only** tier (strategy, guards, write-time discipline). The scheduled nap reaches further than it used to: full auto-clean on Claude Code, notification (or opt-in auto) on opencode, and a session-start **reminder** on Gemini and Codex — both adopted Claude Code's hook shape, so MemPenny's plugin-shipped hook rides along and nudges a consent-first tidy when a nap is due. Full matrix and rationale: [docs/host-and-model-compat.md](docs/host-and-model-compat.md). ## Supported hosts & models | Host | Clean / Restore | Scheduled nap | |---|:---:|:---:| | Claude Code | ✅ | ✅ auto | | opencode | ✅ | ✅ notify · opt-in auto | | Codex / Gemini | rules-only | 🔔 reminder | | Cursor / Windsurf (Devin Desktop) / Cline / Kiro / Copilot / Devin | rules-only | — | | CodeWhale / Swival / OpenClaw | rules-only | — | On opencode, a due nap fires a desktop notification pointing at `/mempenny-clean`; add `"mode": "auto"` to a schedule entry in `~/.claude/mempenny.config.json` and it starts `/mempenny-clean --yes` in the new session instead. On Gemini and Codex the nap is a reminder: a session-start hook injects a note that the nap is due and the model offers the rules-only cleanup — set the schedule from Claude Code or opencode (`/mempenny-nap`), or by hand in the same shared config. On Codex, trust the plugin's hook once via `/hooks`. MemPenny is tuned on Claude Sonnet/Opus and runs on GLM 4.6+, GPT-5, and Gemini 2.5. **Conservation is non-negotiable on every model** — a scripted check verifies nothing is lost before anything old is deleted. Distillation quality varies by model; see the compat doc for per-model notes. ## Commands | Command | What it does | |---|---| | `/mempenny-clean` | One-shot tidy: triage → show → apply. Backup-first. | | `/mempenny-nap` | Schedule a recurring clean. | | `/mempenny-restore` | Reverse any pass. | | `/mempenny-memory-triage` | Dry-run: propose actions, change nothing. | | `/mempenny-memory-apply` | Apply a triage table. | | `/mempenny-memory-distill` | Shrink one file to its load-bearing lines. | | `/mempenny-memory-curate` | Reduce a topic file entry-by-entry. | | `/mempenny-memory-shard-roll` | Close a finished year into a locked shard. | | `/mempenny-memory-auto-split` | Split an over-ceiling file into an index + verbatim pages. Content-preserving — the fallback when nothing else applies. | Claude Code uses the colon namespace (`/mempenny:clean`, etc.) — same commands, two spellings. ## Safety, in one screen - **Backup-first.** Every change is preceded by a full backup. `/mempenny-restore` reverses anything. - **Nothing lost.** A scripted conservation check runs before any old file is deleted. - **Path-locked.** Tight validation on every path and filename; symlinks refused at sensitive points. - **Off-limits by default.** A `.mempenny-lock` file or a `<!-- mempenny-lock -->` comment opts anything out. Full threat model and every codenamed guard: [SECURITY.md](SECURITY.md). ## Advanced Full command reference, flags, config schema, the topic taxonomy, backup retention, localization, and how it all works under the hood: **[docs/advanced.md](docs/advanced.md)**. What's pending and why: **[docs/ROADMAP.md](docs/ROADMAP.md)**. ## License MIT — see [LICENSE](./LICENSE).