{"id":50864819,"url":"https://github.com/tpierrain/second-brain-generator","last_synced_at":"2026-06-15T00:03:33.489Z","repository":{"id":362455380,"uuid":"1257591931","full_name":"tpierrain/second-brain-generator","owner":"tpierrain","description":"Install and configure your own second brain: a private, personal, and robust assistant inside Claude that forgets nothing, helps you connect the dots, and makes you far more effective on your day-to-day tasks (semantic search via RAG included).","archived":false,"fork":false,"pushed_at":"2026-06-11T16:38:57.000Z","size":3260,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-11T18:13:02.272Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tpierrain.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":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-02T20:33:39.000Z","updated_at":"2026-06-11T17:46:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tpierrain/second-brain-generator","commit_stats":null,"previous_names":["tpierrain/second-brain-generator"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/tpierrain/second-brain-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpierrain%2Fsecond-brain-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpierrain%2Fsecond-brain-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpierrain%2Fsecond-brain-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpierrain%2Fsecond-brain-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tpierrain","download_url":"https://codeload.github.com/tpierrain/second-brain-generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tpierrain%2Fsecond-brain-generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34342089,"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-14T02:00:07.365Z","response_time":62,"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":[],"created_at":"2026-06-15T00:03:29.254Z","updated_at":"2026-06-15T00:03:33.469Z","avatar_url":"https://github.com/tpierrain.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"docs/img/kenjaku.png\" alt=\"Kenjaku — the Second Brain Generator's mascot\" align=\"right\" width=\"160\"\u003e\n\n# Kenjaku — Second Brain Generator \u0026nbsp;\u003cimg src=\"docs/img/rag-inside.svg\" alt=\"RAG inside\" height=\"34\" valign=\"middle\"\u003e\n\n*By Thomas Pierrain (VP Tech at [shodo](https://shodo.io/))*\n\n[![Latest release](https://img.shields.io/github/v/release/tpierrain/second-brain-generator?sort=semver\u0026display_name=tag\u0026label=latest\u0026color=7c4dff\u0026style=flat-square\u0026logo=github\u0026logoColor=white)](https://github.com/tpierrain/second-brain-generator/releases/latest)\n\u0026nbsp;[![Engine: self-upgradable since v3.0.0](https://img.shields.io/badge/engine-self--upgradable%20since%20v3.0.0-651fff?style=flat-square\u0026logo=rocket\u0026logoColor=white)](#keeping-your-brain-up-to-date-its-engine)\n\u0026nbsp;[![Privacy: local by default](https://img.shields.io/badge/privacy-local%20by%20default-3d5afe?style=flat-square\u0026logo=lock\u0026logoColor=white)](#and-the-privacy-of-my-data)\n\u0026nbsp;[![Runs on macOS and Windows](https://img.shields.io/badge/runs%20on-macOS%20%C2%B7%20Windows-2979ff?style=flat-square)](#ready-to-try-it)\n\n**Ask it like you'd ask a personal assistant — no dev skills required — and pull up any decision or piece of info from your work in seconds, always with the sources.**\n*In Claude Desktop or on the command line, your call.*\n\n**🔒 Private by default, search à la carte.** Your notes are indexed **on your machine by default — nothing leaves it**. Or hand the job to the API of your choice, right down to your company's own endpoint: **you decide who touches your data**.\n\n**🛟 Bulletproof \u0026 zero chores.** Backup, freshness, recovery after a glitch: **its** job, not yours. *You just have to talk.*\n\n**🔄 Self-upgradable — new in v3.0.0.** Your brain keeps **its own engine** up to date: *ask in plain words, confirm,* and it pulls the latest search engine — **without ever touching a single one of your notes.** No terminal, no re-install. *([how it works](#keeping-your-brain-up-to-date-its-engine))*\n\n**[🧠 What's a second brain?](#what-is-a-second-brain) · [🚀 Install yours now](#ready-to-try-it) · [📖 View the articles](#the-article-series)**\n\n\u003e 🧑 *\"Where are we on the billing project — who owns what, and what's been decided?\"*\n\u003e\n\u003e 🧠 *\"At the January 15 team sync: the database was settled (PostgreSQL over MongoDB),\n\u003e and Jane Doe — platform Tech Lead — is pushing to get ahead of technical debt as early\n\u003e as sprint 1.*\n\u003e *→ decision of January 10 · → team sync of January 15\"*\n\n\u003e 🧑 *\"What does 'MEDDIC' mean — that thing the sales team keeps repeating in their meetings?\"*\n\u003e\n\u003e 🧠 *\"MEDDIC = the opportunity-qualification method adopted by sales: Metrics, Economic\n\u003e buyer, Decision criteria, Decision process, Identify pain, Champion. Introduced by John Smith (VP\n\u003e Sales) at the sales kickoff on February 12 to make the forecast more reliable.*\n\u003e *→ sales kickoff of February 12 · → sales playbook\"*\n\nInstead of digging through Slack, your emails, Google Drive and your meeting notes yourself, you\njust ask — and your **second brain** answers right away, with the sources to back it up. It\n**retrieves by meaning**, so you can ask in French about notes written in English (or the other way\naround).\n\n\u003e ⚠️ This repo is **not** a ready-made brain: it's a **generator** that **produces** a **seed** (a\n\u003e skeleton) for you, which you grow into **one of your own**. We explain why below — and that's\n\u003e exactly what makes it useful.\n\n---\n\n## What is a \"second brain\"?\n\nA **memory external to you**: your notes, your decisions and your work exchanges gathered in one\nplace, that you query in natural language and that answers you **instantly, with the sources to back\nit up**.\n\nA few properties define it:\n\n- **It's yours.** Everything lives in a folder of notes (a *vault*) versioned in **your private git\n  repo**. You're not renting from an online service: you own your data.\n- **It remembers.** Every answer, every new piece of info is persisted (local git commit). Your\n  brain builds up an actionable record — and can **follow you from one machine to another** as soon\n  as you wire it to a remote repository (optional).\n- **It keeps itself up to date — on its own.** Once you've connected your sources (Slack, Drive,\n  email, calendar, meeting transcripts…), it **pulls in what's new automatically**, with **no explicit\n  request from you**: you never have to tell it to \"go sync\". When you ask a question, it quietly\n  catches up in the background and folds anything new into its answer.\n- **It cites its sources.** No answers out of thin air: you can always trace back to the original\n  note or message, with its date.\n\n\u003e 📂 **An open, human-readable format.** The substrate of your second brain is just a set of\n\u003e **Markdown (`.md`)** files — linked together with `[[wikilink]]` links where it makes sense (a\n\u003e note points to a person, a decision, a topic…). Nothing proprietary, nothing locked in.\n\n\u003e 🪨 **Bonus — turn it into a full read/write app with [Obsidian](https://obsidian.md).** The vault\n\u003e is **Obsidian-compatible by design**. Install Obsidian (free), point it at your `vault/` folder, and\n\u003e you instantly get a **visual reading *and* writing interface** over **every Markdown note in your\n\u003e brain**: browse and edit notes, follow the `[[wikilinks]]`, and explore the **graph** of your\n\u003e knowledge. Best of all, it's the **exact same files** Claude works on — so whether you ask Claude or\n\u003e edit directly in Obsidian, both stay perfectly in sync. Two front doors, one brain, zero lock-in.\n\n![Obsidian graph view of a real second brain: hundreds of Markdown notes (1-1s, decisions, meetings, people…) linked together into a knowledge graph, with the folder tree on the left](docs/img/obsidian-graph-view.png)\n\n\u003e \u003csub\u003e☝️ A real brain seen in Obsidian — each dot is a note, each line a `[[wikilink]]`. The folder tree on the left (decisions, meetings, people, prep-1-1…) and the graph are *exactly* what Claude reads and writes.\u003c/sub\u003e\n\n\u003e 💡 **And honestly — the graph isn't the point.** Pretty as that constellation is, and fun to spin\n\u003e around, it's rarely a *useful* view day-to-day. Where Obsidian truly earns its place is as a\n\u003e **polished, advanced Markdown reader and editor**: comfortable reading, live preview, instant local\n\u003e search — and the freedom to **edit a note by hand** whenever you'd rather type than ask Claude.\n\u003e And since these are the very files your brain runs on, anything you tweak in Obsidian is **autosaved\n\u003e and automatically re-indexed within seconds** (a live watcher re-embeds the modified note), so your\n\u003e brain's search stays current — no \"save\" button, no \"sync\", nothing to do by hand.\n\n## Who is it for?\n\nFor anyone who's **drowning in scattered information** and wants to retrieve it effortlessly —\nwhatever their technical level:\n\n- **Managers, Heads of Engineering** — keeping track of their teams, their 1-1s, what's expected of\n  them.\n- **Product managers, product designers** — keeping the thread of product decisions, trade-offs, the\n  \"why we settled on it this way\".\n- **Consultants, researchers, freelancers** — consolidating a business domain, never losing any of a\n  client's context.\n\n👉 **No need to be a geek.** This brain is designed for people who **aren't technical** but who\nalready work with **Claude Desktop** (Code tab). If you can *chat* with Claude, you can use it — and\nit works **just as well on Claude Desktop as on the command line** (CLI), your call.\n\n\u003e ⚠️ **Day-to-day use requires no technical skill**: you ask questions, you read answers. Only the\n\u003e **installation** (once, ~15 min) assumes you have git and Node (and, *if* you choose the API-key\n\u003e option, a key) — we guide you step by step, and an installer checks everything for you.\n\n## How is it different from ChatGPT, Claude, Notion AI or Slack search?\n\n| | What they're missing | What your second brain does |\n|---|---|---|\n| **Bare ChatGPT / Claude** | Only knows what you re-paste into each conversation. Forgets it all afterward. | A **persistent memory**, that grows with every question. |\n| **Notion AI, Slack search…** | Walled into **a single tool**. | **Cross-cutting**: Slack + Drive + emails + transcripts + your notes, all in one place. |\n| **Any SaaS** | Your data on a third party, closed format. | **At home**, in Markdown, in **your** private git repo. |\n| **\"Cloud-only\" AI tools** | A **search engine forced on you**: to index you, your notes go off to a third party — with no alternative. | **Semantic search à la carte**: **local by default** (nothing leaves), or delegated to the API of your choice — [you choose](#how-do-i-choose-my-semantic-search-my-rag). |\n\nAnd above all: this isn't **one** product for everyone. It's a **method** to build **your own**,\ntuned to *your* uses (see \"*Why a generator and not a finished product?*\").\n\n## How is it different from the \"LLM wikis\" and DIY second brains floating around on social media?\n\n🛠️ **\"But a second brain is really just a Markdown folder + a rules file you feed to Claude,\nright?\"** Done carelessly, it **looks** like it works… then it **fails silently** — the worst kind\nof failure, because you don't even notice (nothing's saved, search **makes things up** instead of\nsearching your notes, the session isn't wired to the right place…). Here, **packaged and tested\nguardrails** plug those holes: once installed, **there's nothing left for you to do** — backup,\nindexing and freshness all run on their own, without you having to think about them. That's\n**affordance**: the complexity is **hidden, not dumped on you**.\n\n**Concretely, all the engineering work runs for you — silently.** Incremental indexing, versioned\nbackup on **every** change, **atomic** writes, index freshness handled for you, **non-blocking**\nstartup of the search engine, multi-machine sync, and **deterministic** checks that *prove* the\nanswer really comes from **your notes** (and not from the Internet). We **designed, tested and\npackaged** it to be **robust and reproducible** — not a script that \"works on my machine\". The goal\nwe set ourselves: **the only thing left for you to do is talk to your brain in natural language.**\nThe infra, the storage, the concurrency, the guardrails: that's **its** job — it was built for that\n— **not yours**.\n\n\u003e 🛟 **Why such care?** Because building **production-ready** software — that **recovers on its own**\n\u003e when something breaks — is a conviction **Thomas, its creator, has carried throughout his whole\n\u003e career**, nurtured by **Recovery-Oriented Computing** (ROC — A. Fox \u0026 D. Patterson): you **assume\n\u003e everything eventually breaks**, and you design so that **recovery** is fast, automatic and **with\n\u003e no data loss**. A second brain has to last **years** — not just long enough for a demo.\n\n\u003e 📄 The details (and the full picture — the brain, how it works, the installation, the **RAG à la\n\u003e carte**): see the [**How it's different**](EN-QUOI-C-EST-DIFFERENT.md) page.\n\n## What it changes for you, concretely\n\n- **Immediate answer.** In a few seconds, no time to go grab a coffee.\n- **Always sourced.** You see where each piece of info comes from, and whether it's recent or not.\n- **Nothing gets lost.** Every change is **committed automatically, locally**. And if you wire up a\n  **remote repository** (optional, ~2 min — push *opt-in*), everything is also backed up **off your\n  machine**: laptop lost or stolen, you pick up where you left off elsewhere.\n- **Private by default — and you're the one who chooses.** Your notes are indexed **on your machine**\n  by default: nothing leaves. Small machine or Intel Mac? You can delegate to the API of your choice.\n  *(To decide: [\"how do I choose my semantic search\"](#how-do-i-choose-my-semantic-search-my-rag).)*\n- **Zero effort on your part.** You never have to kick off a sync, or even know that git exists: you\n  ask your question, that's it.\n\n\u003e 💡 For the curious: your answer arrives right away from what your brain already has in memory, and\n\u003e updates quietly in the background if it finds something new — a bit like a web page that displays\n\u003e instantly then refreshes on its own. The details are in [under the hood](#under-the-hood).\n\n## Not sure what to ask it? Start here\n\nA few opening lines to get going — just talk to it the way you'd brief an assistant. Bonus: each one\nis also a quiet way to **confirm a connector is wired up** (the first time it reaches into a given\ntool, Claude asks permission — click **\"Always allow\"**, once).\n\n- **📅 Your calendar** — *\"What do I have on tomorrow?\"* · *\"What does my week look like?\"*\n  → checks it can reach your **calendar**.\n- **📝 Your meeting transcripts** — *\"Can you give me a recap of yesterday's product sync — the\n  decisions and who owns what?\"*\n  → checks it can pull in your **meeting transcripts**.\n- **✅ What's expected of you (across every source)** — *\"What am I on the hook for this week?\"* ·\n  *\"What am I expected to deliver tomorrow?\"*\n  → gathers the actions assigned to you **across Slack, meeting transcripts and emails**, in one shot.\n- **📧 Your emails** — *\"Did I get an email from Acme about the renewal?\"* · *\"Anything I missed from\n  the client this week?\"*\n  → checks it can reach your **inbox**.\n- **🧠 Your own notes \u0026 decisions** — *\"Why did we settle on PostgreSQL?\"* · *\"Who owns the billing\n  project, and what's been decided?\"*\n  → searches **your vault** — and always answers **with the sources**.\n\n\u003e 💬 No magic keywords, no syntax to learn: phrase it however feels natural, in any language. If a\n\u003e source isn't connected yet, it'll simply tell you — see [wiring up your sources](#wiring-up-your-sources-connectors).\n\n---\n\n\u003e 🚀 **Install in one paste — Claude does the rest.** Pick your privacy option, check what you need,\n\u003e and copy the single instruction below. ~15 minutes, once.\n\n\u003ca id=\"ready-to-try-it\"\u003e\u003c/a\u003e\n\n## 🚀 Ready to try it? — install your brain in one paste\n\n**Your only hands-on move:** open Claude and paste this one sentence (adapt the name \u0026 URL).\n\n```text\nInstall me a second brain named \"second-brain\" (name to be confirmed) from this generator: https://github.com/tpierrain/second-brain-generator\n```\n\nThat's the whole manual part — **no cloning, no commands, no key to wrangle in chat.** Claude does\neverything else for you. Here's what happens behind the scenes 👇\n\n\u003e 👉 **The one thing to keep in mind:** what you're pasting into right now is the **installer**. Your\n\u003e **second brain is a *separate place*** that Claude opens for you at the very **end** — you don't ask\n\u003e it questions *here*. That last hop (open your brain in a **brand-new** conversation) is the single\n\u003e step people miss — we flag it loud and clear when you get there.\n\n![Install flow in four steps: clone the launcher → answer 4 questions in chat → the brain folder is created → open your brain in a brand-new conversation](docs/img/install-flow.svg)\n\n\u003ca id=\"how-do-i-choose-my-semantic-search-my-rag\"\u003e\u003c/a\u003e\n\n### 🧭 How do I choose my semantic search (my RAG)?\n\nThis is **the** privacy choice, and it boils down to one question: *who's allowed to read your notes\nto index them?* Three answers — and you can **change your mind whenever you want** (we re-index in a\nfew minutes, nothing is lost):\n\n| Option | Engine \u0026 model | For whom | Privacy | Cost |\n|---|---|---|---|---|\n| 🟢 **On your machine** *(recommended default)* | 📱 **EmbeddingGemma-300M** (local, ONNX) | Machine with ≥ 12 GB RAM, not an Intel Mac | **Nothing leaves** your computer | Free |\n| 🟡 **With an API key** | **`gemini-embedding-001`** — or OpenAI / Mistral / OpenAI-compatible | Small setup, or Intel Mac | Your notes go through the provider — Gemini, OpenAI, **your company's endpoint** | ~€0.10 / 1,000 notes · ~€1 / 10,000 |\n| 🟢 **Ollama, locally** *(advanced)* | Any Ollama model — e.g. **`bge-m3`** | Comfortable installing an app | **Nothing leaves** either | Free |\n\n\u003e 📱 **Why \"on your machine\" is so light:** **EmbeddingGemma** is Google's embedding model **designed\n\u003e to run on-device — even on a phone**. So it sits comfortably on a laptop, with nothing leaving it.\n\n\u003e 💶 With an API key, Gemini's **free** tier is enough to get started. Depending on the provider \u0026 plan,\n\u003e pick the right settings so your notes aren't used for training (e.g. enable billing — a few cents per\n\u003e year — or a \"no-training\" / data-controls option). Details: [SETUP §9](SETUP.md).\n\nAt install time, Claude presents the 3 options and **recommends based on your machine**; with no\npreference, the local default applies on its own if the machine can handle it. *(The \"how it works\":\n[\"the RAG à la carte\"](#-the-rag-à-la-carte--you-choose-who-vectorizes-your-notes).)*\n\n### 📦 What you need\n\n- **[Claude Code](https://claude.com/claude-code)**, **[Node.js](https://nodejs.org) ≥ 18** and\n  **git**. *(The installer checks everything — if one is missing, it tells you cleanly.)*\n- **For semantic search**: nothing more if you go with the **local** option (the recommended\n  default), or an **[API key](https://aistudio.google.com/apikey)** if you choose that option — see\n  [\"how to choose\"](#how-do-i-choose-my-semantic-search-my-rag) above.\n- **Your information sources** (Slack, Drive, emails, Notion, transcripts…), to wire up according to\n  *your* tools. Optional to begin with. *(see [SETUP §6](SETUP.md))*\n\n### ⚙️ Installation — Claude installs everything for you\n\nYou use Claude Code and you have the generator's URL? Let **Claude install everything for you** —\nthat's the only move you make. Open Claude Code in **any empty folder on your machine** (a temporary\nworking directory will do — it's just where the launcher gets cloned), and **copy-paste this single\ninstruction** (adapt the name and URL):\n\n```text\nInstall me a second brain named \"second-brain\" (name to be confirmed) from this generator: https://github.com/tpierrain/second-brain-generator\n```\n\n\u003e 📍 **And my brain, where does it land?** **Not in this current folder**: by default it's created in\n\u003e your home (`~/\u003cname\u003e`). The directory you launch Claude from only serves to host the (disposable)\n\u003e clone of the launcher. For another location, specify it in the instruction (\"…in `~/brains`\") — no\n\u003e need to put yourself there.\n\nThat's it: no need to say \"don't touch the launcher\" or \"don't ask for my key\" — **the generator\nenforces safety itself** (the launcher stays read-only, the brain is a fresh folder with no remote\nlink, the key is never asked for in chat). Claude clones the **launcher**, asks you **in chat** the\nfew questions (brain name, location, your name, language), then runs the installer in non-interactive\nmode — which **creates the brain folder** and does **everything** (copy, generated files, `git init`,\nRAG engine, verification). The install can't **half-succeed**: either it goes all the way and\n**proves it to you** (it verifies for itself that search really answers from your notes), or it\n**stops dead and tells you why** — **never a ghost install** that looks OK but doesn't work. That\nleaves you **3 moves**:\n\n1. **🔑 A key to paste — only if you chose the \"API key\" option.** With the local option (the default),\n   **you skip this move**, nothing to paste. Otherwise, Claude guides you to paste your key into\n   `.env` (never in chat) — details [SETUP §1.1](SETUP.md).\n2. **💾 Remote repository?** Claude will ask whether you want a **remote** git repository (backup +\n   multi-machine). **Saying no is risk-free**: everything stays versioned locally, nothing is lost,\n   and auto-commit **pushes nowhere** (push opt-in disabled by default). You can add one later.\n3. **🧠 Leave the installer — open your brain in a *brand-new* conversation.** Not this one: start a\n   **new** conversation (CLI) / **new session** (Desktop) **in the brain folder that was created**\n   (e.g. `~/second-brain`) — *that* is what activates the search engine. ⚠️ **Just switching the\n   folder of *this* conversation won't work** — it has to be a new one. (The installer itself can be\n   reused for another brain or deleted.)\n   👉 **This is the step most often missed on Claude Desktop — see just below.**\n\n#### 🖱️ On Claude Desktop (Code tab): opening your brain in the RIGHT place\n\nThis is **the** #1 trap, and it's not obvious at all. Your brain only \"works\" if the conversation is\n**properly opened in its folder**. Starting a *New session* isn't enough: by default it reopens on\nyour last folder (often a `tmp`), and Claude then **makes up answers** instead of searching your\nvault.\n\nThe setting is made with **the row of little chips at the bottom, just above the input field**:\n\n![The row of chips Local · folder · ➕ at the bottom of the new session](docs/img/desktop-folder-chips.png)\n\n1. Open a **New session**.\n2. **Click the FOLDER CHIP** (the one showing `tmp` or some other name) — ⚠️ **NOT** the\n   `➕` \"Add another folder\" button: that one *adds* a folder **without replacing** the root, and the\n   brain doesn't load. That's the classic trap.\n3. A **\"Recent\"** menu opens, with a **✓ on the current folder**. **Click your brain's name** (e.g.\n   `second-brain`). If it's not listed, take **\"Open folder…\"** at the very bottom.\n\n![The Recent menu: click the brain's name so the ✓ moves to it](docs/img/desktop-recent-menu.png)\n\n4. The **✓ jumps to your brain**, and the bottom chip shows its name (no more `tmp`). ✅\n5. **Double-check in one word**: type `pwd` as your very first message → it should return the path of\n   your brain, **not** a `…/tmp`.\n\n\u003e ⌨️ **On the terminal (CLI)**, it's foolproof: `cd ~/second-brain \u0026\u0026 claude` — the session opens\n\u003e directly in the right folder, no ambiguity.\n\nOnce installed, try something like:\n\n\u003e *\"At the outfit that helps folks quit overworking, which worker got publicly honored for having loafed the most of anyone — and at what percentage?\"*\n\nClaude searches your vault and answers with links to the source notes. **Correct answer: Pélagie de\nMollecuisse, winner of the Inertia Trophy with a DNR of 98.7%** — a fact **impossible to find\noutside your vault** (the company \"Flemmr\" is made up). If Claude gives you that, you have **proof**\nthat it really queried your brain and not the Internet. If it answers that it doesn't know this\ncompany, then the RAG isn't running.\n\n\u003e 💡 Why this question **always** works: the subject is **made up**, so Claude has no answer in memory\n\u003e → it's *forced* to query the vault (for a public topic like Star Wars, it would answer off the top\n\u003e of its head without searching). And the question **describes** the situation through synonyms: none\n\u003e of its words appear in the notes → a plain \"search the files\" (grep) would fail. If \"Mollecuisse\"\n\u003e comes out anyway, it means search made the connection **by meaning**.\n\n\u003e 🧪 **The example notes.** The vault ships with a few demo notes around a **made-up parody company**\n\u003e (Flemmr, which \"industrializes procrastination\") — just enough for the first question to work right\n\u003e away, and **impossible to confuse** with real work notes. Keep them as templates, or wipe them when\n\u003e you start your real vault (delete the files in the `vault/` folder, or rerun the installer in\n\u003e interactive mode, which offers to empty them).\n\n### Behind the scenes of the installation — launcher vs brain\n\n*(For the curious — you don't need to understand this to use it.)*\n\n**One launcher, one brain — two folders.** You give **one single instruction** to Claude; it takes\ncare of fetching the **launcher** (this generator) and **creating a separate brain folder** where it\nputs everything. The launcher is **never modified**: it stays **read-only** and **reusable** — one\nlauncher can generate several brains.\n\n```\nYou give ONE instruction to Claude Code:\n        │   \"Install me a second brain named \"second-brain\" (name to be confirmed)\n        │     from this generator: https://github.com/tpierrain/second-brain-generator\"\n        ▼\n    📁 second-brain-generator/   ← the LAUNCHER (Claude clones it): read-only, reusable, never modified\n        │\n        │   Claude runs the installer in it  →  which CREATES a folder ELSEWHERE\n        ▼\n    📁 ~/second-brain/            ← YOUR second brain: a FRESH folder (files copied + git init)\n        ├── CLAUDE.md          (your constitution — generated from the bootstrap stub)\n        ├── vault/             (your notes)\n        ├── rag/               (the search engine)\n        ├── .git/              (FRESH repo, 0 remote — no link to the launcher)\n        └── .mcp.json, .env …  (generated config)\n        │\n        │   you reopen Claude Code INSIDE the brain\n        ▼\n    → you ask your questions\n        │\n        │   (optional, whenever you want) you ask Claude, INSIDE your brain:\n        │   \"Push my second brain to a remote GitHub repository (for a backup)\"\n        ▼\n    ☁️  remote repository        ← backup + multi-machine (push opt-in, see § Backing up)\n```\n\nTo clear up the doubts we all have at first:\n\n- **The launcher is not your brain**: it's the tool that **produces** it. Keep it to generate\n  others, or throw it away — your brain lives in **its own folder**.\n- **No link to the launcher**, by construction: the installer **copies** the files into a fresh\n  folder then runs `git init` in it (0 remote). Nothing to \"detach\" yourself.\n- **`--name` = the name of the created brain folder**; its location is chosen with `--dest` (by\n  default, your home → `~/\u003cname\u003e`). The installer **refuses if the folder already exists**.\n- The brain is born **without a remote repository**: for backup / multi-machine, you wire up YOUR\n  repo later (push opt-in, see move 2 above).\n\n### 💾 Backing up your brain \u0026 using it on multiple machines (optional)\n\nBy default, your brain is **versioned locally** (every change is committed automatically) but **stays\non your machine** — nothing goes elsewhere. To have an **off-machine backup** and/or use it **from\nseveral computers**, wire it to a **remote git repository**: **GitHub**, GitLab, Azure DevOps, or\nyour own git server.\n\n- **During installation**: Claude **offers it directly** (move 2) and configures everything.\n- **Later**: three commands (`git remote add` → `git push -u` → enable auto-push), step by step in\n  [SETUP §7](SETUP.md).\n\nIt's **opt-in**: as long as you haven't wired it up, **nothing is pushed** (anti-leak guardrail by\ndefault). You can do it right away **or weeks later**, without breaking anything. Once in place, the\nauto-commit hook **pushes on every change** — backup and switching between laptops become seamless.\n\n## 🔄 Keeping your brain up to date (its engine)\n\n\u003e 🆕 **New in v3.0.0.** Brains generated from **v3.0.0 onward** ship with this built-in updater — so\n\u003e they keep improving long after install day, opt-in and on your say-so.\n\nYour brain runs on an **engine** — the search code, the launchers and a handful of housekeeping\nscripts. Over time that engine improves (faster search, new safeguards, fixes). The good news:\n**your brain knows how to upgrade its own engine — and it never touches a single one of your notes.**\n\nA few plain ideas first (the mental model):\n\n- **The launcher was a one-time thing.** You used the installer (the *launcher*) **once**, on install\n  day. To upgrade later you **don't re-run it**, and you **don't start over from a fresh launcher\n  folder** — you don't even reopen it.\n- **Your brain carries its own updater.** Every brain ships with a small built-in updater\n  (`update-engine`) that travels **inside** the brain. Upgrading is just asking your brain to use it.\n- **`engine-manifest.json` is the map.** A readable file in your brain that spells out exactly *what\n  counts as the engine* — and records *where* a newer engine can be pulled from (the launcher's\n  address + the exact version your engine was built from). It's how the brain tells what is \"engine\"\n  (upgradable) from what is **yours** (off-limits).\n- **An upgrade is a throw-away errand.** When you accept one, the brain fetches a **temporary,\n  disposable copy** of the newer engine into a temp folder, takes only the engine pieces it needs,\n  applies them, then **deletes that temp folder.** Nothing lingers, no new folder left on your machine.\n\n**What you actually do — nothing technical:**\n\n\u003e 🧑 *\"Update your engine, please.\"*\n\u003e\n\u003e 🧠 *\"You're on engine v3.0.0; v3.1.0 is available — want me to update? Your notes won't be touched.\"*\n\u003e → you say **yes**.\n\nThat's the whole thing: **ask in plain words, confirm.** No terminal, no installer, no new folder.\n(Because your brain can *see* its own version, it may even **offer** the update on its own.)\n\n**Sacred — never touched by an update:** your **notes**, your `.env` (keys), your **`CLAUDE.md`**\nconstitution, your **settings** and your **custom skills**. An update only ever swaps **engine**\nfiles, and it **re-indexes only if** the new engine changed the index format (a few minutes) —\notherwise your search keeps working untouched.\n\n\u003e 🔧 **What you need at upgrade time** (same as install): **git**, **npm** and a **network**\n\u003e connection — the brain briefly reaches out to fetch the newer engine. *(That `npm` step just\n\u003e installs the search engine's **dependencies on your machine**; it does **not** pull your brain from\n\u003e any app store or central registry — your brain stays **self-hosted**, exactly as it was generated.)*\n\nThe hands-on steps (and how to run it yourself, if you're technical) are in\n[SETUP §10](SETUP.md).\n\n## And the privacy of my data?\n\nA fair question: your vault can be **confidential**. Depending on the search option you chose, **one\nor two** services may see your content — and **in every case, the right plan/settings keep it from\nbeing used for training** (and in fully-local mode, the indexing engine sees **nothing**):\n\n- **Claude** (which reasons and answers) reads your vault. On **API / Team / Enterprise**, your data\n  is **not** used for training. On the **consumer** plan (claude.ai Free/Pro/Max), go to\n  **Settings → Privacy** and **uncheck** the use of your conversations for model improvement.\n- **The indexing engine** receives the **text of your notes** — *only* if you chose the **API key**\n  option (Gemini, OpenAI, company endpoint). With the **local** or **Ollama** option, **nothing\n  leaves**: your notes never leave your machine. ℹ️ And if you go through **Gemini on the free tier**,\n  Google **may use** that content to improve its products (human review possible): **turning on billing\n  / data controls** keeps it out of training (Google then commits to **not** using it for training).\n\n**The most private is also the recommended default** (fully-local); and even with the key option, for\nthe price of a coffee a year your data leaves the training scope. Details and pricing chart:\n[SETUP §9](SETUP.md). *(Providers' terms change: check them.)*\n\n---\n\n## Why a *generator*, and not a finished product?\n\nBecause a second brain is **personal**. What serves a Head of Engineering, a salesperson or a\nresearcher has **nothing in common**. A single tool for everyone would be bland for each of them.\n\nSo this repo gives you **the ready-to-use machinery** (the search engine) and **a method** — the\n*use case driven* approach of **Thomas Pierrain** ([his article series](#the-article-series)) — to\nlet **your own uses emerge** as you ask questions. You start from a seed; you grow it by using it.\n\n**Everyone has their own instance.** A colleague who wants theirs **starts from the same launcher**\nand **generates** their own brain. You don't share one second brain between several people — you\nshare the generator.\n\nThat's also why the `CLAUDE.md` (the rules Claude follows) is **your constitution**, specific to\n*your* uses: the installer **generates** it custom for you. The launcher only contains a **bootstrap\nstub** that signals to Claude that it's still a generator (and guides you to the installer); the\ninstaller **generates your real constitution in the brain folder** — and **never** touches the\nlauncher's bootstrap stub (which stays reusable).\n\n## Safe by construction: it observes, it answers\n\nYour second brain **takes no action** on your tools. It **reads and it answers**, period. No\nsurprises, nothing going out in your name: it's a design choice, and it's what makes it easy to adopt\nwith peace of mind.\n\n\u003e And if one day you want it to: as you grow it, we can add **action capabilities** (a draft email, a\n\u003e Notion page, a Slack message to approve…), **deliberately and under your control**. Never by\n\u003e default, never behind your back.\n\n## Tailor it to your use cases\n\nA second brain is only worth anything **tuned to your activity**: your needs, the kind of questions\nyou ask, the kind of exchange you want to have with it. *You're* the one who defines that.\n\nIt **arrives already equipped** with a few **ready-to-use skills** — for instance an **\"in-your-face\"\ncoach** in the spirit of *Radical Candor* (brutally honest **and** caring), who challenges you when\nyou've got your head down in the weeds. But these are only **starting points**: the whole point is\nthat it stays **flexible**. Notes in **open Markdown**, skills, the `CLAUDE.md` constitution — **its\nentire structure has been thought out and arranged to be reshaped** to *your* uses: you add, modify or\nremove skills, you refine its rules, as you go. It **grows with you**; it doesn't force you into a\nmold.\n\n**Example — for Thomas Pierrain, *Head of Engineering*** — his second brain helps him to:\n\n- **keep track of his collaborators**, the people he coaches and mentors;\n- **get himself challenged** when he's got his head down in the weeds, in a role where you can\n  sometimes feel alone;\n- **consolidate advanced client business concepts** (here accounting and taxation);\n- **tell business acronyms apart from application acronyms** — quickly recover the meaning mid-meeting,\n  without interrupting everyone;\n- **map out the teams**: who owns which topic, at any moment;\n- **always know what's expected of him, and what he expects from others**.\n\nNone of that is shipped: those are **his** specifics. The generator doesn't try to replicate them —\nit gives you the engine and the method to let **your own** emerge.\n\n## The article series\n\nThe \"why\" behind this repo — to be read in order, each episode tells one step (and its owned-up\nmissteps):\n\n1. [My second brain pivoted twice in 3 days](https://medium.com/@tpierrain/my-second-brain-pivoted-twice-in-3-days-0e6a723faf34)\n2. [I hired a no-bullshit coach in my second brain](https://medium.com/@tpierrain/i-hired-a-no-bullshit-coach-in-my-second-brain-e7b1ce5702c5)\n3. [Why my second brain was talking without understanding](https://medium.com/@tpierrain/why-my-second-brain-was-talking-without-understanding-103d5c305341)\n4. [Embeddings and RAG explained to my parents](https://medium.com/@tpierrain/embeddings-and-rag-explained-to-my-parents-006f76dd4c14)\n\n---\n\n## Under the hood\n\n*This section is for the curious and the technical. You don't need to read it to use your second\nbrain.*\n\n### The design stance: answer right away, verify afterward\n\nEverything is designed **experience first**: you want an answer in a few seconds to *every* question\n— not to wait for an agent to finish re-digging through all your tools.\n\nSo the second brain **answers immediately** from what it already has in memory (the vault), via\n**semantic search** (it finds a note even when phrased differently, not by exact keywords). While\nyou're reading, agents **re-verify in the background** the external sources and only **amend** the\nanswer if there's something new. It's the *stale-while-revalidate* pattern from the web applied to\nyour memory: speed comes first, freshness follows.\n\nOn every question, the brain **catches up**: it pulls in what's happened anew since last time (in\n**delta mode** — only the new bits) and persists everything in the Markdown vault, versioned by git.\n\n### The 4-phase flow\n\n```\nQuestion\n   │\n   ▼  PHASE 1 — Immediate answer from the vault (semantic search)\n   │\n   ├──▶ PHASE 2 — (optional) Sync external sources in the background\n   │\n   ▼  PHASE 3 — Amend the answer if something new is found\n   │\n   ▼  PHASE 4 — Persistence: everything is saved in the vault + auto-commit\n```\n\nThe **RAG engine** splits each note into *chunks* (one per section), turns them into vectors\n(*embeddings*) and retrieves the passages closest to the **meaning** of your question. The index\nrebuilds itself, incrementally; a git hook **commits** on every change (and **pushes** only if you've\nwired up a remote repository — *opt-in*).\n\n#### 🍽️ The RAG à la carte — you choose who vectorizes your notes\n\nVectorization (the *embedding*) is **the only moment** when the text of your notes can leave your\nmachine — so we make it **a conscious choice**, not a default you're stuck with. The **embedding\nengine** (the *embedder*) is interchangeable: a small **local** model (by default), an **API key**\n(Gemini, OpenAI, or a compatible endpoint — including your company's), or **Ollama** locally. The\ndecision table is higher up, in\n[\"how do I choose my semantic search\"](#how-do-i-choose-my-semantic-search-my-rag).\n\n\u003e 🧠 The embedder is **not** \"ChatGPT at home\": it's just the librarian that files your notes by\n\u003e meaning. **The brain that reasons and answers you stays Claude**, whatever your choice.\n\n### What's in the box\n\n| Element | Role | Status |\n|---|---|---|\n| **`rag/`** | RAG engine (TypeScript MCP server): chunking, embeddings **à la carte** (local / API key / Ollama), semantic search, quota guardrails | ✅ ready to use |\n| **`vault/`** | Your Markdown content (example notes included) | 🔧 to fill in |\n| **`CLAUDE.md`** | The rules Claude follows (4-phase flow, conventions, posture) | 🌱 bootstrap stub in the launcher → the installer **generates** a personalized version **in the brain**, then to be tailored |\n| **`.claude/skills/`** | Shipped skills (see below) + ideas for other skills | 🔧 to flesh out |\n| **`.claude/settings.json`** | Hooks (auto-commit, startup status) + permissions | ✅ generated |\n| **`scripts/*.mjs`** | Cross-OS Node hooks: repo + RAG state at startup, auto-commit | ✅ ready |\n| **`installer.mjs`** | Installer: **creates the brain folder** from the launcher (macOS / Linux / Windows) | ✅ |\n\n### The skills you call\n\nThe generator stays deliberately **frugal**. The ones you invoke day to day:\n\n| Skill | What it does |\n|---|---|\n| **`/coach`** | **\"In-your-face\" coach**, a sparring partner wired to your vault, *Radical Candor* spirit (caring AND brutally honest): it challenges your decisions, names your blind spots. *Self-coaching only.* |\n| **`/prepare-1-1`** | Prepares a 1-1 **both ways**: with **your manager** or with someone **you manage** (tracking commitments, KPI review). Cross-references the person's profile + last 1-1 + recent signals. |\n| **`/improve`** | Evolves your harness: reads the frictions, proposes and applies the useful improvements. |\n| **`/sync`** | Syncs your repo between machines — useful mostly if you have **several laptops**. Rarely needed day to day. |\n\n### The internal tooling (you don't call it)\n\nThese elements are part of the machinery: you don't have to know them. It's just good to know they\nexist.\n\n| Element | Role | What triggers it |\n|---|---|---|\n| **`sync-sources`** | Pulls the **delta** of external sources in parallel **read-only** sub-agents — the engine behind Phase 2. 🔧 to wire to your connectors. | **your questions** (never you) |\n| **auto-commit hook** | **Commits** your vault on every change (and **pushes** it if you've enabled a remote repository — *opt-in*, off by default). This is what means a **non-technical** profile **never has to know git** — everything is versioned on its own, locally, nothing gets lost; wire up a remote repository and you switch laptops without a thought. | automatic |\n| **`tdd-discipline`** | Vendored TDD discipline — used to develop *the harness itself*. | Claude, when modifying the harness |\n\nThe rest is **not shipped**: those are **skill ideas** to let emerge as you need them, detailed in\n[`.claude/skills/EXAMPLES.md`](.claude/skills/EXAMPLES.md). For example: `briefing-journee` (morning\nbriefing), `briefing` (recap after an absence), `prepare-meeting`, `rapport-etonnement`,\n`weekly-review`.\n\n\u003e **Skill ≠ connector.** Slack, Drive, Notion, Calendar are **connectors** (data sources), not\n\u003e skills. You wire them up in the installer ([SETUP §6](SETUP.md)). A *skill* is a procedure that\n\u003e leverages these sources — it's up to you to write it.\n\n### The vocabulary in 30 seconds\n\n\u003cdetails\u003e\n\u003csummary\u003eUnfold the mini-glossary\u003c/summary\u003e\n\n- **Vault** — the folder where your notes live (in Markdown).\n- **RAG / semantic search** — the tech that finds a note by the *meaning* of your question, not by\n  exact keywords.\n- **Embeddings** — the translation of a text into numbers, to compare *meanings* with each other.\n- **Skill** — a procedure you trigger (e.g. \"prepare my 1-1\").\n- **Connector** — a hookup to one of your sources (Slack, Drive, Notion…). Two forms: **native**\n  (enabled in your Claude account settings) or **MCP** (a server declared in `.mcp.json`).\n- **Harness** — the set of rules (`CLAUDE.md`) + skills that you personalize.\n- **Hook** — an automatic action triggered by an event (e.g. save on every change).\n- **Installer** — the program that sets everything up for you.\n- **Repo / git** — the versioned place where everything is stored and backed up.\n\n\u003c/details\u003e\n\n---\n\n## Wiring up your sources (connectors)\n\nThe RAG engine answers from **your notes**. For it to also be able to search your **other sources**\n(email, calendar, Notion, files, chat…), you wire up **connectors**.\n\n**Two ways to wire up a source — that's what \"native\" vs \"MCP\" means:**\n\n- **_Native_ connector (claude.ai)** — an integration **provided and hosted by Claude**, that you\n  enable in a few clicks in **your Claude account settings** (*Settings → Connectors*). **Nothing to\n  install or configure** in your brain. The simplest — that's the case for Gmail, Google Calendar,\n  Slack, Google Drive, Notion.\n- **_MCP_ server (community)** — a small program (often an `npm` package) that **you declare\n  yourself** in your brain's `.mcp.json` file, with your credentials. More choice and control, but a\n  bit more configuration. The installer's wizard can add it for you.\n\n\u003e 👉 When a source exists in **both forms** (Notion, Drive…), start with the **native** one: less\n\u003e friction. Move to **MCP** if you want a specific variant or a tool with no native connector.\n\nA few ideas to get started — *up to you to choose according to your tools*:\n\n| You want to query… | You could for example wire up… | Type |\n|---|---|---|\n| Your Notion **notes / wikis** | the Notion MCP server `@notionhq/notion-mcp-server`, or the **native** Notion connector | native **or** MCP |\n| Your **emails** | the **native** **Gmail** connector | native (claude.ai) |\n| Your **calendar** | the **native** **Google Calendar** connector | native (claude.ai) |\n| Your **files / documents** | a Google Drive MCP server (`@modelcontextprotocol/server-gdrive`, `@isaacphi/mcp-gdrive`…), or the **native** Drive connector | native **or** MCP |\n| Your **team chat** | the **native** **Slack** connector | native (claude.ai) |\n| Your **meeting transcripts** (Meet) | the **Calendar** *and* the **Drive** — see below | native + MCP |\n\n\u003e 🎙️ **Meeting transcripts aren't a separate connector.** When you record a video call (Google Meet /\n\u003e Gemini), the transcription link often ends up in the **event invitation** (→ via the **Calendar**)\n\u003e and the transcription document lands on your **Google Drive** (→ via the **Drive**). So you catch\n\u003e them by wiring up **those two connectors**, not a third-party meeting-bot tool.\n\nThe **installer's wizard** (step 5/9) offers to wire all this up by showing you, for each source,\n*what it's for*. The full menu and the credential details are in [**CONNECTORS.md**](CONNECTORS.md)\nand [SETUP §6](SETUP.md).\n\n## What's next?\n\nThe seed gives you the **engine** and a **harness skeleton**; *your* second brain, you grow it by\nusing it — your notes, your rules, your skills. To go further:\n[`.claude/skills/EXAMPLES.md`](.claude/skills/EXAMPLES.md) (skill ideas) and\n[SETUP.md](SETUP.md) (connectors, troubleshooting, RAG details).\n\n## About\n\nBy **Thomas Pierrain** — find the \"second brain\" series and his other writings on\n[medium.com/@tpierrain](https://medium.com/@tpierrain).\n\n## License\n\n[Apache License 2.0](LICENSE) — Copyright 2026 Thomas Pierrain.\n\nYou can use, modify and redistribute it freely, **including commercially**, provided you **keep the\nattribution**: keep the copyright notice, the [`LICENSE`](LICENSE) file and the contents of the\n[`NOTICE`](NOTICE) file in any copy or derivative work, and flag the files you've modified. The\nlicense also includes a grant of patents.\n\n---\n\n\u003cp align=\"center\"\u003e\u003csub\u003eMade with 🧠 by \u003cstrong\u003eThomas Pierrain\u003c/strong\u003e — VP Tech at \u003ca href=\"https://shodo.io/\"\u003eshodo\u003c/a\u003e\u003c/sub\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftpierrain%2Fsecond-brain-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftpierrain%2Fsecond-brain-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftpierrain%2Fsecond-brain-generator/lists"}