brain-map-skill is a note visualization tool designed to be agent-friendly, capable of converting a folder containing Markdown notes (such as an Obsidian vault or gbrain export) into a single self-contained interactive HTML knowledge map.
Main Purpose
Integrate scattered Markdown notes into an intuitive force-directed graph, while providing a timeline to observe the growth of the knowledge base over time, and supporting clicking on nodes to view detailed content. The final output is a single HTML file, requiring no hosted knowledge app, no embedded computation, and no server.
Main Capabilities
- Theme coloring: Uses the top-level folder of a note as its Theme, automatically assigning colors from a palette to nodes and edges. If Work/, Study/, Life/ folders exist, their legacy color schemes are preserved, and notes in the root directory are categorized as Other.
- Node shapes: Determines node shapes based on subfolders or tags (Type), covering types such as person, meeting, journal, lecture, project, link, todo, index, note, and more.
- Edges and node sizes: Edges are generated from parsed [[wikilinks]]; node size scales with the number of links, and hub nodes display labels.
- Timeline: Based on the created timestamp of notes, bucketed by month and stacked by theme. If created is missing from the frontmatter, it falls back to the file's own timestamp, so ordinary vaults can also generate a timeline.
- Interactions: Drag or play the timeline (progressively revealing notes from empty to the current state); filter by theme and type (with real-time counts); search to highlight matches; clicking a node fades the rest, highlights its neighborhood, and opens a details panel (summary, tags, date, connected notes); responsive design, adaptable to mobile phones.
Usage
- Zero-configuration experience: A prebuilt demo is included in the repository, containing 992 fictional notes (covering the three themes work, study, life). Simply open the HTML file to experience timeline dragging, playback growth, node clicking, and filtering, with no need to generate notes, embeddings, gbrain, or Python.
- Build from your own notes: The command is
brain-map-skill <notes_dir> --dir <out>, where<notes_dir>is an Obsidian vault or gbrain export directory. The map reads ordinary Markdown files, parsing YAML frontmatter (tags, created) and [[wikilinks]]. The networkx dependency is optional; the builder automatically detects and chooses the better path; it runs whether or not gbrain, embeddings, or a server are installed. - Install as an agent skill: Environments such as Cursor can paste SKILL.md into the agent instructions; the file is self-contained.
- Regenerate the demo corpus: All people, organizations, and events in the demo are fictional and do not involve real data.
Applicable Scenarios
Suitable for users who need to export an Obsidian vault or gbrain notes as a visualized knowledge map, especially for scenarios where it is desired to integrate it as an agent skill into workflows such as Claude Code, OpenAI Codex, Cursor, Gemini CLI, OpenClaw, and others. The richer the cross-links (person cards, meeting participants, index pages, etc.), the higher the map's readability; this tool is designed to pair with the save-note skill, which writes exactly this format.
Limitations
The materials do not mention information such as fees, pricing, platform restrictions, or performance limits, so none is provided for now.
