A second brain with Obsidian: organizing your notes into a living knowledge base

9 min readApril 30, 2026#obsidian#pkm#notes#brain#zettelkasten#para#knowledge-management#bash

Building a second brain with Obsidian — from note chaos to a living knowledge base

The problem isn't a lack of information. It's not being able to find what you already learned.

You read a technical article about embeddings, jot down a note somewhere. Six months later, you reimplement the same thing from scratch because you can't remember where you put it.

A second brain is the fix: an external system where information is organized to be found and reused, not just stored.

This tutorial walks through how I built Brain/ — an Obsidian vault on Debian that covers my projects, my technical resources, my atomic notes, and connects to my CLI and my AI assistant.

Prerequisites: Obsidian installed, basic Markdown knowledge, Linux or macOS. Main tool: Obsidian — a local, Markdown-file-based note editor.

What we're building

~/Brain/
├── projets/          Active project notes (one folder per project)
├── ressources/       Snippets, prompts, tools, business
├── notes/            Atomic notes + daily journal
├── _systeme/
│   ├── sessions/     AI session notes (auto-generated)
│   ├── moc/          Maps of Content — topic indexes
│   └── templates/    Reusable templates
└── archives/         Archived content

One vault. A stable structure. Connections rather than deep hierarchies.

1. Why Obsidian

Obsidian has two properties rare among note-taking tools:

The files are yours. Everything is local Markdown. No proprietary database, no server dependency, no lock-in. You can open any note in a text editor, parse it in Python, commit it to Git, or index it into a RAG.

Links are first-class citizens. [[note-name]] creates a bidirectional link. The linked note knows it's being referenced. The graph view visualizes these connections. That's the difference between a filesystem and a knowledge network.

Documentation: help.obsidian.md — the full official docs, especially the section on wikilinks.

2. The adapted PARA structure

PARA (Projects, Areas, Resources, Archives) is an organizing system based on usability rather than topic. I kept the spirit and adapted it:

FolderOriginal PARAMy version
projets/ProjectsNotes for active projects only
ressources/ResourcesReusable snippets, prompts, tools
notes/Areas + NotesAtomic notes + daily journal
_systeme/—Vault infrastructure (templates, MOC, sessions)
archives/ArchivesEverything no longer active

Key rule: A project keeps a folder in projets/ as long as it's active. Once it's finished or on long-term pause, it migrates to archives/projets/. This deliberate friction keeps projets/ small and relevant.

Reference: Building a Second Brain (book) by Tiago Forte — the full theory behind PARA and CODE (Capture, Organize, Distill, Express).

3. Atomic notes

An atomic note = a single idea, fully developed.

Not "everything I know about embeddings" — rather "why multilingual embeddings share a common vector representation."

This principle comes from Niklas Luhmann's Zettelkasten — a paper-slip system where every idea is self-contained and linked to others through explicit references.

---
title: "Multilingual embeddings — shared representation"
type: note-atomique
tags: [ia, embeddings, nlp]
created: "2026-04-15"
---
 
A model like `paraphrase-multilingual-MiniLM-L12-v2` projects sentences
from 50+ languages into the same vector space.
 
"Chat en français" and "Cat in English" produce close vectors
because the model has learned their semantic equivalence.
 
Consequence: a RAG indexed in French becomes queryable in English
with no intermediate translation step.
 
→ [[tutoriel-brain-assistant-rag]] — how I use this in my assistant

Why this beats a catch-all note: When you link two atomic notes together, you create an explicit connection between two ideas. That connection becomes a third, implicit piece of knowledge. That's what the graph view makes visible.

4. File naming convention

Every note follows a naming convention:

YYYYMMDD-HHmm-slug.md

Examples:

20260415-1430-embeddings-multilingues.md
20260428-0900-retour-pixelmart-stripe.md
20260430-1100-clarity-facebook-os.md

Why this format:

  • Natural chronological sorting in any file explorer
  • Guaranteed uniqueness (date + time)
  • Human-readable slug
  • RAG-compatible — the timestamp becomes indexing metadata

The minimal YAML frontmatter:

---
title: "Readable note title"
type: note-atomique     # or projet, ressource, journal, session
tags: [tag1, tag2]
created: "2026-04-30"   # Always quoted to avoid YAML errors
---

Watch out: Unquoted YAML dates (created: 2026-04-30) can get parsed as date objects by some Python parsers, causing unhashable type errors. Always use created: "2026-04-30".

5. Templates

Obsidian supports templates via the community Templater plugin or the native Templates plugin. I use Markdown files in _systeme/templates/ that I copy manually via hub brain new.

Template for a project note:

---
title: "{{title}}"
type: projet
status: actif
tags: []
created: "{{date:YYYY-MM-DD}}"
updated: "{{date:YYYY-MM-DD}}"
---
 
## Context
 
_Why this project exists._
 
## Goals
 
- [ ] 
 
## Journal
 
### {{date:YYYY-MM-DD}}
 
_First log entry._
 
## Decisions
 
## Related resources

Template for an AI session note (auto-generated by the Claude Code hook):

---
title: "AI Session — {{date:YYYY-MM-DD HH:mm}}"
type: session
tags: [ia, session]
created: "{{date:YYYY-MM-DD}}"
---
 
## Summary
 
## Files changed
 
## Key decisions
 
## Notes

Templater documentation: silentvoid13.github.io/Templater — the most powerful plugin for template automation in Obsidian.

6. Maps of Content (MOC)

An MOC is an index note: it lists and contextualizes the notes on a given topic without duplicating their content.

