# Brainless

> Brainless (没脑子) — ALWAYS ACTIVE. Your external brain. You don't need memory, I remember EVERYTHING for you. A persistent knowledge management system for errors, CTF challenges, reverse engineering, tricks, and tool usage. CRITICAL BEHAVIORAL RULES (enforce even when skill body is not loaded): (1) ON ANY non-zero exit code or unexpected error: IMMEDIATELY invoke /brain-search BEFORE attempting fixes — check if this problem was solved before; (2) AFTER resolving any non-trivial error (not a simple typo): IMMEDIATELY invoke /brain-dump to record the problem and solution BEFORE continuing to the next step — do NOT wait until the task is finished or the user asks; (3) NEVER batch recordings — record each issue individually as it is resolved. Also covers: CTF writeups (pwn/web/crypto/rev/misc), IDA/Ghidra reversing notes, useful tricks, tool techniques. Triggers: '/brain-dump', '/brain-search', '/brain-review', '/brain-cheatsheet', '/brain-stats', '/brain-rebuild', 'record this', 'have we seen this', any error/warn

- Skill: `imcoriander/brainless` (Agent Skill)
- Install (CLI): `npx skillmds@latest add imcoriander/brainless`
- Raw SKILL.md: https://api.skillmd.com/api/skills/imcoriander/brainless/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ImCoriander (https://skillmd.com/u/imcoriander)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/imcoriander/brainless

---


# Brainless — Your External Brain

> *"You don't need a brain. I remember everything for you."*
> *"你不需要脑子。我帮你全记着。"*

A persistent, categorized knowledge base that records errors, solutions, CTF challenge writeups, reverse engineering notes, useful tricks, and tool techniques. Builds up automatically over time so that previously solved problems are never re-investigated from scratch.

**Philosophy:** Be brainless. Don't waste neurons remembering things that can be recorded. Offload your memory to me and focus on what matters — solving the next problem.

## Storage Location

All records are stored in `~/.claude/brainless/`:
- `INDEX.md` — master index with all entries organized by category
- `_cache.json` — lightweight JSON cache for fast search
- Category subdirectories (see below)
- Each entry is a single `.md` file in its category directory

## Categories

### Development Errors
| Category | Directory | Scope |
|----------|-----------|-------|
| `build` | `build/` | Compilation, linking, build system errors |
| `runtime` | `runtime/` | Crashes, panics, runtime exceptions |
| `config` | `config/` | Configuration, environment, settings issues |
| `network` | `network/` | Connection, timeout, DNS, API errors |
| `dependency` | `dependency/` | Package version conflicts, missing deps |
| `permission` | `permission/` | File/directory/system permission issues |
| `logic` | `logic/` | Business logic bugs, incorrect behavior |

### Security & RE
| Category | Directory | Scope |
|----------|-----------|-------|
| `ctf` | `ctf/` | CTF challenge writeups — pwn, web, crypto, reverse, misc, forensics |
| `reversing` | `reversing/` | IDA/Ghidra analysis notes, deobfuscation, unpacking, anti-debug bypass |
| `exploit` | `exploit/` | Exploit development techniques, shellcode, ROP, heap tricks |

### Knowledge & Techniques
| Category | Directory | Scope |
|----------|-----------|-------|
| `tricks` | `tricks/` | Useful non-obvious techniques worth remembering |
| `tools` | `tools/` | Tool usage tips — IDA, Ghidra, gdb, Wireshark, Burp, etc. |
| `other` | `other/` | Anything that doesn't fit above |

---

## Record Templates

### Template A: Error Record (build/runtime/config/network/dependency/permission/logic)

```markdown
---
title: [Concise error description]
type: error
category: [category]
tags: [tag1, tag2, tag3]
created: [YYYY-MM-DD]
last_hit: [YYYY-MM-DD]
hit_count: 1
severity: [low/medium/high/critical]
related: []
---

## Error Message
\```
[Exact error output]
\```

## Environment
- Project: [project name]
- Toolchain: [compiler/runtime version]
- OS: [operating system]

## Root Cause
[Brief explanation of why this error occurred]

## Solution
[Step-by-step fix]

## Related Files
- `path/to/file:line`

## Notes
[Any additional context, gotchas, or related issues]
```

### Template B: CTF Writeup (ctf)

