Code Archaeology

What it produces:

• nodes.jsonl — all discovered symbols and structural elements
• edges.jsonl — relationships between nodes
• files.jsonl — file metadata and content hashes
• indexes/ — lookup indexes (by symbol, path, tag)
• summaries/ — per-module and per-package prose summaries

Incremental behavior: On subsequent runs, only files whose content hash has changed are re-processed. Use --full to force a complete rebuild.

Querying

Run scripts/query_graph.py to retrieve context bundles from the graph.

python scripts/query_graph.py <kg-dir> [options]

Output: A markdown context bundle containing the matched subgraph — nodes, edges, evidence pointers, and summaries — ready for pasting into an agent session.

Graph Structure

The graph uses JSONL files with three entity types. See reference/graph-schema.md for the full schema.

Node Types

Edge Types

Evidence Pointers

Every node and edge carries an evidence array:

{"file": "src/server.py", "start_line": 42, "end_line": 58}

Output Structure

archaeology/kg/
├── nodes.jsonl
├── edges.jsonl
├── files.jsonl
├── indexes/
│   ├── by_symbol.json
│   ├── by_path.json
│   └── by_tag.json
└── summaries/
    ├── <module>.md
    └── overview.md

Agent-Driven Fallback

When Python is unavailable, the agent builds the graph manually using read/search tools:

1. Enumerate files — list the repository tree, note languages and file counts
2. Identify entry points — find main, index, app, server, config files, build files
3. Extract imports and symbols — use search/grep to find import statements, class/function definitions, route registrations
4. Build nodes and edges — follow the same schema (node types, edge types, evidence pointers)
5. Write JSONL files — create nodes.jsonl, edges.jsonl, files.jsonl directly in archaeology/kg/
6. Generate summaries — write per-module markdown summaries in summaries/

The agent should prioritize breadth-first: get the coarse structure right before deep-diving into any single module.

Traversal Strategy

Two-pass approach. See reference/traversal-strategy.md for details.

Pass 1 — Coarse inventory:

• Enumerate all files, detect languages, compute file hashes
• Find entry points (main, index, app, server, CLI definitions)
• Extract top-level imports and module boundaries

Pass 2 — Targeted deepening:

• BFS from seed nodes (entry points, high fan-in, high fan-out)
• Extract symbols: classes, functions, methods, types
• Build call edges, data-flow edges, config references
• Tag anti-patterns as discovered

Anti-Pattern Detection

Detected patterns are stored as tags on nodes:

Incremental Updates

• Every file's content hash is stored in files.jsonl
• On re-run, only files with changed hashes are re-processed; their old nodes/edges are replaced
• --since-git <ref> uses git diff --name-only to scope the update to changed files
• Full re-index is needed when: graph schema changes, indexer version changes, or the graph appears corrupted

Design Principles

• Navigational accuracy over precision — it's more important to find the right area of code than to perfectly parse every symbol
• Evidence-backed claims — every node and edge points to source lines; no hallucinated structure
• Minimal context bundles — queries return the smallest subgraph that answers the question
• Language-agnostic heuristics — rely on universal patterns (imports, definitions, call sites) rather than language-specific ASTs