---
title: "MOC — Artificial Intelligence"
type: moc
tags: [ia, moc]
---
 
## Fundamentals
 
- [[embeddings-multilingues]] — shared vector representation
- [[rag-architecture]] — retrieval-augmented generation, principles
- [[llm-routing]] — choosing the right model for the task
 
## Implementations
 
- [[tutoriel-brain-assistant-rag]] — my personal RAG assistant
- [[brain-indexer-chromadb]] — indexing the vault
 
## Reading
 
- [[note-attention-is-all-you-need]] — the founding transformers paper

MOCs don't replace folders — they cut across them. A note can appear in several MOCs without being duplicated.

7. Connecting to the hub CLI

The vault is navigable from the terminal via hub brain:

# In hub — simplified excerpt
BRAIN_DIR="$HOME/Brain"
 
cmd_brain() {
  local sub="${1:-}"
  case "$sub" in
    search) _brain_search "${2:-}" ;;
    new)    _brain_new "${@:2}" ;;
    today)  _brain_today ;;
    stats)  _brain_stats ;;
    "")     _fzf_pick_brain ;;
  esac
}
 
_brain_search() {
  local query="${1:-}"
  [ -z "$query" ] && { _err "Usage: hub brain search <term>"; return 1; }
  grep -r --include="*.md" -l "$query" "$BRAIN_DIR" \
    | sed "s|$BRAIN_DIR/||" \
    | fzf --preview="bat --style=plain {}" \
         --bind="enter:execute(nvim '$BRAIN_DIR/{}')"
}
 
_brain_today() {
  local today; today=$(date +%Y%m%d-%H%M)
  local path="$BRAIN_DIR/notes/${today}-journal.md"
  [ ! -f "$path" ] && cp "$BRAIN_DIR/_systeme/templates/tpl-journal.md" "$path"
  ${EDITOR:-nvim} "$path"
}

hub brain search "embeddings" → recursive grep → results filtered through fzf → opened in Neovim.

See also: hub go and folder navigation — the same zsh wrapper pattern.

8. Integration with Claude Code (Stop hook)

Claude Code's Stop hook automatically generates a session note in _systeme/sessions/ at the end of every significant session.

Script ~/Scripts/brain-session.sh:

#!/usr/bin/env bash
set -euo pipefail
 
BRAIN_DIR="$HOME/Brain"
SESSIONS_DIR="$BRAIN_DIR/_systeme/sessions"
TEMPLATE="$BRAIN_DIR/_systeme/templates/tpl-session.md"
 
timestamp=$(date +%Y%m%d-%H%M)
slug="session-claude-${timestamp}"
output="$SESSIONS_DIR/${timestamp}-${slug}.md"
 
mkdir -p "$SESSIONS_DIR"
cp "$TEMPLATE" "$output"
 
date_today=$(date +%Y-%m-%d)
sed -i "s/{{date:YYYY-MM-DD}}/$date_today/g" "$output"
sed -i "s/{{date:YYYY-MM-DD HH:mm}}/$(date '+%Y-%m-%d %H:%M')/g" "$output"
 
echo "Brain session created: $output"

Configuration in .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/Scripts/brain-session.sh"
          }
        ]
      }
    ]
  }
}

Every Claude Code session ends with a structured note, ready to be manually enriched with the session's decisions and learnings.

9. The 7 non-negotiables

These rules keep the vault usable over the long run:

  1. One note = one idea. If you find yourself adding an H2 "Other topic" section, create a second note and link them instead.

  2. Always a complete YAML frontmatter. title, type, tags, created — no exceptions. A parser can't work with what it can't find.

  3. Quote your dates. created: "2026-04-30" — never created: 2026-04-30. Avoids YAML parsing errors in Python/Ruby.

  4. Internal links over deep folders. Before creating a subfolder, ask yourself if a [[link]] and an MOC would do the job.

  5. Archive instead of delete. A finished project moves to archives/, not the trash. Past context has value.

  6. Never reindex by hand. If something needs to be findable, it needs a tag or a link. Otherwise, it doesn't exist for the brain.

  7. One session = one note. Every Claude Code session, every project, every important decision leaves a written trace.

10. Tips and common pitfalls

Don't start with the structure. Start by taking notes. The structure emerges from the patterns in your notes, not the other way around.

fzf + ripgrep for searching the vault.

rg --type md -l "term" ~/Brain/ | fzf --preview="bat --color=always {}"

ripgrep is 10x faster than grep on large vaults.

Git for vault history.

cd ~/Brain && git init
echo ".obsidian/workspace*" >> .gitignore
git add . && git commit -m "init: Brain vault"

Git + Obsidian = a snapshot of your brain at any point in time.

The graph view isn't for navigating. It's for diagnosing — isolated notes (with no incoming links) are usually orphans that need linking or archiving.

Use bat instead of cat for previewing.

# In ~/.zshrc
alias cat='bat --style=plain'

bat adds Markdown syntax highlighting to the terminal.

Final structure

~/Brain/
├── projets/
│   ├── bloko/
│   ├── pixelmart/
│   └── portfolio/
│       └── drafts/        ← Articles in progress
├── ressources/
│   ├── snippets/
│   ├── prompts/
│   └── outils/
├── notes/
│   ├── 20260430-1100-*.md
│   └── journal/
├── _systeme/
│   ├── sessions/          ← Auto-generated by the Claude Code hook
│   ├── moc/
│   └── templates/
└── archives/

Resources

→ The CLI that drives this Brain from the terminal → The AI assistant built on top of this vault