{"id":51942134,"url":"https://github.com/maystudios/better-second-brain","last_synced_at":"2026-07-28T20:00:45.191Z","repository":{"id":365963491,"uuid":"1274510035","full_name":"maystudios/better-second-brain","owner":"maystudios","description":"Better Second Brain (BSB) — open-source, LLM-maintained knowledge base. Karpathy's LLM Wiki pattern + a knowledge graph (graphify), a self-improvement loop, and autonomous self-healing.","archived":false,"fork":false,"pushed_at":"2026-06-19T17:23:33.000Z","size":280,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T17:35:56.383Z","etag":null,"topics":["claude","graphify","knowledge-base","knowledge-graph","llm","obsidian","pkm","rag","second-brain","zettelkasten"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/maystudios.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-19T15:32:14.000Z","updated_at":"2026-06-19T17:23:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maystudios/better-second-brain","commit_stats":null,"previous_names":["maystudios/better-second-brain"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/maystudios/better-second-brain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maystudios%2Fbetter-second-brain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maystudios%2Fbetter-second-brain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maystudios%2Fbetter-second-brain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maystudios%2Fbetter-second-brain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maystudios","download_url":"https://codeload.github.com/maystudios/better-second-brain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maystudios%2Fbetter-second-brain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36006421,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-28T02:00:06.341Z","response_time":109,"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":["claude","graphify","knowledge-base","knowledge-graph","llm","obsidian","pkm","rag","second-brain","zettelkasten"],"created_at":"2026-07-28T20:00:44.355Z","updated_at":"2026-07-28T20:00:45.179Z","avatar_url":"https://github.com/maystudios.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Better Second Brain (BSB)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/maystudios/better-second-brain/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/maystudios/better-second-brain?style=flat-square\u0026logo=github\" alt=\"Stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/maystudios/better-second-brain/network/members\"\u003e\u003cimg src=\"https://img.shields.io/github/forks/maystudios/better-second-brain?style=flat-square\u0026logo=github\" alt=\"Forks\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/maystudios/better-second-brain/issues\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/maystudios/better-second-brain?style=flat-square\" alt=\"Issues\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/maystudios/better-second-brain/commits/main\"\u003e\u003cimg src=\"https://img.shields.io/github/last-commit/maystudios/better-second-brain?style=flat-square\" alt=\"Last commit\"\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/maystudios/better-second-brain?style=flat-square\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/built%20on-Karpathy%20LLM%20Wiki-8A2BE2?style=flat-square\" alt=\"Built on Karpathy's LLM Wiki\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Obsidian-vault-7C3AED?style=flat-square\u0026logo=obsidian\u0026logoColor=white\" alt=\"Obsidian vault\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/graph-graphify-2EA043?style=flat-square\" alt=\"graphify graph layer\"\u003e\n  \u003ca href=\"./benchmark/RESULTS.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/benchmarks-3%20runs%20%C2%B7%20measured-success?style=flat-square\" alt=\"Benchmarks: 3 runs, measured\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/demo.gif\" alt=\"Better Second Brain: one-paste install in an empty folder\" width=\"780\"\u003e\n\u003c/p\u003e\n\n\u003e An LLM-maintained knowledge base built on Andrej Karpathy's **LLM Wiki** pattern - and measurably *better*.\n\u003e Karpathy's pattern compiles your sources into a persistent, interlinked wiki instead of re-deriving answers\n\u003e from raw chunks on every query (RAG). **BSB keeps that, then adds three layers that close the gaps the original\n\u003e pattern leaves open:** an automatic knowledge **graph**, a self-**improvement** loop, and autonomous\n\u003e self-**healing**.\n\nBSB is an open-source template. Clone it, point it at your sources, and an LLM agent (Claude Code, Codex,\nOpenCode, …) maintains a trustworthy, browsable, version-controlled knowledge base for you. Ships configured for\n**software / tech reference**, but works for any domain - change one config block.\n\n---\n\n## ⚡ Install - paste this into your agent\n\nOpen an **empty folder** in Claude Code, Codex, or any coding agent and paste the prompt below. It clones BSB into\nthat folder and stands up a brand-new brain for *your* topic - nothing else to set up:\n\n```text\nSet up a \"Better Second Brain\" (BSB) in the CURRENT folder, following these steps exactly:\n\n1. Clone the template into this folder:\n   git clone https://github.com/maystudios/better-second-brain .\n   (If this folder is NOT empty, instead run:\n    git clone https://github.com/maystudios/better-second-brain bsb \u0026\u0026 cd bsb)\n2. Read CLAUDE.md - that file is now your operating schema; follow it for everything below.\n3. Ask me for my DOMAIN (what this brain is about) and a one-line LITMUS test, then initialize a fresh, empty brain:\n   python scripts/init_brain.py --domain \"\u003cMY DOMAIN\u003e\" --litmus \"\u003cMY LITMUS\u003e\" --fresh --yes\n4. Verify it is clean:\n   python scripts/verify_wikilinks.py   and   python scripts/lint_sources.py --summary\n5. Tell me the brain is ready and ask for my first source (a URL or file) to ingest into raw/.\n\nYou are now the maintainer of this brain. Never write a wiki page from your own memory - every page must be\ngrounded in at least 3 real, fetched sources (CLAUDE.md §1.5), and populate pages \"lean\" (§2.1). I curate the\nsources and ask the questions; you read, verify, summarize, file, and cross-reference.\n```\n\n**Already cloned it?** Run the shipped slash command **`/bsb-init`** in Claude Code, or\n`python scripts/init_brain.py --domain \"…\" --litmus \"…\" --fresh --yes`. Then open the folder as a vault in\n**Obsidian** (the human reader) next to your agent. Manual / Obsidian-first setup: [`docs/install.md`](./docs/install.md).\n\n---\n\n## Why this exists\n\nThe LLM Wiki pattern (Karpathy, April 2026 - [X post](https://x.com/karpathy/status/2039805659525644595),\n[gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)) is brilliant but deliberately minimal.\nIn practice it has three soft spots. BSB targets each one:\n\n| The gap in vanilla LLM-Wiki | BSB's answer |\n|---|---|\n| **You only find connections you think to ask about.** Cross-links are manual. | **graphify** builds a real knowledge graph over `raw/`+`wiki/` - community detection, hub (\"god\") nodes, *surprising connections*, GraphRAG queries - and feeds what it finds back into the lint loop. |\n| **The method never improves itself.** The schema is static; quality drifts. | **auto-research** periodically re-researches PKM/LLM-wiki best practices and proposes verified upgrades to the schema and page formats. The brain's *method* compounds, not just its data. |\n| **Pages rot. A wrong/outdated doc just sits there.** | **Self-healing**: because every page cites its sources, the brain re-verifies itself, detects superseded versions / dead links / unsupported claims, and fixes them - report-only, on-approval, or autonomously per area. |\n\nPlus a **research-discipline gate** the original lacks: *no page may be written from the model's memory* - every\npage must be grounded in ≥ 3 fetched primary sources, or it isn't written. That single rule is what makes the\nresult trustworthy instead of plausible-sounding slop.\n\n---\n\n## Architecture\n\nThree layers (Karpathy) + a temporal triad of control files:\n\n```\nraw/      immutable sources you curate   (the LLM only reads)\nwiki/     interlinked markdown pages      (the LLM owns + maintains)\n          ├ sources/ concepts/ entities/ cheatsheets/ syntheses/ moc/\nindex.md  what exists   ·  log.md  what happened  ·  roadmap.md  what's next\nCLAUDE.md the schema/rulebook the agent follows   (AGENTS.md = same, for Codex/OpenCode)\n```\n\nSix operations the agent runs: **Ingest · Query · Lint** (classic) + **Graph · Improve · Heal** (the \"better\" part).\nFull spec: [`CLAUDE.md`](./CLAUDE.md).\n\n---\n\n## Quickstart\n\nRequires **Python ≥ 3.10** (for the helper scripts) and git. Obsidian and graphify are optional.\n\n```bash\ngit clone https://github.com/maystudios/better-second-brain \"Second Brain\" \u0026\u0026 cd \"Second Brain\"\n# Open the folder as a vault in Obsidian (optional but recommended - it's the human reader).\n# Open the folder in Claude Code (or Codex/OpenCode) - the agent reads CLAUDE.md automatically.\n```\n\nThen, in the agent:\n\n1. **Make it yours** - edit the `DOMAIN` / `LITMUS` block in [`CLAUDE.md`](./CLAUDE.md) §0 and\n   [`bsb.config.md`](./bsb.config.md). (Skip to use the shipped software/PKM domain.)\n2. **Add a source** - drop a file in `raw/`, or say *\"ingest https://…\"*. The agent fetches it, writes a source\n   page, updates the affected wiki pages, and logs it.\n3. **Ask** - *\"what does the wiki say about X?\"* The agent reads `index.md`, the relevant pages, and answers with\n   citations - then offers to file good answers back as new pages.\n4. **Keep it healthy** - say *\"lint\"* periodically. Add the optional layers when you want them (below).\n\nFull setup, including the optional layers and git hooks: [`docs/install.md`](./docs/install.md).\n\n## The optional layers (off by default, degrade gracefully)\n\n- **graphify** - `uv tool install graphifyy`, then the agent uses the `/graphify` skill. → [`docs/graphify-integration.md`](./docs/graphify-integration.md)\n- **auto-research** - a Claude Code skill that self-improves the schema. → [`docs/auto-research-integration.md`](./docs/auto-research-integration.md)\n- **self-healing** - runs on the source-grade lint. → [`docs/self-healing.md`](./docs/self-healing.md)\n- **qmd** - local hybrid search when you outgrow `index.md`. → `github.com/tobi/qmd`\n\n## 📊 Is it actually better? (measured, not asserted)\n\nBSB ships a benchmark and **runs it**: the same fetched sources built two/three ways - a vanilla Karpathy wiki vs.\nBSB - answered against a gold question set, scored by an objective judge, with deterministic token accounting\n(`scripts/token_report.py`). Three runs so far (`uv`, `MCP`, `Ruff`). **Full data + caveats:\n[`benchmark/RESULTS.md`](./benchmark/RESULTS.md)** · method \u0026 how to run your own: [`docs/benchmark.md`](./docs/benchmark.md).\n\n\u003e **Strongest evidence - applied to a *real, pre-existing* 368-page second brain** (a hand-built game-dev wiki, in a\n\u003e domain BSB knew nothing about): the graph layer answered the same questions at **-23% real tokens / -56%\n\u003e read-footprint**, at equal quality. → [`benchmark/REAL-BRAIN.md`](./benchmark/REAL-BRAIN.md).\n\n**Headline - large run (Ruff, 15 sources, 14 questions, exact `tiktoken` counts):**\n\n| Arm | Quality /6 | Fill tokens | Links / 1k | Read / query | vs. raw |\n|---|:--:|--:|:--:|--:|:--:|\n| vanilla Karpathy | 5.64 | 7,485 | 12.0 | 1,296 | 6.1× |\n| BSB (full) | **5.93** | 22,366 | 20.8 | 1,042 | 7.6× |\n| **BSB-lean** | **5.93** | **7,648** | **31.0** | **442** | **17.9×** |\n\n- **Quality:** BSB beats a vanilla wiki by **+5-12%** across runs - the margin is **verifiable citation** (BSB cites\n  exact source URLs; vanilla cites bare filenames), not raw correctness.\n- **Reading is cheap and scales:** answering one query costs **2-18× fewer tokens** than reading the raw sources\n  (`bsb-lean` hit 17.9× on the large corpus).\n- **Filling is cheap too:** the **`bsb-lean`** fill mode matches full-BSB quality at **-66% fill tokens** (≈ a vanilla\n  wiki's cost) with the *densest* interconnection - so grounding + traceability cost essentially nothing extra. It's\n  the default ([`CLAUDE.md`](./CLAUDE.md) §2.1).\n- **Honest caveats:** small N (3 topics / 30 Q), not fully blinded, well-documented topics flatter the memory-only\n  arm; the \"edge grows with corpus size\" idea did *not* hold. A private/novel corpus is the next test.\n\n## Star history\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://star-history.com/#maystudios/better-second-brain\u0026Date\"\u003e\n    \u003cimg src=\"https://api.star-history.com/svg?repos=maystudios/better-second-brain\u0026type=Date\" alt=\"Star History Chart\" width=\"600\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nIf BSB is useful to you, a ⭐ helps other people find it.\n\n## Credit \u0026 license\n\nBuilt on Andrej Karpathy's LLM Wiki pattern. Graph layer by [graphify](https://github.com/safishamsi/graphify).\nRetrieval layer by [qmd](https://github.com/tobi/qmd). MIT licensed - see [`LICENSE`](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaystudios%2Fbetter-second-brain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaystudios%2Fbetter-second-brain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaystudios%2Fbetter-second-brain/lists"}