Second Brain

AI-powered journaling with semantic backlinks. Extracts actionable tasks from reflections. Works with Azure OpenAI or local Ollama.

Installation

For End Users

Install directly from GitHub:

uv tool install git+https://github.com/madebygps/second-brain.git

After installation, the brain command will be available globally:

brain --help

Next: Configure your .env file (see Configuration below).

For Development

# Clone the repository
git clone https://github.com/madebygps/second-brain.git
cd second-brain

# Install with uv
uv sync

# Set up pre-commit hooks
uv run pre-commit install

# Configure environment
cp .env.example .env
# Edit .env with your paths and Azure credentials

# Run in development mode
uv run brain --help

Features

• Morning planning - LLM extracts tasks from yesterday's diary + carries forward uncompleted todos
• Evening reflection - AI prompts based on your past 3 days
• Semantic backlinks - LLM finds thematic connections (not keyword matching)
• Emotional patterns - Tracks psychological themes over time
• Local or cloud - Works with Ollama (free, private) or Azure OpenAI
• Obsidian-compatible - Plain markdown with wiki-style links

Documentation:

• PHILOSOPHY.md - Design principles
• PLANNING.md - Planning guide
• DIARY.md - Diary guide
• COST_TRACKING.md - Cost tracking guide

Quick Start

# 1. Install
uv tool install git+https://github.com/madebygps/second-brain.git

# 2. Configure
mkdir -p ~/.config/brain
curl -o ~/.config/brain/.env https://raw.githubusercontent.com/madebygps/second-brain/main/.env.example
nano ~/.config/brain/.env  # Edit with your paths and LLM provider

# 3. Use
brain plan create today    # Morning: actionable tasks
brain diary create today   # Evening: reflection
brain diary link today     # Add semantic backlinks

See SETUP_CHECKLIST.md for detailed configuration.

Usage

Daily workflow:

brain plan create today      # Morning planning
brain diary create today     # Evening reflection
brain diary link today       # Add semantic backlinks

Analysis:

brain diary report 7         # Memory trace for past week
brain diary patterns 7       # Emotional/psychological themes
brain diary list            # List all entries

Cost tracking (Azure OpenAI only):

brain cost summary          # Usage stats
brain cost trends 30        # Daily costs
brain cost breakdown        # Per-operation costs

Debugging:

brain --verbose <command>   # Show key operations
brain --debug <command>     # Full diagnostics

Run brain --help for all commands.

Configuration

Required:

DIARY_PATH=/path/to/diary        # Reflection entries
PLANNER_PATH=/path/to/planner    # Daily plans (separate)
LLM_PROVIDER=ollama              # or "azure"

Ollama (local, free, private):

OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.1

Azure OpenAI (cloud):

AZURE_OPENAI_API_KEY=your-key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT=gpt-4o

See SETUP_CHECKLIST.md for full configuration options.

Entry Format

Morning Plan (YYYY-MM-DD-plan.md in PLANNER_PATH):

## Action Items
- [ ] Task from yesterday's diary (from [[2025-10-14]])
- [ ] Unchecked task from yesterday's plan (from [[2025-10-13-plan]])

Evening Reflection (YYYY-MM-DD.md in DIARY_PATH):

## Reflection Prompts
**1. AI-generated prompt based on past 3 days**

---

## Brain Dump
Your free-form reflection...

---

## Memory Links
[Generated by: brain diary link today]
**Temporal:** [[2025-10-14]] • [[2025-10-13]]
**Topics:** #self-doubt #growth #perfectionism

See ENTRY_FORMAT.md for quick reference.

Requirements

• Python 3.13+
• uv package manager
• LLM Provider (choose one):
  • Ollama - Local, free, private (install)
  • Azure OpenAI - Cloud, requires API key

Development

git clone https://github.com/madebygps/second-brain.git
cd second-brain
uv sync                          # Install dependencies
uv run pre-commit install        # Setup hooks
cp .env.example .env             # Configure
uv run brain --help              # Test

# Testing
uv run pytest                    # Run tests
uv run pytest --cov              # With coverage

See PHILOSOPHY.md for architecture and design decisions.

License

MIT