```markdown
---
title: [Challenge name — CTF competition name]
type: ctf
category: ctf
tags: [pwn/web/crypto/reverse/misc/forensics, difficulty, technique-keywords]
created: [YYYY-MM-DD]
last_hit: [YYYY-MM-DD]
hit_count: 1
difficulty: [easy/medium/hard/insane]
ctf_category: [pwn/web/crypto/reverse/misc/forensics]
solved: [true/false]
related: []
---

## Challenge Description
[Brief challenge description, what was given]

## Initial Analysis
[First observations, what tools were used to examine]

## Wrong Approaches (What Didn't Work)
1. [Approach 1] — why it failed
2. [Approach 2] — why it failed

## Solution
[Step-by-step solution that worked]

## Key Insight
[The critical "aha" moment — the non-obvious realization that led to the solve]

## Tools Used
- [tool1]: [how it was used]
- [tool2]: [how it was used]

## Flag
\```
[flag if applicable]
\```

## Lessons Learned
[What to remember for next time — patterns, techniques, gotchas]

## References
- [links to relevant resources, similar challenges]
```

### Template C: Reversing Note (reversing)

```markdown
---
title: [Concise description of the RE challenge/technique]
type: reversing
category: reversing
tags: [ida/ghidra, technique, binary-type, arch]
created: [YYYY-MM-DD]
last_hit: [YYYY-MM-DD]
hit_count: 1
target: [binary name or type]
arch: [x86/x64/arm/arm64/mips]
related: []
---

## Target
- Binary: [name/type]
- Protection: [packer, obfuscation, anti-debug methods]
- Architecture: [x86/x64/arm/...]

## Problem
[What was confusing or blocking analysis]

## Analysis Process
[Step-by-step analysis — what was examined, in what order]

## Key Findings
[Important structures, algorithms, patterns discovered]

## Solution / Technique
[How the problem was resolved — specific IDA/Ghidra operations, scripts, etc.]

## IDA/Ghidra Notes
- [Specific operations, scripts, or plugins used]
- [Struct definitions, type assignments that helped]

## Patterns to Recognize
[Signatures or patterns that identify similar problems in the future]

## Notes
[Additional context]
```

### Template D: Exploit Technique (exploit)

```markdown
---
title: [Exploit technique name]
type: exploit
category: exploit
tags: [pwn, technique-type, protection-bypass]
created: [YYYY-MM-DD]
last_hit: [YYYY-MM-DD]
hit_count: 1
difficulty: [easy/medium/hard]
related: []
---

## Technique
[Name and brief description]

## Prerequisites
[What conditions must be met — vulnerable function, leak primitive, etc.]

## Protection Bypasses
[What mitigations this bypasses — ASLR, NX, canary, PIE, etc.]

## Step-by-Step
1. [Step 1]
2. [Step 2]
...

## Code Snippet
\```python
[Exploit template / key snippet]
\```

## Gotchas
[Common mistakes, alignment issues, version-specific details]

## References
- [Links to papers, blog posts, similar exploits]
```

### Template E: Trick / Technique (tricks)

```markdown
---
title: [Concise trick description]
type: trick
category: tricks
tags: [domain, language, tool]
created: [YYYY-MM-DD]
last_hit: [YYYY-MM-DD]
hit_count: 1
related: []
---

## What
[What this trick does]

## When to Use
[Situation where this trick is useful]

## How
[Step-by-step or code snippet]

## Why It Works
[Brief explanation of the underlying mechanism]

## Notes
[Caveats, alternatives, related tricks]
```

### Template F: Tool Usage (tools)

```markdown
---
title: [Tool name — specific technique]
type: tool
category: tools
tags: [tool-name, use-case]
created: [YYYY-MM-DD]
last_hit: [YYYY-MM-DD]
hit_count: 1
tool: [tool name]
related: []
---

## Tool
[Tool name and version]

## Use Case
[When you'd need this]

## Command / Steps
\```bash
[Exact commands or steps]
\```

## Expected Output
[What to expect]

## Tips
[Non-obvious flags, options, or workflow details]

## Notes
[Gotchas, alternatives]
```

---

## Modes of Operation

### Mode 1: Brain Dump (`/brain-dump`)

Triggered when:
- User says: `/brain-dump`, "record this", "log this"
- AI resolves a non-trivial error (auto-record, see Mode 3)
- User finishes a CTF challenge or RE analysis

**Recording workflow:**

