carbon-claude-brain

🧠 carbon-claude-brain

Persistent memory for Claude Code using Obsidian as a second brain and Inkdrop as a journal — no databases, no services, no complexity.

🇧🇷 Versão em Português

How It Works

Session Lifecycle

flowchart TB
    Start([Start Session]) --> Hook1[session-start.sh]
    Hook1 --> Obs1[📖 Load from Obsidian]
    Hook1 --> Ink1[📓 Load from Inkdrop]

    Obs1 --> |Project Context|Load[Context Loaded]
    Obs1 --> |Global Knowledge|Load
    Ink1 --> |Personal Preferences|Load
    Ink1 --> |Previous Learnings|Load

    Load --> Work[👨‍💻 Coding Session]

    Work --> Skills{Skills Available}
    Skills --> |/carbon-brain-plan|PlanSkill[Update Plan]
    Skills --> |/carbon-brain-context|CtxSkill[View Context]
    Skills --> |/carbon-brain-search|SearchSkill[Search Projects]
    Skills --> |/carbon-brain-search-patterns|PatternSkill[Search Patterns]

    PlanSkill --> SaveObs[💾 Save to Obsidian]

    Work --> Hook2[post-tool-use.sh]
    Hook2 --> |Important Decisions|Capture[Capture Notes]

    Work --> End([End Session])
    End --> Hook3[session-end.sh]
    Hook3 --> SaveObs2[💾 Update Obsidian Status]
    Hook3 --> SaveInk[📓 Save Journal to Inkdrop]

    style Start fill:#fff,stroke:#000,stroke-width:3px
    style End fill:#fff,stroke:#000,stroke-width:3px
    style Work fill:#fff,stroke:#000,stroke-width:2px
    style Load fill:#fff,stroke:#000,stroke-width:2px
    style Skills fill:#fff,stroke:#000,stroke-width:2px

Architecture Overview

graph LR
    Claude[🤖 Claude Code]
    Project[📁 Your Project]

    Obsidian[📖 Obsidian<br/>Project Knowledge<br/><small>plans, decisions, architecture</small>]
    Inkdrop[📓 Inkdrop<br/>Personal Memory<br/><small>preferences, learnings, patterns</small>]

    Claude -->|works on| Project

    Claude -->|reads at start| Obsidian
    Claude -->|reads at start| Inkdrop

    Claude -->|saves at end| Obsidian
    Claude -->|saves at end| Inkdrop

    style Claude fill:#fff,stroke:#000,stroke-width:3px
    style Project fill:#fff,stroke:#000,stroke-width:2px
    style Obsidian fill:#fff,stroke:#000,stroke-width:2px
    style Inkdrop fill:#fff,stroke:#000,stroke-width:2px

Business Logic:

1. Session Start — Claude automatically loads:
   • Global knowledge (learnings, errors-solved, patterns)
   • Project context and recent decisions
   • Personal preferences from Inkdrop
2. Work — Claude codes on your project with full context
3. Session End — Claude automatically saves decisions to Obsidian and learnings to Inkdrop

What gets loaded each session:

• ⚙️ Personal preferences (Inkdrop)
• 📚 Global learnings (cross-project knowledge)
• 🐛 Previously solved errors
• 🎯 Reusable code patterns
• 📁 Current project context
• 🏛️ Recent technical decisions
• 📔 Last session journal

Prerequisites

• Claude Code installed
• Obsidian with local vault configured
• Inkdrop with local server active (localhost:19840) — optional
• bash ≥4.0, curl, node (usually pre-installed)

Installation

Option 1: Marketplace (Recommended)

Install directly from the plugin marketplace:

# Add the marketplace
/plugin marketplace add marcoscarvalhodearaujo/carbon-claude-brain

# Install the plugin
/plugin install carbon-claude-brain@carbon-claude-brain

# Run the configuration wizard
/carbon-brain-setup

Configuration Modes

Interactive Mode (Default): The wizard uses intelligent auto-detection and simplified prompts:

• 🔍 Auto-detects Obsidian vaults - Parses obsidian.json to find your vaults
• 📂 Visual vault selection - Shows open vaults highlighted, or manual entry
• 🧪 Interactive Inkdrop wizard - Optional 4-step setup with connection testing
• ✅ Pre-flight validation - Checks vault access, disk space, and configuration
• 📦 One-click upgrades - Preserves existing config, auto-migrates legacy format

Reduced complexity: 4 manual prompts → 1-2 prompts

Non-Interactive Mode (Advanced): For automated setup or reproducible configuration:

1. Copy the example config:

   cp ${CLAUDE_PLUGIN_ROOT}/.env.example ${CLAUDE_PLUGIN_ROOT}/.env
   

2. Edit .env with your settings:

   # Required
   OBSIDIAN_VAULT="/Users/yourname/Documents/MyVault"
   
   # Optional - leave empty to disable Inkdrop
   INKDROP_URL=""
   INKDROP_USER=""
   INKDROP_PASS=""
   

3. Run setup:

   /carbon-brain-setup
   

The script will detect the .env file and run without prompts.

Advantages:

• 🚀 Automatic updates
• 🔧 One-command installation
• 📦 No manual file copying
• ✅ Validated releases

Option 2: Manual Installation

Clone and install manually:

git clone https://github.com/marcoscarvalhodearaujo/carbon-claude-brain
cd carbon-claude-brain
./install.sh