# brain-map-skill

> Turn a folder of Markdown notes (Obsidian vault or gbrain export) into a self-contained, interactive HTML knowledge map with a force-directed graph and growth timeline.

brain-map-skill is an open-source Python tool by Vladimir Ignatev that converts a directory of Markdown notes into a single, self-contained interactive HTML file — no server, no embeddings, and no external services required. It ships with a prebuilt demo of 992 fictional notes so you can explore the output immediately without any setup.

## What It Is

brain-map-skill is a knowledge visualization tool that reads plain Markdown files — including Obsidian vaults and gbrain exports — and produces an interactive force-directed graph coloured by theme, a scrubbable growth timeline, and a click-to-inspect detail panel. The output is one standalone HTML file that works in any modern browser, including on mobile. It is designed to work as an agent skill for Claude Code, OpenAI Codex, Cursor, Gemini CLI, and OpenClaw, or it can be run directly as a Python script.

## How It Works

The builder script (`scripts/build_map.py`) reads a notes directory and extracts structure from plain Markdown:

- **Theme** is derived from the top-level folder name; colours are assigned automatically from a palette.
- **Node type** (person, meeting, journal, lecture, project, link, todo, index, note) comes from subfolders or YAML frontmatter tags.
- **Edges** are resolved `[[wikilinks]]`; node size scales with link count and hubs get labels.
- **Timeline** uses `created` timestamps from YAML frontmatter, falling back to file system timestamps for plain vaults.

Dependencies are optional: with stdlib Python only, the browser computes the layout using Cytoscape `cose`; adding `networkx`, `numpy`, and `scipy` via `requirements.txt` pre-computes the layout so 1000-node maps open instantly and look cleaner. The builder auto-detects which path to take.

## Interactive HTML Features

The generated HTML file includes several interactive capabilities:
- Scrub or animate the timeline to watch the knowledge base grow from empty to the present
- Filter nodes live by theme and type with live counts
- Search to highlight matching nodes
- Click any node to dim the rest, highlight its neighbourhood, and open a detail panel showing summary, tags, date, and connected notes
- Responsive layout down to phone screen sizes

## Agent Skill Integration

The repository is structured as an installable agent skill. For Claude Code, the skill is cloned into `~/.claude/skills/brain-map`; for OpenAI Codex, into `~/.agents/skills/brain-map`. For Cursor and other agents, the `SKILL.md` file is self-contained and can be pasted directly into agent instructions. The README notes it is designed to pair with the `save-note-skill`, which writes notes in the exact shape brain-map-skill expects.

## Current Status

The repository was created in June 2026 and last updated on June 17, 2026, with 37 stars and 3 forks at the time of indexing. It is licensed under the MIT License and is actively maintained by Vladimir Ignatev (`vladignatyev` on GitHub). The project is free to use, modify, and distribute.

## Features
- Force-directed graph coloured by theme
- Scrubbable growth timeline with Play animation
- Self-contained single HTML output file
- Reads plain Markdown with YAML frontmatter and wikilinks
- Optional networkx/numpy/scipy for pre-computed layouts
- Click-to-inspect node detail panel
- Live filter by theme and type
- Search with node highlighting
- Responsive down to mobile
- Prebuilt demo with 992 fictional notes
- Agent skill spec (SKILL.md) for Claude Code, Codex, Cursor, Gemini CLI, OpenClaw
- No server, no embeddings, no external services required

## Integrations
Obsidian, gbrain, Claude Code, OpenAI Codex, Cursor, Gemini CLI, OpenClaw, networkx, numpy, scipy, Cytoscape.js

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/vladignatyev/brain-map-skill
- Repository: https://github.com/vladignatyev/brain-map-skill
- EveryDev.ai: https://www.everydev.ai/tools/brain-map-skill