cartographer

The agent that charts the workspace as graphed knowledge.

The cartographer doesn't run tasks. The cartographer charts them.

Every solution becomes a reusable script. Every dead-end becomes a hazard note. Every cross-repo connection becomes an edge on the knowledge graph. The graph is exo-filed (markdown + JSON) so humans and agents can both read it.

The maritime role

The deckhand (sibling: able-bodied-crew) runs tasks — indexes, retrieves, batches, executes.

The cartographer charts — documents solutions, maps hazards, draws coastlines, writes chronicles. Pen-on-paper. Thinks with its pen.

Deckhand runs the task → solves the problem → calls Cartographer
Cartographer charts the solution → writes the script → notes hazards
Next time the same problem appears → Cartographer finds the chart → Deckhand runs the known-good script

What it does

• KnowledgeGraph — nodes (repos, concepts, scripts, hazards) and edges (references, dependencies, solved-by). Stored as JSON + markdown. No database.
• ChartMaker — writes reusable scripts, hazard notes (what NOT to do), and procedure docs. Tests scripts automatically.
• CoastlineBuilder — generates maps at three zoom levels: 1000ft (fleet at a glance), 100ft (each repo in detail), 10ft (file-level for one repo)
• Navigator — given a problem, finds the nearest documented solution or hazard
• Chronicler — writes daily chronicles (the thinking-with-pen record)

Install

pip install si-cartographer

Use

# Build knowledge graph from workspace
cartographer graph /path/to/workspace

# Generate coastline maps
cartographer coastline /path/to/workspace

# Find a solution
cartographer navigate "How do I publish to PyPI?"

# Write to the chronicle
cartographer chronicle --section "PyPI" --message "Published si-cartographer v0.1.0"

License

MIT

Built by SuperInstance. The cartographer charts the rocks so the deckhand doesn't hit them.