Frequently Asked Questions

Getting Started

What is Mega Brain?

Mega Brain is an AI-powered knowledge management system that transforms expert materials (videos, PDFs, transcriptions, podcasts, training courses) into structured knowledge. It produces:

Playbooks - Actionable frameworks and methodologies
DNA Schemas - Cognitive profiles across 5 knowledge layers
Mind Clone Agents - AI agents that reason like specific experts

Built for solo entrepreneurs and small teams who want to operationalize the expertise they’ve accumulated across dozens of courses, mentors, and resources.

Think of it as your personal knowledge compiler - turning raw expert content into executable intelligence.

What can I do with Mega Brain?

Knowledge Management:

Ingest any format (videos, PDFs, transcriptions, podcasts)
Extract structured DNA across 5 knowledge layers
Build playbooks and dossiers with full source traceability

AI Agents:

Create mind clones that reason like specific experts
Use functional role agents (Sales, Marketing, Operations, Finance)
Run multi-agent deliberation sessions (Conclave)

Developer Experience:

20+ hooks for automated validation and quality control
Slash commands for common operations
Session persistence with auto-save and resume
Skill system with keyword-based auto-routing

Do I need programming experience to use Mega Brain?

No programming required for basic use:

Setup wizard guides you through installation
Slash commands provide simple interfaces
Natural language interactions with agents

Programming helpful for:

Custom hook development
Advanced skill creation
Pipeline customization
Contributing to the project

The CLI and slash commands are designed to be accessible to non-technical users.

How long does it take to get started?

5 minutes from zero to first insight:

Install (1 min):
```
npm install mega-brain-ai
```
Setup (2 min):
```
npx mega-brain-ai setup
```
Enter your OpenAI API key when prompted.

Ingest content (30 sec):

/ingest https://youtube.com/watch?v=example

Process (2-3 min):
```
/process-jarvis
```

See the Quick Start Guide for detailed walkthrough.

Prerequisites & Setup

What do I need to install?

Required:

Claude Code - Max or Pro plan (core runtime)
Node.js - Version 18.0.0 or higher (CLI and tooling)
Python - Version 3.10 or higher (intelligence scripts)

API Keys:

OPENAI_API_KEY - Required for transcription
VOYAGE_API_KEY - Recommended for semantic embeddings
GOOGLE_CLIENT_ID - Optional for Google Drive import

The setup wizard (/setup) automatically checks prerequisites and guides you through configuration.

Why is Claude Code required?

Claude Code is the runtime environment that:

Executes hooks and automation
Manages agent interactions
Orchestrates the processing pipeline
Provides the LLM capabilities

Mega Brain integrates deeply with Claude Code’s features:

Hooks system for automation
Skills system for specialized workflows
Slash commands for common operations
Session persistence

You need a Claude Max or Pro subscription to use Claude Code.

Where do I get API keys?

OpenAI API Key (Required):

Go to platform.openai.com
Sign up or log in
Navigate to API Keys section
Create a new key
Copy and save securely

Voyage API Key (Recommended):

Visit Voyage AI
Sign up for an account
Generate API key
Use for semantic embeddings (RAG)

Google Client ID (Optional):

Only needed if importing from Google Drive
Follow Google Cloud Console setup
Configure OAuth credentials

Never commit API keys to git. Always use .env file (already in .gitignore).

How much do API calls cost?

OpenAI (Whisper transcription):

~$0.006 per minute of audio
1-hour video = ~$0.36
10-hour course = ~$3.60

Voyage (embeddings):

Varies by model and usage
Check current pricing at voyageai.com

Claude Code:

Included in your Max/Pro subscription
No additional API costs

Most users spend $10-20/month on transcription for moderate use (5-10 hours of content).

Features & Capabilities

What file formats can I ingest?

Directly supported:

Videos: .mp4, .mov, .avi
Audio: .mp3, .wav, .m4a
Text: .txt, .md
Documents: .pdf
URLs: YouTube videos, web pages

Processing:

Audio/video → Transcribed via Whisper API
PDFs → Text extraction
URLs → Content fetching + transcription

Large files (>2GB) may need to be split for optimal processing.

What are the 5 DNA knowledge layers?

The DNA schema extracts expert knowledge across 5 hierarchical layers:

Layer	Name	Description	Example
L1	Philosophies	Core beliefs and worldview	”Value creation is the foundation of all business”
L2	Mental Models	Thinking frameworks	Value Equation framework (Hormozi)
L3	Heuristics	Practical rules	”Price should be 10x less than perceived value”
L4	Frameworks	Structured methodologies	Grand Slam Offer framework
L5	Methodologies	Step-by-step implementations	5-phase offer creation process

Each layer builds on the previous, creating a complete cognitive profile of an expert’s thinking.

More materials from the same expert = richer, more accurate DNA extraction.

What's the difference between a Playbook and a Dossier?

Playbook:

Theme-based knowledge compilation
Actionable frameworks and processes
Example: “Sales Objection Handling Playbook”
Cross-expert synthesis
Goal: Executable knowledge

Dossier:

Expert-specific knowledge profile
Complete DNA extraction
Example: “Alex Hormozi Dossier”
Single-source deep dive
Goal: Understanding an expert’s complete methodology

When to Use What

Playbook: “How do I handle objections?” (cross-expert best practices)
Dossier: “What does Hormozi teach about offers?” (expert-specific deep dive)

How do mind clone agents work?

Mind clones are AI agents that reason like specific experts:

Training: Process multiple materials from the same expert
DNA Extraction: System extracts cognitive patterns across 5 layers
Agent Creation: Agent file with expert’s DNA, thinking style, vocabulary
Consultation: Ask questions, get responses in expert’s reasoning style

Example:

/ask alex-hormozi "How should I price my coaching program?"

Response will:

Use Hormozi’s frameworks (Value Equation)
Apply his heuristics and mental models
Reference his methodologies
Cite source materials

Mind clones require at least 3-5 materials from an expert for high-fidelity responses. With only 1-2 sources, responses will be limited.

What is the Conclave?

Conclave is a multi-agent deliberation system where 3 specialized agents debate your question:The Council:

Methodological Critic - Analyzes frameworks and rigor
Devil’s Advocate - Identifies risks and challenges
Synthesizer - Builds consensus and recommendations

Process:

You ask a strategic question
Each agent analyzes from their perspective
Agents cite evidence from your knowledge base
Synthesizer provides consolidated recommendation
System shows confidence score based on available data

Example:

/conclave "Should I raise prices or increase volume?"

Conclave works best with a populated knowledge base. More expert materials = better deliberations.

Processing & Pipeline

What happens during the 5-phase pipeline?

Phase 1 - Chunking:

Breaks content into semantic segments
Preserves context and relationships
Output: artifacts/chunks/

Phase 2 - Resolution:

Identifies people, concepts, entities
Normalizes references
Output: Entity mappings

Phase 3 - Extraction:

Extracts frameworks, insights, rules
Applies DNA schema
Output: artifacts/insights/

Phase 4 - Synthesis:

Consolidates by theme
Creates narratives
Output: artifacts/narratives/

Phase 5 - Compilation:

Generates dossiers and playbooks
Links to sources
Output: knowledge/dossiers/, knowledge/playbooks/

Each phase builds on the previous, with full traceability back to source materials.

How long does processing take?

Typical times:

1-hour video: 2-4 minutes
50-page PDF: 1-2 minutes
3-hour course: 5-8 minutes

Factors:

Content length
Transcription needed (video/audio adds time)
Complexity of material
API response times

Run /jarvis-briefing to monitor processing status and see estimated time remaining.

Can I process content in batches?

Yes, batch processing is supported:

Add multiple files to inbox/
Run /process-jarvis
System processes all pending files
Batch logs in logs/batches/

Best practices:

Group related content together
Don’t exceed 10-15 files per batch
Review results before next batch
Monitor disk space and API limits

Very large batches (50+ files) may hit API rate limits. Process in groups of 10-15 for optimal results.

Community vs Pro

What's the difference between Community and Pro editions?

Community Edition (L1):

✅ Core engine and templates
✅ CLI tools and setup wizard
✅ Hooks and skills system
✅ Agent framework and templates
❌ Populated knowledge base
❌ Pre-built mind clones
❌ Cargo agents (29 functional roles)
❌ Full pipeline processing

Pro Edition (L2):

✅ Everything in Community
✅ Populated knowledge base
✅ 5 pre-built mind clones
✅ 14 cargo agents (CRO, CMO, CFO, COO, etc.)
✅ Full 5-phase pipeline
✅ Conclave with domain expertise

See Community vs Pro for detailed comparison.

Can I upgrade from Community to Pro later?

Yes, upgrading is seamless:

Your personal data (L3) remains intact
Your .env configuration carries over
No migration needed
Just enhanced capabilities

What you get:

Immediate access to pre-built agents
Populated knowledge base
Full pipeline capabilities
Council/Conclave ready to use

Contact @thiagofinch for Pro Edition access and licensing information.

Troubleshooting

Why isn't my skill activating?

Common issues:

Description too vague:

# Too vague
description: Helps with files

# Better
description: Extract DNA from expert materials. Use when processing videos, PDFs, or transcriptions.

SKILL-INDEX.json missing:
```
ls .claude/SKILL-INDEX.json
```
Should be generated on SessionStart.
Filename wrong:
- Must be exactly SKILL.md (case-sensitive)
Directory name doesn’t match frontmatter

See Troubleshooting for more details.

What if processing fails?

Check:

API keys configured:
```
grep OPENAI_API_KEY .env
```
File in inbox:
```
ls inbox/
```
Python installed:
```
python --version  # Should be 3.10+
```

Session logs:

ls -la logs/sessions/
# Check latest log

Run /jarvis-briefing to see health score and identify issues.

Contributing & Community

Can I contribute to Mega Brain?

Yes! Contributions welcome:Ways to contribute:

Bug fixes
Documentation improvements
New skills or hooks
Feature enhancements
Testing and feedback

Process:

Fork the repository
Create a feature branch (feat/my-feature)
Follow Contributing Guidelines
Open a Pull Request
Get approval from @thiagofinch

All PRs require approval from the maintainer before merge.

How do I report bugs or request features?

Bug Reports:

Check existing issues on GitHub
Create new issue with:
- Clear description
- Steps to reproduce
- Expected vs actual behavior
- System info (OS, Node version, Python version)
- Error messages and logs

Feature Requests:

Search existing requests
Open issue with:
- Use case description
- Problem you’re solving
- Proposed solution (optional)
- Examples or mockups (helpful)

Include output from /jarvis-briefing in bug reports for faster diagnosis.

Where can I get help?

Resources:

📖 Documentation: Read the full docs
🐛 GitHub Issues: Report bugs or ask questions
👤 Maintainer: Contact @thiagofinch
🔧 Troubleshooting: See common issues

Before asking:

Check the Troubleshooting Guide
Search existing GitHub issues
Run /jarvis-briefing to check system status
Review relevant documentation sections

Advanced Usage

Can I create custom hooks?

Yes, custom hooks are supported:Location: .claude/hooks/Requirements:

Python 3.10+
Stdlib + PyYAML only
Follow hook naming conventions

Hook events:

SessionStart - When Claude starts
UserPromptSubmit - Before each user message
PreToolUse - Before tool execution
PostToolUse - After tool execution
Stop - When session ends

Example:

# .claude/hooks/my_hook.py
import sys
import json

def main():
    # Hook logic here
    print(json.dumps({"status": "success"}))

if __name__ == "__main__":
    main()

{
  "hooks": {
    "SessionStart": [".claude/hooks/my_hook.py"]
  }
}

How do I create custom skills?

Structure:

.claude/skills/my-skill/
├── SKILL.md          # Main file (required)
├── resources/        # Optional resources
└── scripts/          # Optional scripts

SKILL.md format:

---
name: my-skill
description: Clear description with trigger words. Use when [scenario].
---

# Skill content
Instructions and workflows...

Best practices:

Specific descriptions with trigger words
Include “Use when…” context
One capability per skill
Clear instructions

See Troubleshooting Skills for common issues.

Can I customize the pipeline?

Yes, pipeline is customizable:What you can modify:

Task definitions in core/tasks/
Workflow YAML in core/workflows/
Intelligence scripts in core/intelligence/
Templates in core/templates/

Caution:

Understand the task anatomy (HO-TP-001 pattern)
Test changes thoroughly
Follow Pedro pattern conventions
Document custom modifications

Heavy pipeline customization may complicate upgrades. Consider contributing improvements upstream.

Resources

​Getting Started

​Prerequisites & Setup

​Features & Capabilities

When to Use What

​Processing & Pipeline

​Community vs Pro

​Troubleshooting

​Contributing & Community

​Advanced Usage

Build docs developers (and LLMs) love

Getting Started

Prerequisites & Setup

Features & Capabilities

Processing & Pipeline

Community vs Pro

Troubleshooting

Contributing & Community

Advanced Usage