brainmaxxing: The Claude Code Memory Layer That Refuses to Be a Prompt Dump

Most agent memory projects start with the same assumption: if the model forgets, store more. brainmaxxing takes the opposite view. It asks whether the thing you just learned should be remembered at all, or whether it belongs in a rule, a skill, or a hook that can enforce the behavior without burdening context.

That shift matters. A note is flexible, but a rule is cheaper. A skill is reusable, but a prompt is brittle. brainmaxxing is built around the idea that the best memory system is the one that keeps shrinking the amount of memory it needs to carry.

The repo is three systems pretending to be one

At a glance, brainmaxxing looks like a memory layer for Claude Code. Under the hood, it is a clean separation of concerns: .agents/skills/ for executable behavior, brain/ for durable knowledge, and .claude/hooks/ for lifecycle automation. Each layer answers a different question.

The brain is the long-term surface. The skills are the action surface. The hooks are the glue. That division keeps Claude from mixing up what it should know, what it should do, and what the environment should inject automatically.

Reflect, ruminate, meditate: the learning loop

The heart of the repo is not storage. It is metabolism. brainmaxxing tries to turn each session into a clean learning loop, then route that learning to the lightest possible container.

Reflect is the post-game wrap-up. It scans the session for mistakes, preferences, and repeated friction, then asks a blunt question: can this be a lint rule, script, or runtime check? If yes, it should not become a memory note at all.

Ruminate is the archaeology pass. It mines Claude's JSONL history, batches it, and uses parallel sub-agents to find patterns that were easy to miss in a single conversation. That makes it feel less like note-taking and more like evidence gathering.

Meditate is the cleanup phase. It reviews stale knowledge, identifies contradictions between principles and behavior, and distills cleaner guidance back into the brain. In other words, the system is not just remembering. It is editing its own memory.

Why Obsidian is not a gimmick here

The choice of an Obsidian vault is doing real work. Markdown and wikilinks make the brain legible to both human and machine, which means the memory is not hidden inside an opaque vector store or buried in a giant prompt file.

That transparency changes the relationship between the human and the agent. The human can prune notes, relink ideas, and inspect the graph. The agent gets a memory surface that is structured enough to be useful, but still editable enough to stay honest.

Planning and review keep the agent from freelancing

The execution layer is deliberately narrow. plan forces a planning-only phase before code is written. review turns architectural trade-offs into visible options instead of silent guesswork. The goal is governance, not speed theater.

plan:
  read brain/principles.md
  break work into independently shippable units
  avoid writing code before the shape is clear

review:
  identify severity
  present options A/B/C
  route high-risk choices to the human

This is a subtle but important design choice. The system does not ask Claude Code to be freeform and clever. It asks it to be staged, inspectable, and constrained by process before it touches implementation.

The plumbing makes the whole thing feel alive

The hooks are what turn the repo from a folder of prompts into an actual operating layer. inject-brain.sh loads the brain index at session start. auto-index-brain.sh keeps that index current when the vault changes. The memory map stays fresh without depending on the user to remember maintenance.

That matters because the repo is not optimizing for bigger context windows. It is optimizing for low-friction retrieval. The right knowledge is available when needed, but the agent is not forced to carry the whole library around all the time.

In practice, that means the system behaves less like a chatbot and more like a disciplined assistant with an update cycle. New experience is captured. Durable lessons are routed. Old assumptions are cleaned up. Nothing stays in the wrong form for long.

What brainmaxxing is really optimizing for

The deeper bet is simple: AI memory should be legible, editable, and structurally enforced. If a lesson can become a rule, it should. If it can become a skill, it should. Only after those options are exhausted should it become a note.

That is why brainmaxxing feels more mature than a prompt pack. It is not trying to help Claude Code remember everything. It is trying to make sure Claude Code remembers the right things in the right layer, and forgets the rest on purpose.