# WorkGraph

<p align="center">
  <strong>Turn a folder full of projects into a drill-down work map and a queryable local knowledge graph.</strong>
</p>

<p align="center">
  <a href="https://github.com/AlexWangzhixin/WorkGraph/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/AlexWangzhixin/WorkGraph/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://github.com/AlexWangzhixin/WorkGraph/releases"><img alt="Release" src="https://img.shields.io/github/v/release/AlexWangzhixin/WorkGraph?display_name=tag"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-2f6f73"></a>
  <img alt="Python 3.11+" src="https://img.shields.io/badge/Python-3.11%2B-3776ab">
</p>

<p align="center"><a href="README.zh-CN.md">简体中文</a> · <a href="#quick-start">Quick start</a> · <a href="docs/architecture.md">Architecture</a> · <a href="docs/privacy.md">Privacy model</a></p>

![WorkGraph portfolio view](docs/images/overview.png)

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.

![WorkGraph project context and provenance](docs/images/project-context.png)

## Quick start

### Windows installer

Download the latest source archive from [Releases](https://github.com/AlexWangzhixin/WorkGraph/releases), extract it, then run:

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

Optional integrations are explicit:

```powershell
.\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

```powershell
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:

```text
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`](config/workgraph.example.json) and the synthetic [`examples/demo-workspace`](examples/demo-workspace).

## Daily commands

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

```powershell
.\.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:

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

For other clients, register this stdio command:

```text
<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](docs/privacy.md) before indexing confidential material.

## Development

```powershell
.\.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`](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`](CONTRIBUTING.md), [`SECURITY.md`](SECURITY.md), and the [roadmap](docs/roadmap.md).

## License

Apache License 2.0. See [`LICENSE`](LICENSE).