WorkGraph

WorkGraph indexes a user-selected workspace without moving or uploading its files. It builds a layered Portfolio -> Area -> Project -> Artifact graph, exposes it through a local browser, CLI, and read-only MCP server, and can optionally generate an Obsidian navigation layer.

It started as a personal vibe-coded tool for navigating a large, mixed research and engineering workspace. The public version removes machine-specific assumptions while keeping the workflow that made the original useful: fast cross-project discovery, explicit provenance, and strict separation between source files, rebuildable indexes, and curated memory.

What it does

• Drill-down map: move from the whole portfolio to an area, project, document, concept, tool, or workflow.

• Local search: SQLite FTS search over project metadata and selected text files.

• Explainable links: distinguish explicit path references from lower-confidence, shared-concept suggestions.

• Read-only MCP: let Codex, Kimi, Reasonix, or another MCP client query project context and reusable prior work.

• Optional Obsidian layer: generate navigation pages, concept indexes, memory mirrors, and a Canvas without copying the workspace.

• Privacy controls: mark entire top-level areas as metadata-only and redact common credential patterns from indexed text.

• No hosted service: the web UI binds to loopback and uses vendored frontend assets; runtime indexing needs no network or model API.

Related MCP server: ContextForge

Quick start

Windows installer

Download the latest source archive from Releases, extract it, then run:

.\scripts\Install-WorkGraph.ps1 -WorkRoot "D:\MyWorkspace" -Start

Optional integrations are explicit:

.\scripts\Install-WorkGraph.ps1 `
  -WorkRoot "D:\MyWorkspace" `
  -ObsidianVault "$HOME\Documents\My Vault" `
  -SensitiveArea Personal,Finance `
  -ConfigureClients `
  -Start

The installer creates a project-local .venv, writes config/workgraph.json, builds the first index, and optionally registers the MCP server. Existing client files are backed up before modification.

Manual installation

uv venv .venv
uv pip install --python .\.venv\Scripts\python.exe -e .
.\.venv\Scripts\python.exe -m workgraph.cli init --work-root "D:\MyWorkspace"
.\.venv\Scripts\python.exe -m workgraph.cli refresh
.\.venv\Scripts\python.exe -m workgraph.cli serve

Open http://127.0.0.1:8765/. On macOS or Linux, use .venv/bin/python with the same module commands.

Workspace model

The default convention treats the first directory level as an area and the second as a project:

MyWorkspace/
├── Research/
│   ├── ClimateModel/
│   └── KnowledgeGraph/
├── Engineering/
│   ├── RobotArm/
│   └── CFDStudy/
└── Writing/
    └── OpenSourceGuide/

Deeper or mixed layouts can be described with project_layout.area_depths and project_layout.group_depths. See config/workgraph.example.json and the synthetic examples/demo-workspace.

Daily commands

.\scripts\Refresh-WorkGraph.ps1
.\scripts\Start-WorkGraph.ps1 -Open
.\scripts\Status-WorkGraph.ps1
.\scripts\Stop-WorkGraph.ps1

.\.venv\Scripts\python.exe -m workgraph.cli search "finite element OCR"
.\.venv\Scripts\python.exe -m workgraph.cli context "ClimateModel"
.\.venv\Scripts\python.exe -m workgraph.cli related "KnowledgeGraph"
.\.venv\Scripts\python.exe -m workgraph.cli reuse "document rendering"

MCP tools

work_map, project_context, related_projects, find_reuse, work_search, and graph_stats are read-only. Automatic registration currently targets Codex, Kimi Code/Kimi Work, and Reasonix on Windows:

.\.venv\Scripts\python.exe -m workgraph.cli configure-clients

For other clients, register this stdio command:

<absolute path to python> -m workgraph.mcp --config <absolute path to workgraph.json>

Trust boundaries

• The workspace remains the source of truth; WorkGraph never moves or deletes source files.

• The SQLite database and generated Obsidian pages are disposable indexes.

• Sensitive areas expose filenames and aggregate metadata, but their contents are not indexed.

• Generated folders such as .git, .venv, node_modules, and build caches are excluded from semantic analysis.

• Binary office files, PDFs, models, and media are metadata-only in v0.1.

• related_to edges are discovery hints, not evidence. Follow source paths before relying on a claim.

Read the full privacy model before indexing confidential material.

Development

.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe -m compileall -q src tests

WorkGraph is runtime-stdlib-only. Cytoscape.js and Lucide are vendored for the offline UI; their notices are in THIRD_PARTY_NOTICES.md.

Development is human-directed and AI-assisted. The maintainer owns architectural decisions, privacy boundaries, verification, releases, and all accepted changes; generated code receives the same review and test requirements as any other contribution.

Contributions are welcome through focused issues and pull requests. See CONTRIBUTING.md, SECURITY.md, and the roadmap.

License

Apache License 2.0. See LICENSE.