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

Security & RE

Knowledge & Techniques

Record Templates

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

---
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)

---
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)

---
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)

---
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)

---
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)

---
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:

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:

# [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:

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