I built a Claude skill that gives my AI agent a second brain

An agent pointed at scattered Slack threads and half-organized notes is a confident hallucination machine. So I built the fix: a small Claude skill that gives an agent one structured place to capture what it learns — and a rule to read it before every action.

Same model. Better grounding. Here's the whole thing — copy it, use it, fork it.

What it does

Four steps. Retrieve runs every turn; the rest fire when the condition hits.

1. Capture — every decision, fix, and user correction logged the turn it happens, timestamped.
2. Organize — flat folders, never nested; tag inline.
3. Connect — one index.md maps every file.
4. Retrieve before acting — grep .brain/ before non-trivial steps. A prior entry that contradicts the model wins.

The other three steps exist only to make the fourth return the right thing.

The skill (SKILL.md)

---
name: agent-second-brain
description: "Give your AI agent a structured knowledge foundation so it stops hallucinating from scattered context. Use when the agent keeps re-asking things you already answered, invents facts when context is missing, or you want a durable project memory. Implements a capture → organize → connect → retrieve-before-act protocol over a local `.brain/` folder."
---

# agent-second-brain

An agent pointed at scattered Slack threads and half-organized notes is a confident hallucination machine. This skill gives the agent one place to capture what it learns, structure it for retrieval, and read it **before acting** — so answers are grounded in what you actually decided, not what the model guesses.

Zero dependencies. Pure markdown + the agent's own file tools. Works in Claude Code, any agent harness with file access, or as a human checklist.

## The protocol

Four steps. **Retrieve** runs every turn; the others run when the condition fires.

### 1. CAPTURE — when you decide, fix, or learn something non-obvious
Append a one-line entry to the matching log the same turn it happens. Never trust the model to "remember" it later.

- A decision made → `.brain/decisions.md` (one row: date · context · decision · why)
- A recurring how-to / SOP → `.brain/sops/<area>.md`
- A domain fact (refund policy, rate limits, naming conventions) → `.brain/domain/<topic>.md`
- A correction from the user → `.brain/corrections.md` (this is gold — it's what they'll otherwise have to repeat)

Format is irrelevant; **recency + findability** are everything. Timestamp every entry.

### 2. ORGANIZE — keep it shallow and searchable
Three folders, no deeper. Deep nesting kills retrieval.

.brain/ decisions.md # append-only log, newest at bottom corrections.md # things the user had to say twice — read this first sops/ # how we do X, one file per area domain/ # facts about the world / the system index.md # the map (see CONNECT)

Tag with `#hashtags` inline. FTS over a flat folder beats a clever taxonomy every time.

### 3. CONNECT — maintain `index.md`
One file that lists every other file with a one-line "what's in here + when it matters." This is the entry point the agent reads first. If a fact isn't reachable from `index.md`, the agent won't find it.

```markdown
# Brain index
- decisions.md — every call we made and why. Read before reversing a prior call.
- corrections.md — user corrections. READ FIRST every turn.
- sops/deploy.md — how we ship. Read before any deploy step.
- domain/provider-limits.md — GLM/Twitter/etc rate limits. Read before bulk API work.

4. RETRIEVE BEFORE ACTING — every turn

Before answering a question or running a non-trivial step, the agent greps .brain/ for keywords from the request. If a relevant entry exists, read it and cite it. If the entry contradicts the model's first instinct, the entry wins.

This is the whole point. The other three steps only exist to make this one return the right thing.

When to use

• The agent asks you to repeat something you already told it.
• You're about to say "we already decided X" — that decision should be in decisions.md.
• The agent invents a config value, path, or policy it can't cite.
• Starting a session on a project you'll touch again.

When NOT to use

• One-off questions with no future value.
• Facts that will be stale in a week (put those in chat, not the brain).
• Anything already encoded in code, CLAUDE.md, or git history — the brain is for the gap between those.

Install / bootstrap

Drop this folder into a project and seed the starter files:

mkdir -p .brain/sops .brain/domain
cp STARTER.md/sections into .brain/   # see STARTER.md

Then add one line to the project's CLAUDE.md:

Before non-trivial actions, grep .brain/ for relevant prior decisions/corrections and honor them.

That single instruction is what makes the brain load-bearing. Without it, the files are just notes.

Why it works (the two-minute thesis)

LLMs reward expertise — but only the expertise you've structured. An agent inherits whatever knowledge it can retrieve at call time; everything else is filled with plausible nonsense. A 5-file .brain/ with a retrieve-before-act rule turns "the model's best guess" into "what we actually decided, last Tuesday, and why." The model is the same. The grounding changes.

Foundation first. Agents second.

## The starter files (`STARTER.md`)

```markdown
# Starter files for agent-second-brain

Copy these into `.brain/` to bootstrap a project brain. Edit freely — the shape matters more than the wording.

## .brain/decisions.md

```markdown
# Decisions log
Newest at the bottom. One row per call.

| Date | Area | Context | Decision | Why |
|------|------|---------|----------|-----|
| 2026-08-13 | infra | bot 429ing on GLM | raised backoff base 2s→15s | old floor exhausted retries before reset window |

.brain/corrections.md

# Corrections (READ FIRST)
Things the user had to say more than once. Each entry is a future hallucination prevented.

- [2026-08-13] Mike Futia posts must ship a real artifact (skill/code/md), not a hot take. Link to the thing.

.brain/index.md

# Brain index
Entry point. If a file isn't listed here, the agent won't find it.

- decisions.md — every call we made and why. Read before reversing a prior call.
- corrections.md — user corrections. READ FIRST every turn.
- sops/<area>.md — how we do recurring work. One file per area.
- domain/<topic>.md — facts about the system/world.

.brain/sops/_template.md

# SOP: <area>
When this applies: <trigger>

1. <step>
2. <step>

Gotchas:
- <thing that bit us>

.brain/domain/_template.md

# Domain: <topic>
Verified: <date + source>

- <fact>
- <fact>

The one-line CLAUDE.md addition

Before non-trivial actions, grep .brain/ for relevant prior decisions/corrections and honor them.

Without that instruction, the files are inert. With it, retrieval becomes a reflex and the brain becomes load-bearing.

```

Make it load-bearing

Drop the files into .brain/, then add one line to your CLAUDE.md:

Before non-trivial actions, grep .brain/ for relevant prior decisions/corrections and honor them.

Without that instruction, the files are just notes. With it, retrieval becomes a reflex and the brain becomes load-bearing.

LLMs reward expertise — but only the expertise you've structured. Foundation first. Agents second. MIT licensed.

Get it on GitHub: PeterCHK/agent-second-brain — MIT licensed, zero dependencies. Fork it, use it, tell me what broke.