BrainDump Butler

Github Copilot SDK powered note-taking assistant that automatically structures your notes and saves them to an Obsidian vault.

Features

• Cross-Platform PWA: Works on desktop, tablet, and mobile from a single web interface
• Multi-Language Support: English and German UI with easy toggle (more languages can be added)
• AI-Powered Structuring: Uses GitHub Copilot SDK to structure and organize notes
• Automatic Tagging: Extracts and suggests relevant tags based on content
• Template System: AI-generated templates for consistent note formats
• Interactive Refine Mode: Chat with AI to extract more insights from your notes
• Obsidian Integration: Saves notes as Markdown files with proper frontmatter
• Smart Linking: Automatically creates [[wiki-links]] to related notes
• Knowledge Base: Learns your vocabulary, projects, people, and abbreviations
• Git Sync: Automatic commits and push to GitHub for backup and sync
• Model Selection: Choose between different AI models (GPT-4.1, GPT-4.1-mini, etc.)

Architecture

┌─────────────────────────────────────────┐
│           PWA Frontend                  │
│  (Notes, Templates, Refine, Browse)     │
└───────────────┬─────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────┐
│         FastAPI Backend                 │
│  ┌─────────────┐  ┌─────────────────┐  │
│  │ Copilot SDK │  │ Knowledge Base  │  │
│  │ (AI Layer)  │  │ (Context)       │  │
│  └─────────────┘  └─────────────────┘  │
│  ┌─────────────┐  ┌─────────────────┐  │
│  │   Skills    │  │   Templates     │  │
│  │ Orchestrator│  │   Service       │  │
│  └─────────────┘  └─────────────────┘  │
└───────────────┬─────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────┐
│        Obsidian Vault (Markdown)        │
│           + Git Sync                    │
└─────────────────────────────────────────┘

Getting Started

# 1. Clone and enter the repository
git clone https://github.com/SchwarziLukas/braindump-butler.git
cd braindump-butler

# 2. Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -e .

# 4. Create the vault directory structure
mkdir -p vault/{daily,meetings,ideas,projects,.ai}

# 5. Initialize git in the vault (required for git sync)
cd vault && git init && cd ..

# 6. Start the server
python -m backend.main

Open http://localhost:8000 in your browser.

Installation (Detailed)

Prerequisites

• Python 3.11+
• GitHub CLI authenticated (gh auth login) - or set GITHUB_TOKEN env var
• (Optional) Git remote for sync

Setup

# Clone the repository
git clone https://github.com/SchwarziLukas/braindump-butler.git
cd braindump-butler

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

# Or with dev dependencies (pytest, ruff, etc.)
pip install -e ".[dev]"

# Create vault directory with required structure
mkdir -p vault/{daily,meetings,ideas,projects,.ai}

# Initialize git in the vault
cd vault && git init && cd ..

# Authenticate with GitHub CLI (if not already)
gh auth login

# Copy environment template (optional)
cp .env.example .env

# Edit .env with your settings (all are optional)
# - VAULT_PATH: where your notes are stored (default: ./vault)
# - VAULT_GIT_REMOTE: (optional) remote URL for git sync
# - VAULT_AUTO_PUSH: (optional) set to true to push after each note

Running

# Activate the virtual environment (if not already active)
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Start the server
python -m backend.main

# Or with uvicorn directly (with auto-reload for development)
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

Open http://localhost:8000 in your browser.

Usage

Creating Notes

1. Select a note type (or leave on "Auto" for AI detection)
2. Optionally add context (e.g., meeting name)
3. Type or paste your raw notes
4. Click "Process & Save"

The AI will:

• Structure your content with proper Markdown
• Extract relevant tags
• Suggest links to existing notes
• Save to the appropriate folder in your vault
• Commit to Git

Interactive Refine Mode

The Refine tab allows you to have a conversation with the AI to extract more from your notes:

• Probe Mode: AI asks deeper questions to help you think through ideas
• Extract Mode: Automatically extracts action items, decisions, and key insights
• Improve Mode: Get suggestions for improving and expanding your notes

Templates

Create and manage templates for consistent note formats:

1. Go to the Templates tab
2. Describe the template you need (e.g., "1:1 meeting with employee")
3. Select an AI model and click "Generate Template"
4. Preview, refine, and save the template
5. Use templates when creating new notes

Language Toggle

Click the language button (EN/DE) in the header to switch between English and German. Your preference is saved automatically.

Note Types

Type	Folder	Use Case
Daily	/daily/	Daily logs, journaling
Meeting	/meetings/	Meeting notes, action items
Idea	/ideas/	Brainstorming, concepts
Project	/projects/	Project documentation
General	/	Everything else

Knowledge Base

The assistant learns from your notes and builds context:

• Tags: Remembers tag descriptions and relationships
• Projects: Tracks project names and descriptions
• People: Associates names with context
• Abbreviations: Expands common abbreviations

Edit knowledge manually via API: GET/POST /api/knowledge/

API Endpoints

Method	Endpoint	Description
POST	/api/notes/	Create and process a new note
POST	/api/notes/clarify	Process note with clarification answers
GET	/api/notes/	List all notes
GET	/api/notes/{path}	Get a specific note
GET	/api/notes/search?q=	Search notes
GET	/api/notes/stats	Get vault statistics
POST	/api/refine/start	Start a refine session
POST	/api/refine/continue	Continue refine conversation
POST	/api/refine/extract/{id}	Extract all insights from session
GET	/api/templates/	List all templates
GET	/api/templates/{id}	Get a specific template
POST	/api/templates/generate	Generate a new template with AI
POST	/api/templates/save	Save a template
POST	/api/templates/refine	Refine an existing template
DELETE	/api/templates/{id}	Delete a template
GET	/api/models/	List available AI models
GET	/api/sync/status	Git sync status
POST	/api/sync/push	Push to remote
POST	/api/sync/pull	Pull from remote
POST	/api/sync/setup-remote	Configure git remote
GET	/api/knowledge/	Get knowledge base
POST	/api/knowledge/tags	Add a tag

Project Structure

braindump-butler/
├── backend/
│   ├── main.py              # FastAPI app
│   ├── config.py            # Settings
│   ├── api/                 # API endpoints
│   │   ├── notes.py
│   │   ├── sync.py
│   │   ├── templates.py
│   │   ├── refine.py
│   │   └── knowledge.py
│   ├── services/            # Business logic
│   │   ├── ai_processor.py
│   │   ├── template_service.py
│   │   ├── git_sync.py
│   │   └── vault_writer.py
│   ├── skills/              # AI skill modules
│   │   ├── base.py
│   │   ├── orchestrator.py
│   │   ├── classify.py
│   │   ├── structure.py
│   │   ├── tag.py
│   │   └── link.py
│   ├── models/
│   │   └── schemas.py
│   └── knowledge/
│       └── context.py
├── frontend/
│   ├── index.html
│   └── static/
│       ├── app.js           # Main app with i18n
│       ├── style.css
│       ├── sw.js            # Service worker
│       └── manifest.json
├── tests/                   # Test suite
│   ├── conftest.py
│   ├── test_api.py
│   └── test_skills.py
├── vault/                   # Obsidian Vault
│   ├── daily/
│   ├── meetings/
│   ├── ideas/
│   ├── projects/
│   └── .ai/                 # Knowledge Base
├── pyproject.toml
├── pytest.ini
├── .env.example
└── README.md

Testing

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with coverage
pytest --cov=backend

# Run specific test file
pytest tests/test_api.py

Roadmap

• Template system with AI generation
• Interactive refine mode
• Multi-language support (EN/DE)
• Model selection
• Test infrastructure
• Voice input (Speech-to-Text)
• Image/screenshot support
• Mobile app (React Native / Capacitor)
• Multi-user support
• Obsidian plugin for direct integration

License

MIT