1. **Determine entry type** from context:
   - Command failed → Error record (Template A)
   - CTF challenge → CTF writeup (Template B)
   - IDA/Ghidra analysis → Reversing note (Template C)
   - Exploit technique → Exploit record (Template D)
   - Useful technique/trick → Trick (Template E)
   - Tool usage tip → Tool usage (Template F)

2. **Classify** into the appropriate category

3. **Assign tags** — free-form keywords relevant to the entry

4. **Check for existing entries** — search _cache.json and grep for similar entries. If a similar one exists, UPDATE it instead of creating a duplicate

5. **Generate slug filename** — lowercase, hyphen-separated, descriptive

6. **Write the file** using the appropriate template

7. **Scan for cross-references** — if the new entry references techniques, tools, or errors from other entries, add their filenames to the `related: []` frontmatter field, and add a back-reference in those entries too

8. **Update all indexes** (in this order — ALL steps are MANDATORY, do NOT skip any):
   a. **`_cache.json`** — add entry to `entries[]` with fields: `id` (category/slug), `title`, `category`, `tags`, `error_pattern` (regex from error message), `solution_hint` (one-line), `hit_count`, `last_hit`. Add tags to `tags_index`. Increment `total`. Update `updated` date. **WARNING: If you skip this step, the auto-search hook and Mode 4 will NOT find the entry!**
   b. **`<category>/_index.md`** — add one-line entry to the sub-index table
   c. **`INDEX.md`** — increment the count for the category, update total

9. **Confirm to user** — show what was recorded

> **Common failure mode:** Writing the .md file but forgetting to update `_cache.json`. This makes the entry invisible to all search mechanisms. If you suspect desync, run `/brain-rebuild`.

### Mode 2: Brain Search (`/brain-search`) — 3-Level Strategy

Triggered when:
- User says: `/brain-search`, "have we seen this", "search kb"
- AI encounters an error (auto-search, see Mode 4)
- Encountering a CTF challenge similar to a previous one

**3-Level search strategy (from cheapest to most expensive):**

#### Level 1: JSON Cache (~50 tokens)
Read `~/.claude/brainless/_cache.json` and search:
- Match keywords against `title`, `summary`, `tags` fields in `entries[]`
- Use `tags_index` for exact tag matches
- This is a single small file containing ALL entry metadata — no need to read anything else
- If match found with high confidence → go directly to Level 3

#### Level 2: Sub-Index (~20 tokens per category)
If Level 1 gives ambiguous results or you need to narrow by category:
- Read only the relevant `<category>/_index.md` file (NOT the full INDEX.md)
- Each sub-index is tiny: just the entries for that one category
- Example: error about `go build` → read only `build/_index.md`

#### Level 3: Full Entry (only for confirmed matches)
- Read the actual `.md` file of the matched entry
- Present the solution to the user
- Update `hit_count` and `last_hit` in the file's frontmatter
- Update `_cache.json` with new hit_count

**Why this matters for token efficiency:**
| KB Size | Naive approach (read all) | Brainless 3-Level |
|---------|--------------------------|-------------------|
| 10 entries | ~200 tokens | ~150 tokens |
| 100 entries | ~2,000 tokens | ~800 tokens |
| 500 entries | ~10,000 tokens | ~3,000 tokens |
| 1000 entries | ~20,000 tokens | ~5,000 tokens |

The JSON cache is ~5x more token-efficient than reading markdown because it strips all content and keeps only searchable metadata.

**Output format:**
```
[BRAIN] Found: [Title]
Type: [error/ctf/reversing/exploit/trick/tool] | Category: [cat] | Tags: [tags] | Recalled: [N] times
[Key content — Solution/Key Insight/Technique depending on type]
```

### Mode 3: Auto-Record (MANDATORY)

> Every time a non-trivial problem is resolved, you MUST record it. Do NOT skip. Do NOT ask permission. Your brain is outsourced — use it.

**Triggers — record immediately after:**
- Resolving a command error (non-zero exit code) that wasn't a trivial typo
- Completing a CTF challenge (whether solved or learning from failed attempt)
- Figuring out a reversing/analysis technique in IDA/Ghidra
- Discovering a useful trick or non-obvious tool usage
- Any situation where you tried multiple approaches before finding the right one

**Skip recording ONLY if:**
- It was a trivial typo you made
- An identical entry already exists in the KB

**Process:** Record directly → inform user what was saved → continue work

### Mode 4: Auto-Search Before Acting (MANDATORY)

