brain-map-skill

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.