claudeers.
// Claude Plugins

gemkeeper

Never kill a good Claude Code session again. A tiny, always-current ledger of mission-critical context that survives /clear and compaction.

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up gemkeeper (claude-plugin project) into my current project.
Found on https://claudeers.com/gemkeeper
Repo: https://github.com/adamoelz/gemkeeper
Homepage/docs: —
Detected install method: claude-plugin → /plugin install gemkeeper@adamoelz/gemkeeper
Category: plugins. Platforms: cli, api.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
unknown; community-verified: false. Confirm the source before running anything.
// or install directly (claude-plugin)

⚠ Unverified / not recently updated — review before pasting a run-this config.

/plugin marketplace add adamoelz/gemkeeper
/plugin install gemkeeper@adamoelz/gemkeeper
// or clone
git clone https://github.com/adamoelz/gemkeeper

// compatibility

Platformscli, api
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageShell

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

gemkeeper

gemkeeper

Never kill a good Claude Code session again.
Claude writes down the 2% of context that matters while it still remembers it,
so you can /clear a bloated session and keep going at full quality.

Install · How it works · Benchmark · Example ledger · FAQ

gemkeeper carries ~2.6k tokens into the next session and still knows 30 of 30 planted facts: 85% fewer tokens than /compact, 98% fewer than no reset

Demo: a rule is saved to the ledger, the session bloats to 146k tokens, /clear, then the same request without gemkeeper adds a forbidden dependency while gemkeeper stops and cites the rule

Quick install

In Claude Code:

/plugin marketplace add adamoelz/gemkeeper
/plugin install gemkeeper@gemkeeper
/reload-plugins

The problem

You finally have a session where Claude gets it. It knows the weird test setup, why you picked SQLite, the three approaches that already failed. Then the context fills up and you have two bad options:

  • Keep going. Quality drifts as the window bloats. Old instructions fade.
  • /clear or let it compact. /clear throws everything away. Compaction keeps a lot, but as a ~17k-token summary that only lives inside this one session: tomorrow's session starts from zero.

Handoff skills help, but they run at the end, when the context is already at its biggest and the details are already blurred.

The fix: a ledger that's written continuously

gemkeeper keeps one short file, .gemkeeper/ledger.md, that Claude updates as things happen:

SectionWhat goes in
MissionThe goal and what "done" means
RulesHard constraints and your stated preferences, marked (user)
DecisionsWhat was decided and why, so the next session doesn't reverse it
Dead endsWhat was tried and why it failed, so nobody wastes an hour retrying it
FactsEnv quirks, the exact command that works, the misleading error
NowCurrent state and the single next step

Every entry has to pass one test: would a fresh session with only the code and this ledger get this wrong? If not, it stays out. That keeps the ledger at around 1–2k tokens instead of turning into another dump. → See a real-looking example

How it works

flowchart LR
    A[You work normally] -->|decision / rule / dead end| B[Claude saves a gem<br/>one small edit]
    A -->|every N prompts| C[checkpoint nudge]
    C --> B
    A -->|context ~100k| D[full sweep +<br/>'safe to /clear']
    B --> L[(.gemkeeper/ledger.md)]
    D --> L
    L -->|/clear · compaction · new session| E[ledger auto-injected]
    E --> A
  • Skill gems. Teaches Claude what counts as a gem, the format, and four modes: capture, sweep, resume, close.
  • SessionStart hook. Re-injects the ledger after /clear, after auto-compaction, and on a new session. After compaction it tells Claude the ledger outranks the compaction summary.
  • UserPromptSubmit hook. When your message looks like it holds a gem (a rule, a reason, a dead end, a gotcha; English and German), a one-line gem check. Otherwise a checkpoint every 6 prompts, plus a single warning when the context passes ~100k tokens (read from the real API usage in the transcript).
  • PreCompact hook. Tells the compactor not to waste summary space on what the ledger already holds.

Plain bash. No dependencies, no network, no telemetry.

Benchmark

Recall after a session reset: gemkeeper vs /compact, handoff and no memory

15 facts are planted in a scripted 20-turn Claude Code session, the session is reset in different ways, and a blind judge scores what the next session still knows (gemkeeper-bench, all raw data and the harness to rerun it):

  • gemkeeper 0.2.1 kept all 15 after a reset into a fresh session, also across two fresh sessions (30/30 in 3 of 3 runs), carrying only ~2.6k tokens into the next session.
  • /compact is strong too (29–30/30) but only inside one session and at ~17k tokens. A handoff summary lost the why and the dead ends (25/30). No memory: 0/30.

gemkeeper 0.2.1 (8979dab), Sonnet via claude -p, one synthetic scenario; limitations in the results.

Install

This is the version the benchmark measured. Only this one loads the ledger automatically after /clear, compaction and in new sessions, and reminds Claude to save gems while you work. Run the three commands from the Quick install in Claude Code (or simply start a new session instead of /reload-plugins).

