Connecting Korium gives your assistant a memory. It does not give it the habit of using one. This page is how you close that gap, so searching before work and saving after it happen on their own instead of when you remember to ask.
You need Korium connected already. If you have not done that, start with getting started and come back.
Korium carries this page's contents as a guide your assistant can read itself. Say "read the Korium hooks guide and set it up" and it fetches the working recipes, including the three traps below, and wires them. The rest of this page is the same material for a human, and worth reading if you want to know why each piece is shaped the way it is.
Why asking nicely is not enough
Everybody starts the same way: write "always check Korium first" into the instructions file and assume that settles it. It does not, and it is worth understanding why before you build on it.
Written instructions compete for attention with everything else in a long session. Early on they win. Three hours in, with a large task and a full context, they lose, and they lose silently. Nothing announces that the rule stopped being followed.
We learned this on our own work. We had the rule written down, took away the thing that enforced it, and within two days shipped an entire piece of work with nothing saved at all. Nobody noticed until later.
So the pattern is two layers. Written instructions explain what to do and why. Hooks make it actually happen. A hook is a small check Claude Code runs at a fixed moment: before it edits a file, before it finishes, when a subagent is dispatched. It cannot be talked out of running, and it does not get tired.
Write the house rule
Start here anyway. The hooks below are the enforcement, but a hook that blocks with no explanation is infuriating. The written rule is what makes the block make sense.
Put this in your project's CLAUDE.md, adjusting the names to your work:
## Korium memory protocol
Korium is this project's long-term memory. Read it, write to it,
summarise into it. If Korium is unreachable, say so once and carry on.
- Before starting anything substantial: search Korium with one or two
focused queries (the feature, the files, the area) and fold what
comes back into the approach.
- While working: capture decisions, gotchas and reversals as they
happen. Keep each under 500 characters. Importance 0.4 to 0.7.
- Before finishing: capture one summary: what was done, the key
decisions, what is still open. Importance 0.6 to 0.8.
- Always use your own agent name as source_agent. Never file under
another agent's name.Two details are doing real work here. "Search with one or two focused queries" beats "search Korium", because the vague version gets satisfied by one lazy lookup. And naming the importance ranges stops everything arriving at 0.5, which tells the ranking nothing.
Make it search before it works
The first hook. It runs before Claude edits or writes a file, and if nothing has been looked up yet this session, it stops and says so.
You do not have to write this yourself. Paste this to Claude Code in your project:
Add a PreToolUse hook on Edit, Write and NotebookEdit that
blocks the edit if I have not searched Korium yet this session.
Track it with a marker file in the project, set by a PostToolUse
hook on the Korium search tool. The block should explain why and
name the search tool. Only block once per session, then let it
through.Claude writes the script, wires it into your settings, and tells you what it did.
Blocking at the start of every conversation would be intolerable, because most conversations are questions rather than work. The first file edit is the moment work actually begins, and it is the last moment where reading what you already know is still cheap.
Make it save before it finishes
The one that matters most, and the one people skip. A session that changed files and saved nothing has thrown away everything it learned.
Add a Stop hook that checks whether this session changed any
files but never captured anything to Korium. If so, block once
and tell me to capture a summary first: what was done, the key
decisions, and what is still open. Only block once per session.
Track changes and captures with PostToolUse hooks on the edit
tools and on the Korium capture tool.There is one trap worth knowing about, because we fell into it. A save that gets refused, because you hit your monthly limit, still looks like the tool ran. If your hook counts "the tool ran" as success, a session that was refused on every save will finish believing it saved everything.
Ask for the stricter check:
Only count a capture as successful if the response contains a
memory id. A refused save must not count.Brief your subagents
If you use subagents, this is where memory quietly leaks. A subagent gets a fresh context and knows nothing about your house rules, so it does the work, learns something useful, and hands back a summary while the lesson evaporates.
Add a PreToolUse hook on the Agent tool that blocks if the
subagent prompt does not tell it to search Korium first and
capture what it decides, using its own name as source_agent.
And add a SubagentStop hook that blocks once if the subagent
changed files without capturing anything.The first half is the one people miss. The fix is not to remind the subagent once it is running, it is to refuse to dispatch a subagent whose instructions never mentioned memory.
Tools arrive with a prefix built from whatever you named the connection, so mcp__korium__agent_search on your machine may be mcp__claude_ai_Kyroco__agent_search on someone else's. There is no spelling that is right everywhere.
That matters twice over here. If the hook matches on a guessed name it never fires. If the hook's message names a guessed tool, and that message gets pasted into a subagent prompt, you have just told the subagent to call something it does not have. It fails, or worse, skips the step and reports success. Ask for a loose match on the ending, and for messages that say "the Korium search tool" rather than a full name.
The one rule that matters: never hold a session hostage
Everything above blocks. That is the point. But a gate that blocks forever turns a service blip into a work stoppage, and you will disable the whole thing the first time it happens at the wrong moment.
So every one of these hooks refuses once and then stands aside. The first attempt is stopped with an explanation. The second goes through.
That sounds like it defeats the purpose. It does not, and this is the most useful thing on this page. The block is not a lock, it is a tap on the shoulder at exactly the right moment. Almost every time, being stopped once is enough: the summary gets written because it was asked for while the work was still fresh. And on the rare occasion Korium is unreachable, or you genuinely have nothing worth saving, you are not stuck.
Add "block once per session, then allow" to every hook request. Without it you will get a hook that blocks every time, and you will turn it off within a day.
The same thinking applies when you are out of room. Once you hit a limit, no amount of retrying inside that session will work, so a gate that keeps blocking is punishing you for something you cannot fix from there. Ask for it to stand aside on a quota refusal and tell you plainly instead.
What good looks like
Once this is running, a working session has a shape:
- It opens by remembering. Before touching anything, your assistant looks up what is already known about the area and says what it found.
- It records as it goes. Decisions and surprises get saved while they are still fresh, not reconstructed at the end.
- It closes by summarising. One memory covering what happened, what was decided, and what is still open.
- The next session starts warm. A fresh conversation, days later, opens knowing what the last one concluded.
That last one is the whole return. Everything before it is setup.
If it nags too much
The usual complaint is that the search gate fires on trivial edits. Fix it by narrowing where it applies rather than by turning it off:
Change the Korium search gate so it only fires on edits under
src/ and lib/, and skips docs, tests and config.The other common one is memories arriving too thin to be useful. That is not a hook problem, it is an instruction problem: go back to your CLAUDE.md and be specific about what a good capture contains. "Capture decisions" produces "changed the config". "Capture the decision and the reason it was chosen over the alternative" produces something worth reading in six months.
And if you want to see whether any of this is working, ask:
Show me what has been saved to Korium this week, grouped by
agent name.A week with a lot of edits and three memories tells you the protocol is not binding, whatever the instructions say.
Where to go next
What you can store
Every field on a memory, so your captures carry what recall needs.
Everything Korium can do
All fourteen tools and when to reach for each.