🧠 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
What It Does
Gives Claude Code a memory across sessions using local markdown files:
- Obsidian → Project knowledge (plans, decisions, architecture)
- Inkdrop → Personal memory (preferences, learnings, patterns) - optional
Every session:
- Claude loads context automatically (global knowledge + project context)
- You work normally
- Claude saves learnings automatically when you close
No cloud dependencies. No databases. Just markdown files you own.
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
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
Key Features
🤖 Auto-Save Sessions
Session summaries are saved automatically when you close Claude Code:
- Intelligent summary generated by Claude Haiku
- Saves to Obsidian journals + Inkdrop
- Adds ~5-10s to session close
- → Auto-Save Documentation
🧠 Global Knowledge System
Cross-project knowledge loaded in every session:
- learnings.md - Best practices and insights
- errors-solved.md - Documented solutions
- patterns.md - Code patterns
📦 Intelligent Installation
- 🔍 Auto-detects Obsidian vaults from system
- 📂 Visual vault selection (shows open vaults)
- 🧪 Interactive Inkdrop wizard (optional)
- ✅ Pre-flight validation
- 🔄 Smart upgrades with config preservation
4 manual prompts → 1-2 prompts (80%+ auto-detection)
⚡ Token Optimization
- Context injection: ~1500-3000 tokens/session
- Auto-save: ~2000-8000 tokens/session
- Main skill: 90% reduction (700 tokens vs 7000)
- → Token Optimization Guide
Installation
Option 1: Marketplace (Recommended)
# Add marketplace
/plugin marketplace add marcoscarbonera/carbon-claude-brain
# Install plugin
/plugin install carbon-claude-brain@carbon-claude-brain
# Run setup wizard
/carbon-brain-setup
Advantages:
- 🚀 Automatic updates
- 🔧 One-command installation
- ✅ Validated releases
Option 2: Manual Installation
git clone https://github.com/marcoscarbonera/carbon-claude-brain
cd carbon-claude-brain
./install.sh
When to use:
- Testing development versions
- Custom modifications
- Contributing to the project
Dry-run mode:
./install.sh --dry-run
Available Skills
