{"id":48844762,"url":"https://github.com/arkangelai/second-brain","last_synced_at":"2026-04-15T04:03:59.339Z","repository":{"id":339487113,"uuid":"1162121835","full_name":"arkangelai/second-brain","owner":"arkangelai","description":"Local-first, AI-native knowledge management system. Markdown + QMD hybrid search + Obsidian + any AI agent.","archived":false,"fork":false,"pushed_at":"2026-03-29T20:31:21.000Z","size":249,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"initial-setup","last_synced_at":"2026-03-29T22:23:41.471Z","etag":null,"topics":["ai-agent","claude-code","knowledge-management","mcp","obsidian","qmd","second-brain","zettelkasten"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arkangelai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-19T22:26:38.000Z","updated_at":"2026-03-09T13:55:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/arkangelai/second-brain","commit_stats":null,"previous_names":["arkangelai/second-brain"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/arkangelai/second-brain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkangelai%2Fsecond-brain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkangelai%2Fsecond-brain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkangelai%2Fsecond-brain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkangelai%2Fsecond-brain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arkangelai","download_url":"https://codeload.github.com/arkangelai/second-brain/tar.gz/refs/heads/initial-setup","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkangelai%2Fsecond-brain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31825515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"online","status_checked_at":"2026-04-15T02:00:06.175Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","claude-code","knowledge-management","mcp","obsidian","qmd","second-brain","zettelkasten"],"created_at":"2026-04-15T04:03:58.769Z","updated_at":"2026-04-15T04:03:59.330Z","avatar_url":"https://github.com/arkangelai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Second Brain\n\nA local-first, AI-native knowledge management system. Markdown files + semantic search + any AI agent.\n\nBuilt on [QMD](https://github.com/tobi/qmd) (by Tobi Lutke) for hybrid search, [Obsidian](https://obsidian.md) for reading and navigating, and any AI coding agent for synthesis and content creation.\n\n**Zero cloud dependency for search. Everything runs on your machine.**\n\n---\n\n## Why This Exists\n\nMost \"second brain\" setups are passive filing cabinets. This one is designed to be **actively queried by AI agents** — meaning your notes become a searchable, citable knowledge base that any LLM can tap into.\n\nThe stack:\n\n| Layer | Tool | Purpose |\n|-------|------|---------|\n| **Storage** | Markdown files | Plain text, portable, future-proof |\n| **Reading** | [Obsidian](https://obsidian.md) | Visual navigation, `[[wiki links]]`, graph view |\n| **Search** | [QMD](https://github.com/tobi/qmd) | BM25 + vector + reranking — 100% local |\n| **Agent** | Any (Claude Code, Cursor, Codex, etc.) | Reads, searches, and creates from your vault |\n| **Sidebar** | [Claude Sidebar](https://github.com/derek-larson14/obsidian-claude-sidebar) | Claude Code terminal embedded in Obsidian |\n| **CLI** | `second-brain` | Setup, search, scaffold, and draft from the terminal |\n| **Publishing** | [Notion](https://notion.so) (optional) | Sync pipeline posts to a Notion database |\n\n---\n\n## Quickstart\n\n### Prerequisites\n\n- macOS, Linux, or Windows\n- [Bun](https://bun.sh) installed (`curl -fsSL https://bun.sh/install | bash`)\n- [Obsidian](https://obsidian.md) installed (free, for reading/navigating your vault)\n\n### Install\n\n```bash\ngit clone https://github.com/arkangelai/second-brain.git\ncd second-brain\nbun install\nbun link\n```\n\nThis installs dependencies and registers `second-brain` as a global command so it works from any directory (including Obsidian's Claude Sidebar).\n\n### One-command setup\n\n```bash\nsecond-brain init\n```\n\nThis installs QMD, creates your vault at `~/Documents/Second_Brain`, copies templates, indexes everything, and downloads the local AI models (~2GB on first run).\n\nCustom vault path:\n\n```bash\nsecond-brain init --vault ~/my-vault\n# or\nexport SECOND_BRAIN_PATH=~/my-vault\nsecond-brain init\n```\n\n### Open in Obsidian\n\n1. Open Obsidian\n2. Click \"Open folder as vault\"\n3. Select `~/Documents/Second_Brain`\n4. Done — you'll see wiki links, graph view, and full navigation\n\n### Activate Claude Sidebar\n\nThe `init` command automatically installs the [Claude Sidebar](https://github.com/derek-larson14/obsidian-claude-sidebar) plugin into your vault. To activate it:\n\n1. Restart Obsidian (or reload: `Cmd+Shift+P` → \"Reload app without saving\")\n2. Go to **Settings → Community Plugins → enable \"Claude Sidebar\"**\n\nThe plugin gives you a full Claude Code terminal right in your Obsidian sidebar — no need to switch between windows.\n\n**What you get:**\n- Embedded Claude Code terminal in Obsidian's sidebar panel\n- Multi-tab support — run multiple Claude instances simultaneously\n- Right-click any folder to launch Claude scoped to that directory\n- Send selected text or file paths directly to Claude\n- Drag-and-drop files onto the sidebar to reference them\n- Multi-backend support — switch between Claude Code, Codex, OpenCode, or Gemini CLI\n\n**Requirements:** [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code/overview) must be installed and authenticated. The plugin runs the CLI inside Obsidian — it doesn't call the API directly.\n\n### Your First Session\n\nOnce Obsidian is open and Claude Sidebar is active, click the Claude icon in the sidebar to start a terminal. Here's a three-step walkthrough to get your vault loaded and generating content:\n\n#### Step 1 — Set up your voice profile\n\nTell Claude about yourself so it can write in your voice. Paste this into the sidebar:\n\n```\nRead AGENTS.md to orient yourself, then open 06_system/content-engine/voice-profile.md.\n\nInterview me to fill it out: ask me about who I am, what I do, who my audience is,\nmy content pillars, my tone, and paste in any example posts I share. Update the file\nwith my answers as we go.\n```\n\nClaude will ask you questions about your background, audience, tone, and writing style, then fill in `voice-profile.md` for you.\n\n#### Step 2 — Feed your vault\n\nYour second brain is only as good as what's in it. Use the `/resource` command to import articles, YouTube videos, PDFs, or anything you've been thinking about:\n\n**Claude Code:**\n```\n/resource https://example.com/article-i-liked\n```\n\n**Any agent:**\n```\nRead 06_system/commands/resource.md and follow the instructions.\nInput: https://example.com/article-i-liked https://youtube.com/watch?v=video-id\n```\n\nYou can feed it anything — book highlights, podcast episodes, blog posts, research papers. Each URL gets summarized and saved as a formatted note with wiki links to related content. The more you add, the richer the output when you generate content later.\n\n#### Step 3 — Generate your first content\n\nNow that your vault has a voice profile and some source material, try generating your first draft:\n\n```bash\nsecond-brain draft \"a topic you care about\"\n```\n\nOr use the vault commands directly in any agent:\n\n**Claude Code:**\n```\n/research AI agents in healthcare\n```\n\n**Any agent:**\n```\nRead 06_system/commands/research.md and follow the instructions.\nTopic: AI agents in healthcare\n```\n\nFrom here, review what the agent generated, edit in Obsidian, and iterate. The more notes and feedback you add to `learnings.md`, the better the output gets over time.\n\n---\n\n## CLI Commands\n\n### `second-brain init`\n\nSet up vault, install QMD, create config, index.\n\n```bash\nsecond-brain init\nsecond-brain init --vault ~/custom/path\n```\n\n### `second-brain update`\n\nPull new templates (won't overwrite your files), update QMD, re-index.\n\n```bash\nsecond-brain update\n```\n\n### `second-brain status`\n\nFile counts per folder and QMD health check.\n\n```bash\nsecond-brain status\n```\n\n### `second-brain search \"query\"`\n\nHybrid search across your vault using QMD (BM25 + vector + reranking).\n\n```bash\nsecond-brain search \"growth strategies\"\nsecond-brain search \"AI in healthcare\"\n```\n\n### `second-brain create note \"title\"`\n\nScaffold a new atomic note in `01_thinking/notes/`.\n\n```bash\nsecond-brain create note \"quality is the hard part\"\n# → 01_thinking/notes/quality-is-the-hard-part.md\n```\n\n### `second-brain create post \"title\"`\n\nScaffold a new pipeline post in `03_creating/pipeline/`.\n\n```bash\nsecond-brain create post \"AI replacing docs\"\n# → 03_creating/pipeline/ai-replacing-docs.md\n```\n\n### `second-brain draft \"topic\"`\n\n**The killer feature.** Searches your vault, loads your voice profile + structures + learnings, assembles a rich prompt, and launches your AI agent.\n\n```bash\nsecond-brain draft \"leadership lessons\"\nsecond-brain draft \"AI in healthcare\" --agent cursor\nsecond-brain draft \"growth\" --agent codex\nsecond-brain draft \"founder content\" --agent gateway\n```\n\nAgent detection order: `claude` \u003e `cursor` \u003e `codex` \u003e `gateway` (gateway is used when an API key is configured).\n\nWhat happens:\n1. Searches vault via QMD for the 10 most relevant notes\n2. Reads your voice profile, structures, and learnings\n3. Assembles a prompt with all context + instructions\n4. Launches the detected agent (or saves `.draft-prompt.md` if none found)\n\n### `second-brain config \u003cset|get\u003e ...`\n\nConfigure AI Gateway credentials and default model:\n\n```bash\n# Save API key for gateway usage\nsecond-brain config set apiKey \"your_api_key\"\n\n# Save default model (optional)\nsecond-brain config set model \"deepinfra/deepseek-v3.2\"\n\n# Inspect current settings\nsecond-brain config get apiKey\nsecond-brain config get model\n```\n\nYou can also set the key via environment variable:\n\n```bash\nexport AI_GATEWAY_API_KEY=\"your_api_key\"\n```\n\nWhen using `--agent gateway`, the CLI sends the assembled draft prompt (including vault search context) to the Vercel AI Gateway API.\n\n### Notion Integration (`publish` / `pull`)\n\nSet up Notion once:\n\n```bash\n# 1) Export your integration token in shell\nexport NOTION_API_TOKEN=\"secret_...\"\n\n# 2) Run guided setup (paste database URL or ID when prompted)\nsecond-brain publish setup\n```\n\nWhat setup does:\n- Validates database access\n- Infers property mappings from your Notion schema\n- Saves Notion integration config to `~/.config/second-brain/config.json`\n- Stores auth as `\"$NOTION_API_TOKEN\"` reference in config\n\nPublish local pipeline posts to Notion:\n\n```bash\n# Publish ready posts from 03_creating/pipeline\nsecond-brain publish\n\n# Preview only (no writes)\nsecond-brain publish --dry-run\n\n# Publish all statuses, or only specific status\nsecond-brain publish --all\nsecond-brain publish --status ready\n\n# Publish one file\nsecond-brain publish \"my-post.md\"\n\n# Force update even if hash is unchanged\nsecond-brain publish --force\n```\n\nAfter a successful live publish/update, files are moved from `03_creating/pipeline/` to `04_published/`.\n\nPull Notion properties/metrics back into local markdown:\n\n```bash\n# Pull for all posts in 04_published\nsecond-brain pull\n\n# Pull one file\nsecond-brain pull \"my-post.md\"\n\n# Preview only (no file writes)\nsecond-brain pull --dry-run\n```\n\n`pull` updates mapped metadata fields and writes a `## Metrics` section in the markdown file when mapped pull fields are available.\n\n### Global Options\n\n```bash\n--vault \u003cpath\u003e      Override vault path\n--agent \u003cname\u003e      Agent for draft: claude, cursor, codex, gateway\n--model \u003cid\u003e        Model id for gateway draft requests\n--dry-run           Preview publish/pull actions without writing\n--force             Re-publish even when hash matches\n--all               Publish all pipeline posts regardless of status\n--status \u003cvalue\u003e    Publish only posts with this status\n--version, -v       Show version\n--help, -h          Show help\n```\n\n### Vault Path Resolution\n\nPriority order:\n1. `--vault` flag\n2. `$SECOND_BRAIN_PATH` environment variable\n3. `~/.config/second-brain/config.json`\n4. `~/Documents/Second_Brain` (default)\n\n---\n\n## Vault Commands\n\nYour vault ships with 4 agent-agnostic commands — prompt files in `06_system/commands/` that any CLI agent can read and execute. Claude Code users also get `/slash` commands automatically.\n\n| Command | What it does |\n|---------|-------------|\n| `/answer` | Answer a question using **only** vault content — no web |\n| `/research` | Research a topic with web + vault, create a sourced note |\n| `/resource` | Ingest URL(s) into the vault as formatted notes |\n| `/therapy` | Organize a brain dump into structured, linked notes |\n| `/ideas` | Fetch today's content ideas from Notion and optionally generate posts |\n| `/schedule` | Schedule ready pipeline posts to X/LinkedIn via Post-Bridge |\n\n### Usage\n\n**Claude Code** (slash commands work automatically):\n\n```\n/answer what is counter-positioning?\n/research AI agents in healthcare 2026\n/resource https://paulgraham.com/startupideas.html\n/therapy I've been thinking about three things: first, the way our product...\n```\n\n**Any other CLI agent** (Cursor, Codex, OpenCode, etc.):\n\nTell the agent to read the prompt file and follow it:\n\n```\nRead 06_system/commands/answer.md and follow the instructions.\nQuestion: what is counter-positioning?\n```\n\n```\nRead 06_system/commands/resource.md and follow the instructions.\nInput: https://paulgraham.com/startupideas.html\n```\n\n### When to use which command\n\n| Situation | Command |\n|-----------|---------|\n| You know it's in the vault | `/answer` — vault-only search, no web |\n| You need fresh external info | `/research` — web + vault, creates a note |\n| You have a URL to save | `/resource` — summarize + ingest |\n| Your head is full of ideas | `/therapy` — brain dump → structured notes |\n| You want today's content ideas | `/ideas` — fetch from Notion, optionally generate posts |\n| Ready posts need scheduling | `/schedule` — schedule to X/LinkedIn via Post-Bridge |\n\n### Customizing commands\n\nThe prompt files live in `06_system/commands/`. Edit them to match your workflow — change the note formats, default folders, output language, or add new commands.\n\nTo add a new command, create a new `.md` file in `06_system/commands/` with the prompt instructions. For Claude Code slash command support, also create a matching file in `.claude/commands/` with a `$ARGUMENTS` reference.\n\n---\n\n## Vault Structure\n\n```\nSecond_Brain/\n├── INDEX.md                  # Table of contents — start here\n├── AGENTS.md                 # Agent operating manual (the core prompt)\n│\n├── 00_inbox/                 # Capture zone. Drop anything here.\n├── 01_thinking/              # YOUR ideas + Maps of Content (MOCs)\n│   ├── growth.md             # MOC: growth, go-to-market, distribution\n│   ├── product.md            # MOC: product thinking, workflows\n│   ├── leadership.md         # MOC: leading teams, decisions\n│   ├── life.md               # MOC: personal reflections, identity\n│   ├── content-creation.md   # MOC: content engine, voice, pipeline\n│   └── notes/                # Atomic notes (your original thinking)\n├── 02_reference/             # External knowledge — don't modify\n│   ├── approaches/           # Strategies, case studies, methods\n│   ├── tools/                # Tool documentation and reviews\n│   └── sources/\n│       ├── books/            # Book notes and summaries\n│       ├── podcasts/         # Podcast episode notes\n│       └── articles/         # Article summaries\n├── 03_creating/              # Work in progress\n│   ├── drafts/               # General drafts\n│   ├── pipeline/             # Content ready to publish\n│   └── scheduled/            # Posts scheduled for future publish\n├── 04_published/             # Finished, published work\n├── 05_archive/               # Inactive content (out of sight, not deleted)\n└── 06_system/                # Templates, scripts, configuration\n    ├── commands/             # Agent command prompts\n    │   ├── answer.md         # /answer — ask the vault\n    │   ├── research.md       # /research — web + vault research\n    │   ├── resource.md       # /resource — ingest URLs\n    │   ├── therapy.md        # /therapy — brain dump → notes\n    │   ├── ideas.md           # /ideas — fetch content ideas from Notion\n    │   └── schedule.md       # /schedule — schedule posts to X/LinkedIn\n    ├── content-engine/\n    │   ├── voice-profile.md  # Your voice, audience, pillars, tone\n    │   ├── structures.md     # Proven post formats with templates\n    │   └── learnings.md      # Weekly reviews and running insights\n    ├── templates/\n    │   ├── note.md           # Template for new atomic notes\n    │   ├── moc.md            # Template for new MOCs\n    │   ├── book.md           # Template for book notes\n    │   └── pipeline-post.md  # Template for content pipeline posts\n    └── scripts/\n        └── txt-to-md.sh      # Convert .txt files to .md\n```\n\n---\n\n## Key Files Explained\n\n### `INDEX.md` — Your Table of Contents\n\nA flat list of every note in the vault with a one-line summary. This is the first thing an agent reads to orient itself.\n\n### `AGENTS.md` — The Agent Operating Manual\n\nThis is the most important file. It tells any AI agent:\n- **How to orient**: Structure → INDEX → MOC → Note (never skip steps)\n- **How to name notes**: As claims (`quality-is-the-hard-part.md`), not topics (`quality.md`)\n- **How to link**: `[[wiki links]]` inline, not reference lists\n- **How to update MOCs**: Add breadcrumbs for future sessions\n- **Philosophy**: Depth over breadth, network over perfection, curator not modifier\n\n### MOCs (Maps of Content) — Topic Hubs\n\nEach file in `01_thinking/` groups related notes with context. They accumulate \"breadcrumbs\" — observations the agent makes while navigating. This is how knowledge compounds across sessions.\n\n### `06_system/content-engine/` — Content Creation System\n\nThree files that turn your accumulated knowledge into published content:\n- `voice-profile.md` — Who you are, your audience, your tone\n- `structures.md` — Proven post formats with fill-in templates\n- `learnings.md` — What worked, what didn't, running insights\n\nSee the [Content Engine](#content-engine) section below for the full workflow.\n\n---\n\n## How QMD Search Works\n\nQMD provides three search modes, all running locally:\n\n```bash\nqmd search \"exact phrase\"       # Fast BM25 keyword search\nqmd vsearch \"concept or idea\"   # Semantic vector search\nqmd query \"broader topic\"       # Hybrid + reranking (best quality, slower)\n```\n\nOr use the CLI wrapper:\n\n```bash\nsecond-brain search \"broader topic\"   # Runs qmd query under the hood\n```\n\n### Under the Hood\n\n```\nYour Query\n    ↓\nQuery Expansion (Qwen3-1.7B) → generates 2 variants\n    ↓\nParallel search:\n  ├── BM25 (SQLite FTS5) ── keyword matching\n  └── Vector (sqlite-vec) ── semantic similarity\n    ↓\nReciprocal Rank Fusion → combines results\n    ↓\nLLM Reranking (Qwen3-0.6B) → reorders by relevance\n    ↓\nTop results with scores\n```\n\n### Local Models (downloaded automatically on first use)\n\n| Model | Size | Purpose |\n|-------|------|---------|\n| `embeddinggemma-300M` | ~300MB | Embeddings |\n| `qwen3-reranker-0.6B` | ~640MB | Reranking |\n| `qmd-query-expansion-1.7B` | ~1.1GB | Query expansion |\n\n### QMD as MCP Server\n\nQMD can run as an [MCP server](https://modelcontextprotocol.io), giving any compatible agent direct access to your vault:\n\n```bash\n# Start MCP server (stdio — for Claude Code, Cursor, etc.)\nqmd mcp\n\n# Start MCP server (HTTP — for remote agents)\nqmd mcp --http --port 8181\n```\n\n**Exposed tools via MCP:**\n- `qmd_search` — BM25 keyword search\n- `qmd_vector_search` — Semantic search\n- `qmd_deep_search` — Hybrid + reranking\n- `qmd_get` — Get document by path or docid\n- `qmd_multi_get` — Batch document retrieval\n- `qmd_status` — Index health check\n\n---\n\n## Using With Any AI Agent\n\nThe vault is agent-agnostic. Point any coding agent at `~/Documents/Second_Brain` and it works.\n\n### Claude Code\n\n```bash\n# Navigate to your vault\ncd ~/Documents/Second_Brain\n\n# Start Claude Code — it reads AGENTS.md automatically\nclaude\n```\n\nOr use QMD as an MCP server in `~/.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"qmd\": {\n      \"command\": \"qmd\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json` in your project:\n\n```json\n{\n  \"mcpServers\": {\n    \"qmd\": {\n      \"command\": \"qmd\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nOr simply open the vault folder in Cursor and paste the agent prompt from `AGENTS.md`.\n\n### OpenAI Codex CLI\n\n```bash\ncd ~/Documents/Second_Brain\ncodex\n```\n\nCodex will read the `AGENTS.md` file. You can also paste the agent instructions directly.\n\n### Any Other Agent\n\n1. Point the agent to `~/Documents/Second_Brain`\n2. Tell it to read `AGENTS.md` first\n3. It now knows how to navigate, search, and create in your vault\n\n---\n\n## First Prompts to Try\n\nOnce your vault is set up and you're inside an agent, try these:\n\n### 1. Orient the agent\n\n```\nRead AGENTS.md and INDEX.md. Give me a summary of what's in this vault.\n```\n\n### 2. Search your knowledge\n\n```\nSearch the vault for notes about [your topic]. Summarize the key insights\nand how they connect to each other.\n```\n\n### 3. Create a new note from an idea\n\n```\nI just learned that [insight]. Create a new atomic note in 01_thinking/notes/\nfollowing the naming conventions in AGENTS.md. Link it to any related\nexisting notes and update the relevant MOC.\n```\n\n### 4. Add a book or podcast\n\n```\nHere are my notes from [Book Title]: [paste notes]\n\nCreate a reference note in 02_reference/sources/books/ and connect it\nto relevant thinking notes. Update the INDEX.\n```\n\n### 5. Weekly review\n\n```\nSearch all notes modified this week. Summarize what was added,\nwhat connections were made, and suggest 3 notes that should exist\nbut don't yet. Add breadcrumbs to the relevant MOCs.\n```\n\n### 6. Draft content (or just use the CLI!)\n\n```bash\nsecond-brain draft \"your topic here\"\n```\n\n---\n\n## Content Engine\n\nThe real power of a second brain isn't storing information — it's **generating new things from everything you've accumulated**. Books, social media posts, articles, presentations, newsletters. The more you capture, the richer the output.\n\nThe content engine is the system that turns your vault into a publishing machine.\n\n### How It Works\n\n```\n  Your vault (months/years of notes, books, ideas, references)\n      ↓\n  second-brain draft \"topic\" (or agent searches manually)\n      ↓\n  Finds connections you didn't see\n      ↓\n  Drafts content in YOUR voice using YOUR structures\n      ↓\n  You review in Obsidian → edit → publish\n      ↓\n  Track what worked → feed learnings back into the system\n```\n\nThe key insight: **the agent has access to your entire history of thinking**. It doesn't just write from a prompt — it writes from hundreds of notes, book summaries, podcast insights, and your own accumulated observations. That's what makes the output uniquely yours.\n\n### Setup (One Time)\n\nEdit these three files in `06_system/content-engine/`:\n\n**1. `voice-profile.md`** — Teach the agent who you are:\n- Your company, audience, and content pillars\n- Your tone (direct? reflective? technical? casual?)\n- Paste 3-5 of your best posts as calibration examples\n- List what you do NOT sound like (corporate jargon, hype, etc.)\n\n**2. `structures.md`** — Give it proven formats to use:\n- 8 templates included (counterintuitive truth, hard truth list, personal lesson, etc.)\n- Each has a pattern, a fill-in template, and which platform it works for\n- Add your own as you find posts you love\n\n**3. `learnings.md`** — Build a feedback loop:\n- Weekly: what performed well, what didn't, why\n- Running insights that accumulate over time\n- The agent reads this before drafting to avoid repeating mistakes\n\n### Content Creation with the CLI\n\nThe fastest way to draft content:\n\n```bash\n# Draft posts about a topic\nsecond-brain draft \"leadership lessons\"\n\n# Use a specific agent\nsecond-brain draft \"AI in healthcare\" --agent cursor\n\n# Scaffold a pipeline post manually\nsecond-brain create post \"why quality compounds\"\n```\n\n### Content Creation with Agent Prompts\n\n#### Social media posts (X / LinkedIn)\n\n```\nRead voice-profile.md and structures.md from 06_system/content-engine/.\nThen search the vault for ideas about [topic].\n\nDraft 3 post options:\n- 1 for X (Twitter) using \"The Counterintuitive Truth\" structure\n- 1 for LinkedIn using \"The Personal Lesson\" structure\n- 1 for LinkedIn using \"The Framework Share\" structure\n\nUse insights from actual vault notes. Cite which notes inspired each post.\nCheck learnings.md to avoid patterns that underperformed.\n```\n\n#### Generate a week of content\n\n```\nRead voice-profile.md, structures.md, and learnings.md from the content engine.\nSearch the vault for the strongest ideas across all MOCs.\n\nPlan 5 posts for this week:\n- Mon: X post (observation or counterintuitive truth)\n- Tue: LinkedIn post (personal lesson)\n- Wed: X + LinkedIn (hard truth list or framework)\n- Thu: Product update / build in public (both platforms)\n- Fri: \"Here's what we're seeing\" or \"We used to think\" (both)\n\nFor each post: pick an idea, choose a structure, write the draft,\nand note which vault sources informed it.\nCreate each as a pipeline file in 03_creating/pipeline/.\n```\n\n#### Write an article or essay\n\n```\nI want to write a long-form article about [topic].\n\n1. Search the entire vault for related notes — books, podcast episodes,\n   approaches, and my own thinking notes\n2. Outline the article with sections, using the strongest insights\n   from across the vault\n3. For each section, cite the specific notes that support the argument\n4. Write the first draft (~1500 words), weaving together ideas from\n   different sources into a coherent narrative\n5. Use the voice from voice-profile.md\n\nSave the draft in 03_creating/drafts/.\n```\n\n#### Write a book chapter\n\n```\nI'm writing a book about [topic]. This is chapter [N]: [chapter title].\n\n1. Search the vault exhaustively — books I've read, podcast insights,\n   strategies, case studies, and my own thinking notes related to this chapter\n2. Create a detailed outline with the key arguments and supporting evidence\n3. Write the chapter draft (~3000 words), synthesizing insights\n   from across my entire knowledge base\n4. Include [[wiki links]] to source notes so I can verify and expand later\n5. Match the voice in voice-profile.md\n\nSave in 03_creating/drafts/book/chapter-[N]-[title].md\n```\n\n#### Write a newsletter edition\n\n```\nRead the content engine files and search the vault for the most\ninteresting ideas I've captured recently.\n\nWrite a newsletter edition:\n- Subject line: compelling, not clickbait\n- Opening: a personal hook or observation\n- Body: 2-3 insights from my vault, connected with a thread\n- Close: a question or takeaway for the reader\n- Tone: voice-profile.md\n\nSave in 03_creating/drafts/.\n```\n\n#### Repurpose existing content\n\n```\nRead [path to published post or article in 04_published/].\n\nNow search the vault for related notes that could expand on this.\nCreate 3 derivative pieces:\n1. A Twitter thread that breaks down the main argument\n2. A LinkedIn post with a different angle on the same idea\n3. A short article draft that goes deeper using vault sources\n\nSave all three in 03_creating/pipeline/.\n```\n\n### The Content Pipeline\n\nContent moves through folders as it progresses:\n\n```\n03_creating/drafts/      → work in progress, rough ideas\n03_creating/pipeline/    → ready to publish (status: ready)\n03_creating/scheduled/   → queued for a future date\n04_published/            → live, published content\n```\n\nEach pipeline file tracks metadata as bold key-value pairs:\n\n```markdown\n# Post Title\n\n**Status:** draft\n**Platform:** LinkedIn\n**Pillar:** Business Strategy\n**Structure:** The Personal Lesson\n**Source notes:** [[7-powers]], [[crossing-the-chasm]], [[blitzscaling]]\n\n## Core Idea\nWhat's the one takeaway?\n\n## Draft\nThe actual post text.\n\n## Notes\nRevisions, alternatives, performance after publishing.\n```\n\nWhen you run `second-brain publish`, ready posts in `03_creating/pipeline/` are pushed to Notion and automatically moved to `04_published/`. After publishing, use `second-brain pull` to sync metrics back from Notion into your local files. Log results in `learnings.md` to improve future drafts.\n\n### Why This Gets Better Over Time\n\nThe more you use it, the better it gets:\n\n1. **More notes = richer output.** A vault with 50 notes produces decent content. A vault with 500 notes produces content that connects ideas no human would think to combine.\n2. **Learnings compound.** The agent reads `learnings.md` before every draft. Patterns that work get reinforced. Patterns that don't get avoided.\n3. **MOC breadcrumbs guide the agent.** Every session leaves trails that make the next session smarter.\n4. **Your voice sharpens.** As you add best-performing posts to `voice-profile.md`, the agent's calibration improves.\n\n---\n\n## Updating\n\nWhen we release new templates, structures, or improvements:\n\n```bash\ncd second-brain\ngit pull\nbun install\nbun link\n\n# Pull new templates into your vault (won't overwrite your files)\nsecond-brain update\n```\n\n---\n\n## Maintenance\n\n```bash\n# After adding new markdown files:\nqmd update \u0026\u0026 qmd embed\n\n# After adding .txt files (converts to .md first):\n./06_system/scripts/txt-to-md.sh\n\n# Check vault health:\nsecond-brain status\n\n# Or directly:\nqmd status\n```\n\n### Important Rules\n\n- **Never run** `qmd collection add`, `qmd embed`, or `qmd update` automatically from an agent\n- **Never modify** the SQLite database directly\n- The index lives at `~/.cache/qmd/index.sqlite`\n- QMD models download automatically on first use (~2GB total)\n\n---\n\n## Customizing for Your Use Case\n\n### 1. Edit `AGENTS.md`\n\nAdapt the orientation protocol, naming conventions, and linking rules to your workflow.\n\n### 2. Edit the MOCs in `01_thinking/`\n\nReplace the example MOCs (growth, product, leadership, life, content-creation) with your own topics. Each MOC is a hub for a thinking area.\n\n### 3. Edit `voice-profile.md`\n\nReplace with your own voice, audience, pillars, and tone. This drives the content engine.\n\n### 4. Edit `structures.md`\n\nKeep the formats that work for you, remove the rest, add new ones as you find posts you love.\n\n### 5. Add QMD context annotations\n\n```bash\n# Add context to help QMD understand your collections\nqmd context add ~/Documents/Second_Brain \"Personal knowledge base with notes on business, AI, product, and leadership\"\nqmd context add ~/Documents/Second_Brain/02_reference/sources/books \"Book summaries and key insights\"\n```\n\n---\n\n## Optional Integrations\n\nThese are **entirely optional**. The vault works fully without them. Set them up when you're ready to publish content or use the AI gateway for drafting.\n\n### Notion (Publish \u0026 Pull)\n\nSync your content pipeline to a Notion database. Posts in `03_creating/pipeline/` get pushed to Notion, and metrics from Notion get pulled back into your local files.\n\n**What you need:**\n- A [Notion integration](https://www.notion.so/my-integrations) with access to your content database\n- The integration token (starts with `secret_...`)\n\n**Safe setup (3 steps):**\n\n```bash\n# Step 1: Add your Notion token to your shell environment.\n# Open ~/.zshrc (or ~/.bashrc) in a text editor and add:\nexport NOTION_API_TOKEN=\"secret_your_token_here\"\n\n# Then reload your shell:\nsource ~/.zshrc\n\n# Step 2: Run the guided setup (paste your database URL when prompted).\nsecond-brain publish setup\n\n# Step 3: Verify it worked.\nsecond-brain publish --dry-run\n```\n\nYour token is stored as an environment variable reference (`$NOTION_API_TOKEN`) in the config file — **the actual secret never touches the config**. This means your AI agents can read the config safely without seeing your credentials.\n\n**How it works:**\n- `second-brain publish` — pushes ready posts from `03_creating/pipeline/` to Notion, then moves them to `04_published/`\n- `second-brain publish --dry-run` — preview what would be published without writing\n- `second-brain pull` — syncs metrics and properties from Notion back into local markdown files\n- Files are tracked by SHA-256 hash, so unchanged files are skipped automatically\n\nSee the [CLI Commands](#notion-integration-publish--pull) section above for all flags and options.\n\n### AI Gateway (Draft Without a CLI Agent)\n\nIf you don't have Claude Code, Cursor, or Codex installed, you can still use `second-brain draft` via the AI Gateway — an OpenAI-compatible API endpoint that streams responses directly to your terminal.\n\n**What you need:**\n- An API key for the gateway (contact your team or provider)\n\n**Safe setup (2 steps):**\n\n```bash\n# Option A: Environment variable (recommended — never stored on disk)\nexport AI_GATEWAY_API_KEY=\"your_api_key\"\n\n# Option B: Store in config (masked when displayed)\nsecond-brain config set apiKey \"your_api_key\"\n\n# Optional: change the default model\nsecond-brain config set model \"deepinfra/deepseek-v3.2\"\n```\n\n**How it works:**\n- The gateway is auto-detected as the last fallback when no CLI agent is found but an API key is configured\n- Override explicitly with `--agent gateway`\n- Output streams to your terminal and is saved as a pipeline post in `03_creating/pipeline/`\n\n```bash\nsecond-brain draft \"leadership lessons\" --agent gateway\nsecond-brain draft \"AI in healthcare\" --agent gateway --model \"deepinfra/deepseek-v3.2\"\n```\n\n### Post-Bridge (Social Media Scheduling)\n\nSchedule posts from your content pipeline directly to X and LinkedIn. Posts in `03_creating/pipeline/` with status `ready` are sent to the Post-Bridge API, which handles the actual publishing at the scheduled time.\n\n**What you need:**\n- A [Post-Bridge](https://post-bridge.com) account with connected social accounts\n- An API key from Post-Bridge\n\n**Safe setup (3 steps):**\n\n```bash\n# Step 1: Add your Post-Bridge API key to your shell environment.\n# Open ~/.zshrc (or ~/.bashrc) and add:\nexport POST_BRIDGE_API_KEY=\"your_api_key_here\"\n\n# Then reload your shell:\nsource ~/.zshrc\n\n# Step 2: Install dependencies and discover your social accounts.\ncd tools/post-bridge \u0026\u0026 bun install\nbun run src/index.ts accounts\n\n# Step 3: Verify it worked.\nbun run src/index.ts list\n```\n\n**How it works:**\n- `/schedule` command (or `bun run schedule-week`) scans the pipeline for ready posts\n- Each post is scheduled to X, LinkedIn, or both based on its `Platform` field\n- Posts are scheduled one per weekday (Mon-Fri) at 08:00 COT by default\n- The pipeline file's `Publish date` field is updated automatically\n\n```bash\n# Schedule a single post\nbun --cwd tools/post-bridge run src/index.ts schedule my-post.md --date 2026-03-02\n\n# Auto-schedule all ready posts starting next Monday\nbun --cwd tools/post-bridge run src/index.ts schedule-week --start 2026-03-02\n\n# Check scheduled posts\nbun --cwd tools/post-bridge run src/index.ts list --status scheduled\n\n# Check publish results\nbun --cwd tools/post-bridge run src/index.ts results\n```\n\n### Security Notes\n\nAll integrations follow the same principle: **secrets live in your shell environment, not in files agents can read**.\n\n| Secret | How to set | Stored as |\n|--------|-----------|-----------|\n| `NOTION_API_TOKEN` | Shell environment (`~/.zshrc`) | `\"$NOTION_API_TOKEN\"` reference in config |\n| `AI_GATEWAY_API_KEY` | Shell environment or `config set apiKey` | Env var (preferred) or config file |\n| `POST_BRIDGE_API_KEY` | Shell environment (`~/.zshrc`) | Env var only (not stored in config) |\n\nThe config file at `~/.config/second-brain/config.json` stores Notion auth as an environment variable reference string, not the raw token. The `config get apiKey` command masks the key (shows only first 4 and last 4 characters). This means you can safely let any AI agent read your vault and config without exposing credentials.\n\n---\n\n## How It All Connects\n\n```\n┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n│  You write   │────▶│  QMD indexes │────▶│  Agent reads │\n│  in Obsidian │     │  locally     │     │  and searches│\n└─────────────┘     └─────────────┘     └─────────────┘\n       │                                        │\n       │              ┌─────────────┐           │\n       └──────────────│  Agent adds  │◀──────────┘\n                      │  notes, links│\n                      │  breadcrumbs │\n                      └─────────────┘\n```\n\n1. **You capture** ideas in Obsidian (or any text editor)\n2. **QMD indexes** everything locally (BM25 + vectors)\n3. **Any AI agent** searches and reads via QMD or direct file access\n4. **The agent creates** new notes, adds links, updates MOCs\n5. **You review** in Obsidian — approve, edit, or discard\n6. **Knowledge compounds** across sessions via MOC breadcrumbs\n\n---\n\n## Tech Stack\n\n| Component | Technology |\n|-----------|------------|\n| Files | Markdown (.md) |\n| Reader | Obsidian (free) |\n| Obsidian plugin | [Claude Sidebar](https://github.com/derek-larson14/obsidian-claude-sidebar) v1.7.1 |\n| CLI | `@arkangelai/second-brain` (Bun, zero deps) |\n| Search engine | QMD |\n| Database | SQLite + FTS5 + sqlite-vec |\n| Embeddings | EmbeddingGemma-300M (GGUF, local) |\n| Reranking | Qwen3-0.6B (GGUF, local) |\n| Query expansion | Qwen3-1.7B (GGUF, local) |\n| LLM runtime | node-llama-cpp |\n| Package manager | Bun |\n| Agent protocol | MCP (Model Context Protocol) |\n| Publishing | Notion API (`@notionhq/client`) — optional |\n| Scheduling | Post-Bridge API (`tools/post-bridge/`) — optional |\n| AI Gateway | Vercel AI Gateway (OpenAI-compatible) — optional |\n\n---\n\n## License\n\nMIT\n\n---\n\nBuilt by [Arkangel AI](https://arkangel.ai). We build AI tools for healthcare.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farkangelai%2Fsecond-brain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farkangelai%2Fsecond-brain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farkangelai%2Fsecond-brain/lists"}