# Second Brain Vault 🧠

A personal knowledge base and system for capturing, organizing, and synthesizing knowledge.

**Synced with:** Extended thinking passes (on-idle or nightly)  
**Backed by:** Git for version control and history  
**Indexed in:** MEMORY.md for fast access  

## Structure

- **00-inbox/** — Raw captures, ideas, quick notes
- **01-daily/** — Daily reflections and work logs
- **02-projects/** — Project-specific knowledge (gravl, job-portal, finedine)
- **03-learnings/** — Books, lessons, insights, skills
- **04-architecture/** — System design decisions (ADRs)
- **05-code-snippets/** — Reusable code, commands, patterns
- **06-references/** — Links, resources, standards
- **07-templates/** — Note templates for consistency
- **08-connections/** — Relationship maps, team info
- **_files/** — Images, PDFs, diagrams

## How It Works

1. **Capture:** Ideas go into 00-inbox/
2. **Organize:** Distributed into 02-projects/, 03-learnings/, etc.
3. **Synthesize:** Extended thinking pass (`/dream`)
4. **Index:** Important insights → MEMORY.md
5. **Access:** Fast lookup via indexed memory

## Dream Sync

**When:** On-idle or nightly  
**What:** Extended thinking pass over vault  
**Output:** Updated MEMORY.md + daily memory file  
**Goal:** Extract patterns, connections, actionable insights

---

Created 2026-04-26

---

## Quick Start (Setup)

### 1. Clone the repo

```bash
cd /workspace
git clone http://localhost:3002/clawd/second-brain.git
cd second-brain
```

### 2. Start the vault server (headless)

The vault server provides a REST API for reading and writing notes without needing Obsidian Desktop.

```bash
# Start the vault server
OBSIDIAN_API_KEY=c3b35c9ff948d127ba46acad226ad3ab4b5992da0a53b4ffc1aae6d4c8cbb771 \
VAULT_PATH=/workspace/second-brain \
node vault-server.js &
```

The server runs on port **27123**.

### 3. Start the MCP bridge (optional)

For connecting to Bumblebee or other MCP clients:

```bash
./start-mcp.sh
```

### 4. Enable systemd auto-start (optional)

```bash
sudo cp vault-server.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now vault-server
```

---

## Daily Usage

### Capture a note

```bash
# Quick capture to inbox
echo "- $(date +%Y-%m-%d): Idea about X" >> 00-inbox/capture.md
```

### Read or write via API

```bash
# Read a note
curl -s \
  -H "Authorization: Bearer c3b35c9ff948d127ba46acad226ad3ab4b5992da0a53b4ffc1aae6d4c8cbb771" \
  "http://localhost:27123/vault/read?path=02-projects/gravl/status.md"

# List all notes
curl -s \
  -H "Authorization: Bearer c3b35c9ff948d127ba46acad226ad3ab4b5992da0a53b4ffc1aae6d4c8cbb771" \
  "http://localhost:27123/vault/list"
```

### Run dream sync manually

```bash
./dream-sync.sh
```

Or wait for the nightly cron job at 23:00.

### Git sync

```bash
# Pull changes from other devices
git pull origin master

# Commit and push
git add .
git commit -m "Update notes"
git push origin master
```

---

## Vault Server API

**Base URL:** `http://localhost:27123`  
**Auth:** Bearer token (`OBSIDIAN_API_KEY`)

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/vault/read` | GET | Read a note by `path` query param |
| `/vault/list` | GET | List all notes in the vault |
| `/vault/search` | GET | Search notes by `q` query param |

Example:

```bash
curl -s \
  -H "Authorization: Bearer <API_KEY>" \
  "http://localhost:27123/vault/search?q=gravl"
```

---

## Architecture

```
/workspace/second-brain/ (vault files)
        ↓
vault-server.js (Node.js REST API on port 27123)
Reads vault directly from disk
        ↓
obsidian-mcp-server (MCP Protocol bridge)
Provides tools for reading/writing vault
        ↓
Bumblebee (can read/write vault headless!)
```

---

## Tips

- **Capture fast, organize later.** Dump everything into 00-inbox/ first.
- **Use templates.** Copy from 07-templates/ for consistent structure.
- **Link notes.** Use `[[note-name]]` or `[text](path/to/note.md)` for connections.
- **Tag for discovery.** Add `#tag` anywhere for searchability.
- **Review weekly.** Move inbox items to proper folders during cleanup.

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| Vault server won't start | Check port 27123 is free: `lsof -i :27123` |
| Auth failed | Verify `OBSIDIAN_API_KEY` matches |
| MCP not connecting | Ensure vault-server is running first |
| Git conflicts | Pull before push: `git pull origin master` |

---

Created 2026-04-26
Updated 2026-04-29