thinkbetter

Token-efficient persistent project memory for Claude Code. Hook-enforced behaviors, stable entry IDs, reference-counted retrieval that gets sharper the more you use it.

Why

Naive memory systems either dump the whole context (expensive) or rely on the model to remember (unreliable). thinkbetter keeps a compact grep-able file per project, injects only what is actionable, and gets cheaper as references accumulate.

• SessionStart emits zero output on clean sessions.
• UserPromptSubmit injects at most 4 scored hits, deduplicated against what was already shown this session.
• Reference counter promotes hot entries; cold entries quietly stop competing.
• Hot files auto-seed 🌱 stub entries so the log builds itself.
• Errors go to a log file, never to chat.

Install

/plugin install simple11337/thinkbetter

Or clone and install locally:

git clone https://github.com/simple11337/thinkbetter ~/.claude/plugins-local/thinkbetter

Requires Node.js on PATH (the hooks are .mjs scripts).

Quick start

1. Start a session in any project. thinkbetter creates .think-better/context.cb with goal:pending.
2. The first SessionStart injects a directive asking you to set the goal via AskUserQuestion. Answer, then edit the @S line.
3. Work normally. Edits are logged as A lines. After 3 edits and ~30 lines on the same file, a 🌱 stub E entry appears.
4. Refine stubs with /thinkbetter-log <file>. Use /thinkbetter-get <id|#tag|file> for surgical lookups.
5. Check the savings with /thinkbetter-stats.

Format

E<ID>[!|+] <risk> <file:line> <unit> [#tags] | <core> [| flags [| decision]]
A <ts> <file> <action> <span>

• <ID> stable forever: E001, E002 ...
• ! = P0 (always inject), + = P1 (important), no modifier = P2.
• risk: ✓ holds, ⚠ flag, ✗ broken.
• tags: lowercase, no-space, prefixed #. Field is optional.
• flags and decision columns are optional.

Headers:

@S <date> <goal>
@T E:N R:N X:N P0:N A:N

Example entries:

E007! ✗ src/auth.ts:42 loginFn #auth#sec | accepts empty pw | 🐛 critical | 📌 reject in v2
E008 ✓ src/util.ts:10 fmtDate | pads single-digit days
E009+ ⚠ api/users.go:88 ListUsers #api | unbounded query

Commands

Command	Purpose
/thinkbetter-show	session line, stats, P0, and risks
/thinkbetter-get <id|#tag|file|P0|risk|broken>	direct node access via index
/thinkbetter-log [file-or-unit]	promote or refine an entry
/thinkbetter-stats	token estimate, top-cited entries, stub count, last errors
/thinkbetter-compact [days]	drop old A lines (E lines always kept)
/thinkbetter-reset [reason]	archive current session, start fresh

How it scales with use

• Every E line injected via UserPromptSubmit increments a reference counter in .think-better/state.json. The score function adds log2(1 + refs) (capped at 3), so frequently-cited entries surface faster on later prompts.
• Hot files generate stub entries automatically. The first edit costs zero memory tokens; the third edit seeds an entry you can later refine.
• Session dedup ensures the same entry never appears twice in one session.
• Cold entries (no refs after 30+ days) lose the boost and stop competing for the four inject slots.

Net effect: a project with 5 sessions of history behaves like a brand-new memory. A project with 50 sessions of history behaves like a tuned local RAG over your own decisions.

Token math

Rough per-session figures versus a naive 10-line memory dump:

Stage	Naive dump	thinkbetter v0.5
SessionStart, clean session	~400 tokens	0
SessionStart, with 2 P0 + 1 risk	~400 tokens	~70
UserPromptSubmit, no match	~200 tokens	0
UserPromptSubmit, 4 hits	~200 tokens	~90
Format overhead per entry	50-80 tokens	22-30 tokens

Across 100 sessions of moderate use this is on the order of 30,000-80,000 tokens saved, before counting the cost of restated entries that ID references avoid.

Hooks

Four hooks installed by the plugin:

• SessionStart – injects forced question-round directive on goal:pending, then up to 4 actionable entries.
• UserPromptSubmit – scores E lines against the prompt, dedups, injects top hits, increments refs.
• PostToolUse on Edit/Write/MultiEdit – appends A lines with 10-min coalesce, refreshes stats, rebuilds the index, counts edits per file, seeds 🌱 stub entries on hot files.
• Stop – one short systemMessage when broken entries exist, stubs need refinement, or 10+ activities have produced no entries.

All hooks fail open and log to .think-better/errors.log.

State and index

• .think-better/context.cb – the canonical memory file.
• .think-better/index.cb – hook-maintained tag/file/priority/risk → ID buckets for O(1) lookups.
• .think-better/state.json – per-session shown IDs, reference counters, metrics. Never injected.
• .think-better/errors.log – hook failures.

Limitations

• The forced question round is hook-injected but the actual AskUserQuestion call is up to the model. If the model ignores the directive, the goal stays pending and the directive re-fires next session.
• The stealth skill pairing is described in SKILL.md; it is invoked by the model, not the hook.
• Token figures are estimates, not benchmarks.
• The plugin assumes Node.js is on PATH.

License

MIT. See LICENSE.