CogMap

CogMap is an agent-assisted tool for navigating the tsunami of information that agents and people produce. As agents generate more content, we need new tools for thought that help us understand what a knowledge base contains, how ideas relate, what changed, what matters, what conflicts, what is missing, and where attention should go next.

CogMap treats a knowledge base not as a folder of documents, but as an evolving external memory system with time as a key organizing construct. It extracts concepts, claims, relationships, tensions, gaps, and trends from notes, then renders them as a self-contained, source-traceable visualization you can open in any browser.

The visualization uses Minard-style flows to make that external memory legible: source notes feed into concepts, concepts branch into themes and questions, and related threads converge into synthesis points. Thicker paths represent heavily developed ideas, thinner paths show weakly supported concepts, branches reveal divergence, convergence points show synthesis, and fading paths mark stale or unresolved knowledge.

The goal is to make accumulated knowledge navigable for both people and agents: map the concepts, trace relationships across sources, surface conflicts and gaps, notice drift or convergence, and decide where to focus next.

Why Minard?

Charles Joseph Minard's 1869 map of Napoleon's Russian campaign is one of the classic examples of information design because it compresses many dimensions into one readable story: geography, direction of movement, army size, temperature, and time. Its power is not just that it shows data, but that it shows movement, magnitude, direction, change, context, and consequence together. In Minard's chart, the thickness of the flow represents the number of surviving troops as the campaign advances and retreats.

CogMap borrows that historical visual language for knowledge work. A knowledge base also has movement, magnitude, direction, and consequence: ideas emerge from sources, gather support, split into competing interpretations, reconnect through synthesis, or weaken when they remain unresolved. Minard's format is useful here because it makes change legible without flattening the story into a static list or dashboard.

What it does

• Ingests Markdown, plain text, and optional OneNote .onex note exports.
• Extracts concepts, claims, typed relationships, contradictions, and emergent insights.
• Tracks provenance so nodes and insights link back to the source text.
• Surfaces change, conflict, gaps, and attention-worthy themes across time.
• Opens on a knowledge review inbox that prioritizes tensions, open questions, uncertain extractions, and developing ideas.
• Lets users inspect evidence, mark items reviewed, dismiss noise, and retain those decisions locally across regenerated maps.
• Rebuilds incrementally, re-processing only changed chunks where possible.
• Ships with a GitHub Copilot / Claude Code skill for agent-assisted refreshes.
• Outputs a portable HTML artifact with embedded data and no server requirement.
• Can publish the generated artifact to GitHub Pages for easy sharing.

Knowledge review inbox

Each generated map opens on a knowledge review inbox that turns the visualization into an actionable review queue. It gathers contradictions, open questions, low-confidence concepts, and emerging or rising ideas, then orders them by urgency so the items most likely to need attention appear first.

Select Review evidence to open the item's claims, source excerpts, and provenance in the inspector. Items can be marked Reviewed, dismissed as noise, or reopened later, and the inbox filters make it easy to move between open, reviewed, dismissed, and all items.

Review decisions are stored in the browser using stable item IDs. They remain available when the same map is regenerated and opened at the same location, without changing the source notes or generated data. If browser storage is unavailable, the visualization warns that decisions will last only until the page is reloaded.

See it in action

A synthetic demo corpus ships inside the skill, but it is isolated from real CogMaps. Run the demo explicitly with refresh.py --demo; it renders in:

cogmap-demo/output/knowledge-base-viz.html

The generated page is fully local: no server, database, or API key is required. Real runs use a separate, initially empty cogmap/ workspace, so synthetic concepts cannot leak into a user's map.

How CogMap uses agents

CogMap is built as a deterministic pipeline with agent-powered semantic stages. The Python orchestrator handles file discovery, chunking, caching, aggregation, graph assembly, and HTML rendering. When a semantic step is needed, it emits a structured action file and lets the host coding agent do the LLM work.

Small and medium deltas are packed into as few extraction calls as safely possible. Large corpora adapt toward roughly 8–10 batches and can fan out across at most eight sub-agents at once, so only changed parts of the knowledge base are re-read. Valid partial outputs survive retries; missing or invalid batches are re-run with machine-readable diagnostics before ingestion. Separate higher-reasoning passes then handle concept resolution and synthesis sequentially. CogMap uses agents as temporary cognitive workers while the pipeline remains the durable system of record.

Quick start

CogMap is a coding-agent skill, not a standalone SaaS app. The Python pipeline is the engine the agent drives; the normal user workflow is to install/open the project in your agent and ask it to refresh or rebuild the knowledge base.

Prerequisites

• Python 3.10 or newer.
• One of: GitHub Copilot CLI, Claude Code, or OpenAI Codex CLI.
• No LLM API key. The host coding agent performs the semantic stages.
• Optional: olefile for best-effort OneNote .onex conversion.

1. Clone or open this repository in your coding agent workspace.
2. Install or expose the skill at cogmap-app/skills/build-cogmap.
3. Add your notes to the generated cogmap/sources/ workspace as Markdown or plain text.
4. Ask the agent: "refresh the knowledge base" or "add these notes and rebuild the knowledge map".
5. Open the generated visualization:

cogmap/output/knowledge-base-viz.html

When extraction, resolution, or synthesis work is needed, the skill pauses the pipeline, gives the coding agent structured actions to perform, and then resumes. That agent-in-the-loop loop is what lets CogMap rebuild without requiring a separate LLM API key.

To share the finished map from a GitHub-backed repository, ask the agent to publish it to GitHub Pages. The skill runs refresh.py --publish-github-pages, copies the visualization to index.html on a gh-pages branch, pushes it, and prints the Pages URL.

Installation paths

GitHub Copilot CLI

Copy the self-contained skill folder into your Copilot skills directory:

cp -r cogmap-app/skills/build-cogmap ~/.copilot/skills/

On Windows, copy cogmap-app\skills\build-cogmap to %USERPROFILE%\.copilot\skills\.

Claude Code

This repository is a Claude Code marketplace. In Claude Code:

/plugin marketplace add ryannadel/CogMap
/plugin install cogmap-knowledge-base@cogmap

OpenAI Codex CLI

Codex discovers agent skills under .agents/skills. This repository ships a mirrored copy at .agents/skills/build-cogmap/, kept in sync with the canonical skill under cogmap-app/skills/build-cogmap/.

Repository layout

cogmap-app/
  skills/build-cogmap/   Self-contained skill and bundled pipeline engine
  tools/                 Utility scripts for keeping skill copies in sync

cogmap/                  Project-local workspace created at runtime
  sources/               Input notes
  work/                  LLM extraction/resolution/synthesis artifacts
  output/                Self-contained visualization HTML and JSON data

See cogmap-app/README.md for the full app guide.

Development

Run the public-release checks from the repository root:

python -m compileall -q .
python -m unittest discover -s tests -v
python cogmap-app/tools/sync_skill.py --check

See CONTRIBUTING.md for contribution and skill-sync guidance.

License

CogMap is released under the MIT License. See LICENSE.