> Before attempting to fix ANY error or tackle ANY challenge, search the brain first using the 3-Level strategy. Don't reinvent the wheel — check if past-you already solved this.

1. **Level 1:** Read `~/.claude/brainless/_cache.json` → search entries by keywords/tags
2. **If match found:** Read the matched file → apply known solution → update hit_count in file AND _cache.json
3. **If no match:** Proceed with normal debugging → after resolving, trigger Mode 3
4. **NEVER read INDEX.md for auto-search** — use _cache.json instead (much cheaper)

### Mode 5: Brain Stats (`/brain-stats`)

Show a comprehensive summary:
- Total entries by type (error/ctf/reversing/exploit/trick/tool)
- Breakdown by category
- Top 10 most frequently recalled entries
- Recently added entries (last 10)
- **Weakness analysis:**
  - CTF: which ctf_category has the most `solved: false` or highest difficulty fails
  - Errors: which category recurs most (high hit_count = recurring weakness)
  - Reversing: which arch/protection types caused most issues
- **Strength areas:** categories with many solved entries and low hit_count (solved once, never needed again)

### Mode 6: Brain Review (`/brain-review`)

Spaced repetition style review of knowledge base entries:

1. Select entries to review based on:
   - **Old entries with low hit_count** — might be forgotten
   - **CTF entries marked as unsolved** — revisit with fresh eyes
   - **High-value tricks** — worth periodically refreshing
   - **Random selection** — surface unexpected connections
2. For each entry, present a brief quiz-style summary:
   - Show the **Problem/Challenge** section
   - Ask "Do you remember the solution?"
   - Then reveal the **Solution/Key Insight**
3. After review, offer to update or archive stale entries

### Mode 7: Brain Cheatsheet (`/brain-cheatsheet`)

Auto-generate condensed cheat sheets from accumulated entries:

```
/brain-cheatsheet [category]
```

**Examples:**
- `/brain-cheatsheet ctf` → CTF techniques cheat sheet grouped by category (pwn/web/crypto/rev)
- `/brain-cheatsheet reversing` → RE cheat sheet (common patterns, IDA shortcuts, anti-debug bypasses)
- `/brain-cheatsheet tools` → Tool quick reference
- `/brain-cheatsheet build` → Common build error fixes
- `/brain-cheatsheet all` → Full knowledge base summary

**Cheat sheet format:**
```markdown
# [Category] Cheat Sheet
> Auto-generated from Brainless on [date]. [N] entries.

## [Sub-group 1]
| Problem/Technique | Quick Solution | Tags |
|-------------------|---------------|------|
| [title] | [one-line solution] | [tags] |

## [Sub-group 2]
...
```

Save generated cheat sheets to `~/.claude/brainless/_cheatsheets/[category].md`

### Mode 8: Brain Rebuild (`/brain-rebuild`)

Rebuild all indexes from existing entry files. Fixes desync between `.md` entries and `_cache.json`/`_index.md` indexes.

**When to use:**
- `_cache.json` is empty but entry files exist
- Auto-search isn't finding entries that you know exist
- After manual edits to entry files
- As a periodic health check

**Workflow:**
1. Scan all category directories for `.md` files (excluding `_index.md`)
2. Read YAML frontmatter from each entry
3. Rebuild `_cache.json` from scratch (entries, tags_index, total, updated)
4. Rebuild each `<category>/_index.md` with correct table of entries
5. Rebuild `INDEX.md` with correct counts
6. Report results

---

## Hook System — Full Session Lifecycle

Brainless installs hooks across the **entire Claude Code lifecycle** — every tool call is monitored, errors are tracked, and Claude is forced to use its brain when stuck. This is real automation — not dependent on prompt instructions.

### PreToolUse: Streak Reminder (ALL tools)
- Hook script: `~/.claude/brainless/hooks/streak_reminder.py`
- Triggered: **BEFORE every tool call** (all tools, no exceptions)
- Action: checks `_error_streak.json` — if 2+ consecutive errors detected, injects escalating warnings
- At 2-3 errors: WARNING — "STOP and think, run /brain-search"
- At 4+ errors: CRITICAL — "YOU ARE IN A LOOP, CHANGE YOUR APPROACH"
- Shows the error trail so Claude sees exactly what keeps failing

