Transforming a Markdown notes folder, such as an Obsidian vault or a gbrain export, into a standalone, interactive HTML knowledge map is now easier than ever. This transformation results in a dynamic force-led chart colored by theme, an engaging timeline that you can scroll through to watch your knowledge base grow, and a clickable panel for in-depth inspection.
Works with: Claude Code, OpenAI Codex, Cursor, Gemini CLI, OpenClaw, or you can simply run the script.
See it in 5 Seconds (No Setup Required)
A prebuilt demo is included in this repository, requiring no notes to generate, no integrations, no gbrain, and no Python. Simply open the file:
Open demo/brain-map.html # macOS
Demo xdg-open/brain-map.html # Linux
Start demo/brain-map.html # Windows
The demo features 992 fiction notes spread over three themes: work · study · life. Browse the timeline, tap ▶ Play growth, click on the nodes, and activate the filters.
Build From Your Own Notes
Run the following script to build your map:
python3/build_map.py scripts <notes_dir> out.html –title “My second brain“
<notes_dir> represents your Obsidian vault or a gbrain export. This tool uses Simple Markdown with YAML frontmatter tags, created dates, and [[wikilinks]].
Dependencies Are Optional
| Facility | Result |
|---|---|
| Nothing (Python stdlib only) | Built anywhere; the browser calculates the layout (Cytoscape cose). |
| pip install -r requirements.txt (networkx, numpy, scipy) | Pre-calculated layout → 1000 node maps open instantly and look cleaner. |
The builder automatically detects networkx and chooses the best path, requiring no gbrain, no integration, and no server.
- Theme: Top-level folder (Work/, Studies/, Life/) determines the color of node and edge.
- Type: Subfolder/tags determine node shape (person, meeting, journal, etc.).
- Edges: Resolved [[wikilinks]]. Node size varies with link count; hubs get labels.
- Chronology: Timestamps created, grouped by month, stacked by theme.
The richer your cross-links (e.g., person files, meeting participants, index pages), the more readable your map becomes. It’s designed to associate with note-saving skills that write in this format.
- Scrub / Play: The timeline reveals grades up to that month. The animation shows the evolution from the void to the present.
- Filtered: By theme and type (live accounts). Research highlights matches.
- Click: Select a node to sift through the rest, illuminate its area, and open a detail panel (summary, tags, date, connected notes).
- Responsive to mobile devices.
Install as an Agent Skill
Claude Code
git clone https://github.com/vladignatyev/brain-map-skill ~/.claude/skills/brain-map
OpenAI Codex
git clone https://github.com/vladignatyev/brain-map-skill ~/.agents/skills/brain-map
Cursor / Others: Paste SKILL.md into your agent’s instructions for autonomous operation.
Regenerate the Demonstration Corpus
Run the following commands to generate demonstration notes:
python3 scripts/generate_demo_notes.py /tmp/demo-vault # 992 invented notes
python3 scripts/build_map.py /tmp/demo-vault demo.html
All people, organizations, and events in the demonstration are fictitious and do not represent real data.
The brain-map-skill directory includes:
- SKILL.md: Agent skill specification
- scripts/: Includes build_map.py (constructor) and generate_demo_notes.py (mock demo vault)
- demo/: Contains brain-map.html (prebuilt), vault/ (992 source Markdown notes), and preview.png
- requirements.txt: Optional dependencies (networkx, numpy, scipy)
- LICENSE
To learn more and access the resources, visit the repository.
“`