Check that everything loaded: /hooks should list three gemkeeper hooks (SessionStart, UserPromptSubmit, PreCompact), and /gemkeeper:gems should autocomplete. If Claude Code mentions two unset options, there's nothing to do: the defaults apply (checkpoint every 6 prompts, sweep warning at ~100k tokens, see Configuration).

Keep it up to date: plugins from third-party marketplaces don't auto-update by default. Turn it on once under /plugin → Marketplaces → gemkeeper → Enable auto-update, or update by hand with claude plugin update gemkeeper@gemkeeper, then /reload-plugins.

Other ways (fewer features)

What you getWhat's missing
Skill-only edition (for the Claude plugin directory)Skill + /gemkeeper:resume command, no code runs on your machineNo automatic loading: run /gemkeeper:resume after every /clear or new session. No hook reminders, no token-based sweep warning. Not benchmarked yet.
Skill only via skills.sh, any agent with skills (Claude Code, Cursor, Codex, …): npx skills add https://github.com/adamoelz/gemkeeper --skill gemsThe gems skill; without hooks it checks each message for gems itselfNo automatic loading: ask your agent to "resume from the ledger" after a reset. No token-based sweep warning. Not benchmarked yet.
Manual install of the full version: git clone this repo, then ./install.sh --hooksSame as the recommended pluginUpdates by hand: git pull && ./install.sh --hooks

Install only one of these. The full plugin and the skill-only edition both bring a gems skill.

Usage

Mostly: nothing. Work as usual and Claude captures gems on its own. When you want to reset:

/gems          # full sweep → "Safe to /clear"   (as a plugin: /gemkeeper:gems)
/clear         # fresh context, ledger is injected automatically

Claude then replies with three lines (mission, where we are, next step) and continues.

You sayWhat happens
/gems or "sweep"Full pass: capture missed gems, verify against git, rewrite ## Now, prune
"resume"Restate mission / state / next step from the ledger and check it against git
"close the ledger"Archive it to .gemkeeper/archive/ and start fresh for the next mission

Configuration

Plugin users: /plugin → gemkeeper → configure. Manual install: environment variables.

OptionEnv varDefault
nudge_everyGEMKEEPER_NUDGE_EVERY6Checkpoint every N prompts (0 = off)
warn_tokensGEMKEEPER_WARN_TOKENS100000Sweep warning threshold (0 = off)
GEMKEEPER_LEDGER.gemkeeper/ledger.mdLedger path
GEMKEEPER_MAX_INJECT_LINES250Safety cap on what gets injected

How is this different from…

Built-in /compactHandoff skillsgemkeeper
When context is capturedAt compactionAt the end of the sessionContinuously, while details are fresh
Facts kept after a reset (benchmark)29–30 of 3025 of 30, loses the why and dead ends30 of 30
Survives /clear and new sessionsNoOnly if you paste itRe-injected automatically
Tokens carried into the next session~17k~3k~2.6k
Manual step neededNoYes (copy/paste or command)No

Works well alongside /compact and CLAUDE.md: CLAUDE.md is for project-wide truths, the ledger is for the current mission.

FAQ

Should I commit .gemkeeper/? Your call. Ignored by default (in .gitignore). Commit it if your team should share the context of a mission.

Does it cost tokens? Some. Saving gems while you work adds a few model steps. On a reset the next session starts with the ledger, ~1–3k tokens instead of ~17k for a /compact summary, so you can reset earlier and more often.

Parallel sessions in one repo? gemkeeper uses one ledger per project. Set GEMKEEPER_LEDGER per terminal if you run several missions in parallel.

Windows? Works in Git Bash, which Claude Code uses on Windows.

Contributing

Issues and PRs are welcome, especially real-world "the ledger missed X" reports. They make the ledger test sharper.

If gemkeeper saved one of your sessions, a ⭐ helps other people find it.

License

MIT

// faq

What is gemkeeper?

Never kill a good Claude Code session again. A tiny, always-current ledger of mission-critical context that survives /clear and compaction.. It is open-source on GitHub.

Is gemkeeper free to use?

gemkeeper is open-source under the MIT license, so it is free to use.

What category does gemkeeper belong to?

gemkeeper is listed under plugins in the Claudeers registry of Claude-compatible tools.

3 views
★ 10 stars
unclaimed
updated 1 day ago

// embed badge

gemkeeper on Claudeers
[![Claudeers](https://claudeers.com/api/badge/gemkeeper.svg)](https://claudeers.com/gemkeeper)

// retro hit counter

gemkeeper hit counter
[![Hits](https://claudeers.com/api/counter/gemkeeper.svg)](https://claudeers.com/gemkeeper)

// reviews

// guestbook

0/500

// related in Claude Plugins

🔓

A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.

// pluginsmultica-ai/★ 230,631[ claude ]
🔓

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explainin…

// pluginsanthropics/⟨Python⟩★ 156,472[ claude ]
🔓

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

// pluginsHKUDS/⟨Python⟩★ 58,467◷ Apache-2.0[ claude ]
🔓

financial-services — a Claude ecosystem project on GitHub.

// pluginsanthropics/⟨Python⟩★ 41,409◷ Apache-2.0[ claude ]
→ see how gemkeeper connects across the ecosystem