### PostToolUse: Universal Error Search + Streak Tracking (ALL tools)
- Hook script: `~/.claude/brainless/hooks/universal_error_search.py`
- Triggered: **after every tool call** (Bash, Edit, Write, LSP, Agent, Grep, Glob, Read, etc.)
- Action: detects errors in tool output → searches `_cache.json` → outputs matching entries
- On error: increments `_error_streak.json` streak counter
- On success: resets streak counter to 0
- Escalated output when streak >= 2: appends extra directives to search results

### PostToolUseFailure: Error Search (ALL tools)
- Same script: `~/.claude/brainless/hooks/universal_error_search.py`
- Triggered: when any tool call **fails** (permission denied, invalid args, etc.)
- Special handling: PostToolUseFailure stdout is not visible to Claude, so results are written to `_pending_brainless_output.txt` and flushed on next PostToolUse

### PostToolUse: Activity Logger (Edit|Write)
- Hook script: `~/.claude/brainless/hooks/post_tool_logger.py`
- Triggered: after Edit/Write tool calls
- Action: logs file edits to `activity.log`, checks if modified files relate to known KB entries

### SessionStart: Brain Context Injection
- Hook script: `~/.claude/brainless/hooks/session_start.py`
- Triggered: on every new session
- Action: loads brain stats, project-aware entry search, resets error streak

### UserPromptSubmit: Proactive Brain Search
- Hook script: `~/.claude/brainless/hooks/user_prompt_search.py`
- Triggered: when user sends a message, BEFORE Claude starts processing
- Action: extracts keywords from user prompt → searches `_cache.json` → injects matching entries
- This means Claude starts working with relevant brain knowledge already loaded

### PostCompact: Memory Restoration
- Hook script: `~/.claude/brainless/hooks/post_compact.py`
- Triggered: after context compression
- Action: re-injects project entries, current streak state, unrecorded error count, and behavioral rules
- This is the most critical recovery hook — when Claude's context gets compressed, it loses memory. This hook restores awareness.

### CwdChanged: Project Context Reload
- Hook script: `~/.claude/brainless/hooks/cwd_changed.py`
- Triggered: when working directory changes
- Action: searches brain by new cwd/repo name, shows known issues for new project

### SubagentStop: Subagent Result Scanning
- Hook script: `~/.claude/brainless/hooks/subagent_stop.py`
- Triggered: when a subagent finishes
- Action: scans subagent result for error keywords → searches brain for matching solutions

### StopFailure: API Failure Tracking
- Hook script: `~/.claude/brainless/hooks/stop_failure.py`
- Triggered: when Claude's turn ends due to API error (rate limit, auth, billing)
- Action: records failure to session errors log for tracking

### Stop: Session Summary
- Hook script: `~/.claude/brainless/hooks/session_end.py`
- Triggered: on session end
- Action: logs session duration, tool count, brain hits, warns about unrecorded errors

### Trash Talk Module
- Module: `~/.claude/brainless/hooks/trash_talk.py`
- Shared by all hooks — provides random witty one-liners (毒舌吐槽风) for each event type
- 13 phrase pools: session_start, session_end, user_prompt, error, error_no_match, error_matched, success, streak_warning, streak_critical, compact, cwd_changed, subagent_stop, stop_failure

**This means:** even if CLAUDE.md instructions are lost due to context compression, the hooks will still fire and surface relevant knowledge from the brain. Claude literally cannot escape brainless awareness.

---

## Cross-Reference System

Entries can reference each other via the `related: []` frontmatter field:

```yaml
related: [ctf/pwn-stack-overflow-2024.md, tricks/rop-chain-gadget-finder.md]
```

**When recording a new entry:**
1. Scan existing entries for overlapping tags/topics
2. If related entries exist, add cross-references in both directions
3. When displaying an entry, show "Related entries:" at the bottom

**When searching:**
- If a match is found, also show its related entries as "See also:"

---

## Important Guidelines

- **Be aggressive about recording** — a rich brain is infinitely more useful than an empty one
- **Use the right template** — CTF writeups need different structure than build errors
- **Record failed attempts** — for CTF, "what didn't work" is as valuable as the solution
- **Keep solutions actionable** — someone reading should be able to apply it directly
- **Update, don't duplicate** — if a similar entry exists, enrich it
- **Cross-reference actively** — connections between entries multiply their value
- **Use consistent slugs** — `lowercase-hyphen-separated.md`
- **Preserve INDEX.md structure** — always update when adding/modifying entries
- **Tag generously** — more tags = better searchability