{"id":44585501,"url":"https://github.com/dinn0000/dotbrain","last_synced_at":"2026-06-26T07:01:30.497Z","repository":{"id":337750640,"uuid":"1154751098","full_name":"DinN0000/DotBrain","owner":"DinN0000","description":"AI-powered PKM organizer for macOS. Automatically classify files into PARA folders using Claude/Gemini.","archived":false,"fork":false,"pushed_at":"2026-03-23T08:51:43.000Z","size":2093,"stargazers_count":3,"open_issues_count":8,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-24T06:04:57.101Z","etag":null,"topics":["ai","knowledge-management","macos","menubar-app","obsidian","para-method","pkm","swift"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DinN0000.png","metadata":{"files":{"readme":"README.en.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.en.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.en.md","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-10T18:30:08.000Z","updated_at":"2026-03-23T08:51:11.000Z","dependencies_parsed_at":"2026-03-05T04:02:04.572Z","dependency_job_id":null,"html_url":"https://github.com/DinN0000/DotBrain","commit_stats":null,"previous_names":["dinn0000/ai-pkm-bar","dinn0000/dotbrain"],"tags_count":139,"template":false,"template_full_name":null,"purl":"pkg:github/DinN0000/DotBrain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DinN0000%2FDotBrain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DinN0000%2FDotBrain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DinN0000%2FDotBrain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DinN0000%2FDotBrain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DinN0000","download_url":"https://codeload.github.com/DinN0000/DotBrain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DinN0000%2FDotBrain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34806448,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"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","knowledge-management","macos","menubar-app","obsidian","para-method","pkm","swift"],"created_at":"2026-02-14T06:04:01.625Z","updated_at":"2026-06-26T07:01:30.488Z","avatar_url":"https://github.com/DinN0000.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"right\"\u003e\u003ca href=\"README.md\"\u003e한국어\u003c/a\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"Resources/app-icon.png\" width=\"128\" alt=\"DotBrain Icon\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eDotBrain\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eBuilt for Humans. Optimized for AI.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Swift-5.9-F05138?logo=swift\u0026logoColor=white\" alt=\"Swift 5.9\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/macOS-13%2B-000000?logo=apple\u0026logoColor=white\" alt=\"macOS 13+\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/DinN0000/DotBrain\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/DinN0000/DotBrain/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/DinN0000/DotBrain\" alt=\"Latest Release\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n[한국어](README.md) | **English**\n\nDotBrain systematically organizes your local documents using the PARA methodology.\u003cbr\u003e\nThis structure becomes an intuitive knowledge system for humans,\n\nand provides understandable Context for AI.\u003cbr\u003e\nThat Context serves as AI's exploration foundation, enabling it to understand and reason more deeply about your knowledge.\n\n```\n·‿·  →  ·_·!  →  ·_·…  →  ^‿^\n\n```\n\n---\n\n## 🧐 What is DotBrain?\n\nThe bottleneck in knowledge management isn't accumulation — it's **utilization**.\u003cbr\u003e\nInformation piles up easily,\u003cbr\u003e\nbut organizing it for easy retrieval and connecting context is hard.\n\nWhat's even harder is\u003cbr\u003e\nstructuring that knowledge into a form AI can understand and leverage.\n\n**The Problem: Human vs. AI**\n- **The PARA Dilemma (Human Overhead):** The PARA methodology works brilliantly for human cognition, but the maintenance cost of manually sorting everything each time is high. Eventually, organizing falls behind and files just pile up in the inbox.\n- **AI's Discord (Context Gap):** Disorganized documents make it difficult for even AI to grasp context. Simply storing files becomes nothing more than a useless data dump for both humans and AI.\n\n**The Solution: DotBrain**\nDotBrain delegates this 'organizing bottleneck' to AI.\n- **Zero-Friction Sort:** Drop files into the inbox and AI reads the content, automatically moving them according to the PARA framework.\n- **Semantic Structure:** Automatically generates Obsidian-compatible frontmatter and wiki-links to connect context between documents.\n- **Self-Healing:** Flattens nested folder structures, repairs broken links and missing frontmatter, and detects duplicate files via SHA256 hashing for merging.\n- **Reliability:** Supports both Claude and Gemini simultaneously, with an automatic fallback safety net — if one fails, the other takes over.\n\n---\n\n## 🚀 Quick Start\nInstall with a single line in your terminal.\n```bash\nnpx dotbrain\n```\n\nWhen `·‿·` appears in your menu bar, installation is complete. Click the icon to begin onboarding.\n\n\u003e 📖 For detailed usage instructions, see the **[Service Manual (MANUAL.md)](MANUAL.md)**.\n\n\u003e **Requirements:** macOS 13 (Ventura) or later / Node.js 18+ (when using npx) / Claude subscription (Pro/Max) + Claude CLI as default. [Claude API key](https://console.anthropic.com/settings/keys) or [Gemini API key](https://aistudio.google.com/apikey) also supported.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eBuild from source\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/DinN0000/DotBrain.git ~/Developer/DotBrain\ncd ~/Developer/DotBrain\nswift build -c release\n# Binary: .build/release/DotBrain\n```\n\u003c/details\u003e\n\n---\n\n## ⚙️ How it Works\n\n### Inbox Processing\n\nDrop files into the inbox and they are processed automatically:\n\n```\nAdd file to _Inbox/ (drag \u0026 drop)\n    ↓\nContent extraction (text/PDF/image/PPTX/XLSX/DOCX)\n    ↓\nTwo-stage AI classification\n    ├── Stage 1: Fast (Haiku/Flash) — batch classification\n    └── Stage 2: Precise (Sonnet/Pro) — only for low-confidence files\n    ↓\nFile move + frontmatter injection + related note linking + MOC update\n    ↓\nClassification complete\n```\n\n### AI Classification Strategy\n\n| Provider | Stage 1 (Fast) | Stage 2 (Precise) | Cost |\n|----------|----------------|-------------------|------|\n| **Claude CLI (recommended)** | Haiku | Sonnet | Uses subscription tokens |\n| Claude API | Haiku 4.5 | Sonnet 4.5 | ~$0.002/file |\n| Gemini API | Flash 2.5 | Pro 2.5 | Possible within free tier |\n\nMost files finish at Stage 1. Claude CLI uses subscription tokens, so there is no additional API cost.\n\n### Folder Reorganization\n\nAI re-organizes existing PARA folders:\n\n```\nSelect folder\n    ↓\nFlatten — move content from nested subfolders to top level (SHA256 deduplication)\n    ↓\nAI reclassification\n    ├── Correct location → update frontmatter\n    └── Wrong location → automatically move to correct folder\n```\n\n### Vault Management\n\n- **PARA Management** — move folders between categories, create projects, auto-organize per folder\n- **Full Reorganization** — AI scans the entire vault and suggests misclassification moves (executed after user approval)\n- **Vault Audit** — automatically fixes broken links and missing frontmatter\n\n### Frontmatter Standardization\n\nDotBrain applies a standard specification that both humans and AI can understand to every note.\n\n```yaml\n---\npara: project\ntags: [defi, ethereum, blockchain]\ncreated: 2026-02-11\nstatus: active\nsummary: \"DeFi system architecture project\"\nsource: import\nproject: MyProject\n---\n```\n\n| Field | Description |\n|-------|-------------|\n| `para` | PARA category (Project/Area/Resource/Archive) |\n| `tags` | Auto-tagged based on file content |\n| `created` | Original creation date (existing values preserved) |\n| `status` | active / draft / completed / on-hold |\n| `summary` | One-line summary of the file content |\n| `source` | original / meeting / literature / import |\n| `project` | Associated project name |\n| `area` | Associated Area name |\n| `projects` | List of associated projects (for documents within an Area) |\n| `file` | Original filename (for non-text files) |\n\n---\n\n## 📂 Folder Structure\nThe PKM (Personal Knowledge Management) folder structure managed by DotBrain.\n\n```\nPKM Root/\n├── _Inbox/                          ← Drop files here\n├── _Assets/                         ← Central storage for binary files\n│   ├── documents/                   ← PDF, DOCX, etc.\n│   ├── images/                      ← Images\n│   └── videos/                      ← Videos\n├── 1_Project/\n│   └── MyProject/\n│       ├── MyProject.md             ← Index note (auto-generated)\n│       └── plan.md\n├── 2_Area/\n│   └── DevOps/\n│       └── monitoring-guide.md\n├── 3_Resource/\n│   └── Python/\n│       └── asyncio-patterns.md\n└── 4_Archive/\n    └── 2024-Q1/\n        └── quarterly-report.md\n```\n\n## 🛠 Technical Details\n\n### Supported File Formats\n\n| Format | Extraction Method | Extracted Content |\n|--------|-------------------|-------------------|\n| `.md`, `.txt`, etc. | Direct read | Full text |\n| `.pdf` | PDFKit | Text + page count/author/title |\n| `.docx` | ZIPFoundation + XML | Body text + metadata |\n| `.pptx` | ZIPFoundation + XML | Slide text |\n| `.xlsx` | ZIPFoundation + XML | Cell data |\n| `.jpg`, `.png`, `.heic`, etc. | ImageIO | EXIF (date taken, camera, GPS) |\n| Folder | Internal file traversal | Aggregated content of contained files |\n\n### Duplicate Detection\n\n| Scenario | Detection Method | Action |\n|----------|------------------|--------|\n| Same content, different name | SHA256 body hash (excluding frontmatter) | Merge tags → delete |\n| Same content binary | SHA256 hash (≤500MB) or size+modified date (\u003e500MB) | Merge tags → delete |\n| Same name, different content | Filename comparison | Prompt user for confirmation |\n| Name conflict with index note | `foldername.md` comparison | Prompt user for confirmation |\n\n### Tech Stack\n\n- **Swift 5.9** + SwiftUI + Combine\n- **macOS menu bar app** — `NSStatusItem` + `NSPopover`\n- **AI** — Claude CLI (subscription, recommended) / Claude API / Gemini API — triple provider, automatic fallback\n- **Dependencies** — ZIPFoundation (DOCX/PPTX/XLSX processing)\n- **Security** — Claude CLI requires no API key (subscription auth). When using API keys, stored in AES-GCM encrypted files with device binding (hardware UUID + HKDF)\n- **Reliability** — Exponential backoff retry, provider fallback, path traversal protection\n\n---\n\n## 🎨 Design Philosophy\n\n### Making your context readable by AI\n\nAI makes judgments based on the material it's given.\nBut in most cases, users have to manually select and hand over files.\n\n- Passing individual files allows per-file analysis, but connecting context across documents is difficult\n- Passing everything at once hits context limits\n- The same background explanation must be repeated every conversation\n\nFor AI to leverage a user's entire knowledge, it needs a **structured knowledge base that AI can explore on its own**.\n\nDotBrain receives files, classifies them, assigns tags, and generates relationships between documents.\nWhen any AI tool opens this knowledge base, the structure alone enables it to navigate relevant context.\n\n### Frontmatter — Metadata for both humans and AI\n\nEvery file receives YAML frontmatter.\n\n```yaml\n---\npara: project\ntags: [defi, ethereum, blockchain]\nsummary: \"DeFi system architecture project\"\n---\n```\n\nFor humans, it's metadata that's immediately visible in Obsidian and directly editable.\nFor AI, it's structured data where classification, search, and summary information can be extracted in a single parse.\n\n**AI handles generation and management, while humans retain editing authority.**\nUsers are freed from the labor of manually filling in metadata, and AI gets consistently formatted data.\n\n### Wiki-links + MOC — A table of contents for humans, an index for AI\n\nEach folder gets an automatically generated MOC (Map of Content).\nAn MOC is an index note that lists all documents in a folder with `[[wiki-links]]` alongside **a summary of each document**.\n\n```markdown\n# MyProject\n\n\u003e System architecture project. Covers from architecture design to validation.\n\n## Documents\n- [[Architecture Design]] — Full system architecture design document\n- [[Meeting Notes 0211]] — 2nd requirements meeting. API integration approach finalized\n- [[Audit Report]] — Static analysis results and vulnerability remediation details\n```\n\nFor humans, these links are a clickable table of contents, and the summaries are guides that convey content without opening each file.\nFor AI, these links are graph edges, and the summaries are context for determining exploration priority.\nWhich document to read first, which document is relevant to the current question — all of this can be determined from the MOC alone.\n\n**The same structure works as navigation for humans and as an exploration graph for AI.**\n\n### AI Companion Files — Making your vault AI-ready\n\nDotBrain automatically generates AI companion files like `CLAUDE.md`, `AGENTS.md`, and `.cursorrules` in your vault.\nWith these files in place, AI tools like Claude Code or Cursor can immediately understand the folder structure, classification rules, and tag system when they open the vault.\n\nWithout reading the entire vault, a single companion file communicates **\"this knowledge base is organized like this, and follows these rules.\"**\n\nDuring updates, only the content between `\u003c!-- DotBrain:start --\u003e` / `\u003c!-- DotBrain:end --\u003e` markers is refreshed.\nAny content users have added outside the markers is preserved.\n\n### Humans define projects, AI handles classification\n\nThe PARA framework (Projects, Areas, Resources, Archive) provides the foundational structure for classification.\nWithin this structure, AI classifies files automatically.\n\nWhat the user does is **define projects**.\n\"PoC-Alpha\", \"Research-Beta\", \"DotBrain\" — only the user knows which projects are in progress.\nOnce projects are set, AI determines where each file belongs.\n\n---\n\nOnce the knowledge base is structured, AI goes beyond simple Q\u0026A.\nIt explores related materials on its own, discovers patterns in connections between documents, and reasons on top of the user's context.\n\nDotBrain creates that starting point.\n\n---\n\n## ❓ Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e\"Unidentified developer\" / \"Damaged and can't be opened\"\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nxattr -cr ~/Applications/DotBrain.app\n```\n\nOr: Go to **System Settings → Privacy \u0026 Security** → click \"Open Anyway\".\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eFolder access permission popup\u003c/b\u003e\u003c/summary\u003e\n\nOn first launch, you must select **\"Allow\"** when prompted for PKM folder access permission.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eIcon not visible in the menu bar\u003c/b\u003e\u003c/summary\u003e\n\nThis may be due to insufficient menu bar space. Remove other icons by ⌘+dragging them away, or use Bartender/Ice to manage them.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eUninstall\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nnpx dotbrain --uninstall\n```\n\nOr manually:\n```bash\npkill -f DotBrain 2\u003e/dev/null; \\\nlaunchctl bootout gui/$(id -u)/com.dotbrain.app 2\u003e/dev/null; \\\nrm -f ~/Library/LaunchAgents/com.dotbrain.app.plist; \\\nrm -rf ~/Applications/DotBrain.app; \\\necho \"Uninstall complete\"\n```\n\n\u003c/details\u003e\n\n---\n\n## 💬 So, what is DotBrain?\n\n\u003e DotBrain is an AI-powered PKM app that runs in the macOS menu bar.\n\u003e Drop files into the inbox and AI analyzes the content, automatically classifying them into the PARA structure, writing frontmatter, linking related notes, and generating MOCs — all handled for you.\n\u003e\n\u003e **It eliminates the time spent organizing notes.** Deciding where to put things, adding tags, finding and linking related documents — AI does all of that, so users only need to write and read. Instead of a note app where things pile up and never get revisited, everything organizes itself so you actually come back and use it.\n\u003e\n\u003e And the real key is that **when AI reads a vault organized this way, its performance dramatically improves.** Thanks to structured frontmatter, MOCs, and related note links, AI grasps context accurately and finds the documents it needs quickly. The better your knowledge is organized, the smarter AI works — that's the feedback loop.\n\u003e\n\u003e It's Obsidian-compatible, and automatically embeds agents for Claude Code and Cursor, so a single command like \"audit my vault\" runs a full health check.\n\n---\n\n\u003cp align=\"center\"\u003e\nMade by Hwaa\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdinn0000%2Fdotbrain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdinn0000%2Fdotbrain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdinn0000%2Fdotbrain/lists"}