the-ai-brain

The AI Brain

A universal persistent memory system for AI agents. Install into any directory or Obsidian vault to give your AI agent long-term memory, self-improving behavior, and structured workflows.

Prerequisites

Requirement	Required?	Notes
Claude Code	Required	For hooks, skills, and full memory features
git	Required	For version control of your vault
jq	Required	For JSON processing in hooks
Obsidian 1.12+	Optional	Unlocks CLI mode — 70,000x faster vault search. Without it, brain uses raw file reads (still fully functional)
yq	Optional	Better YAML parsing. Falls back to awk if missing
python3	Optional	Used by hooks when Obsidian CLI is active

Obsidian CLI setup (if you want it):

1. Install Obsidian 1.12+
2. Open Obsidian → Settings → General → enable Command Line Interface
3. Click Register CLI — adds obsidian to your system PATH
4. Run obsidian version in terminal to verify
5. The brain auto-detects it during install.sh

Obsidian is not required. The brain works on any plain directory with raw markdown files.

Supported Agents

Agent	Config File	Hooks	Skills	Memory
Claude Code	CLAUDE.md	Mechanical (hooks)	/brain-today, /brain-new, /brain-tldr, etc.	Full
Cursor	.cursorrules	Instruction-based	N/A	Instruction-based
Gemini CLI	GEMINI.md	Instruction-based	N/A	Instruction-based
OpenAI Codex	AGENTS.md	Instruction-based	N/A	Instruction-based

Install

Option 1: Claude Code Plugin Marketplace (Recommended)

From within any Claude Code session:

/plugin marketplace add cfircoo/the-ai-brain
/plugin install the-ai-brain@cfircoo

Then initialize the brain in your vault:

/the-ai-brain:brain-setup

Option 2: Load as Local Plugin

# Clone the repo
git clone https://github.com/cfircoo/the-ai-brain.git

# Launch Claude Code with the plugin loaded
claude --plugin-dir ./the-ai-brain

Skills are available as /the-ai-brain:brain-today, /the-ai-brain:brain-debrief, etc.

Option 3: Standalone Installer

git clone https://github.com/cfircoo/the-ai-brain.git
cd the-ai-brain
bash install.sh /path/to/your/vault

The installer will:

1. Auto-detect your role from git/README (no questions if context is clear)
2. Ask your preferred architecture (Hub+Spokes default — press Enter)
3. Create the vault directory structure
4. Generate agent-specific config files
5. Install hooks and skills (Claude Code)
6. Wire the hub if Hub+Spokes was chosen

Adding a brain to an existing project:

cd ~/projects/your-existing-project
# Then in Claude Code:
/the-ai-brain:brain-setup
# Auto-detects context, defaults to Hub+Spokes

Architecture Strategies

Hub + Spokes (default, recommended)

One global brain for your identity + per-project brains for local context. Both are always in context simultaneously.

~/Brain/                         ← HUB (your personal OS)
├── Human/Daily/                 ← daily notes, life captures
├── Machine/Memory/
│   ├── entities.md              ← people, tools — across ALL projects
│   ├── decisions.md             ← life/career decisions
│   └── projects.md              ← registry of all known projects
└── CLAUDE.md                    ← who you are, global rules

~/.claude/CLAUDE.md              ← loads ~/Brain on EVERY session

~/projects/my-app/               ← SPOKE (project-specific)
├── .brain/                      ← local memory, hooks
└── CLAUDE.md                    ← project rules + references ~/Brain

~/projects/other-project/        ← another SPOKE
└── CLAUDE.md                    ← references ~/Brain automatically

Setup: Run /the-ai-brain:brain-setup in any project — Hub+Spokes is the default. Existing projects with no brain? Same command, it auto-detects context from your git/README.

Per-Project (isolated)