Graph Cache

CodeNib has two cache layers with different contracts:

1. the codenib index and codenib wiki commands manage repository manifests and view freshness below $CODENIB_HOME/repositories;
2. the low-level LSIndexer API can reuse individual graph-pipeline stages in an explicitly selected output directory.

Most users should use the CLI layer. It compares the repository state with the stored manifest and updates only the views that need work:

codenib index /path/to/repository --preset graph

# Ignore reusable index state and rebuild the selected views
codenib index /path/to/repository --preset graph --rebuild

Low-Level Pipeline Stages

A SCIP-backed LSIndexer normally produces:

index.scip       raw SCIP protobuf
index.decoded    decoded protobuf text
graph.pkl        serialized CodeGraph
lsp_index.pkl    occurrence index for LSP-shaped queries

Other backends can use different raw files, but expose the same graph-stage interface.

Choose the cache directory and language explicitly:

from codenib.ls_router import LSIndexer

indexer = LSIndexer(
    project_root="/path/to/repository",
    output_dir="/path/to/cache",
    language="python",
)
graph = indexer.run_pipeline(skip_level="graph")

skip_level means “reuse this stage when its artifact exists”:

Value	Reused artifact	Remaining work
None	none	generate, decode, and construct
"raw"	raw language index	decode and construct
"decode"	decoded index	construct
"graph"	serialized graph	load and return

If the requested artifact is absent, the pipeline falls back to the preceding work needed to recreate it. A graph that cannot be loaded also falls back to the pipeline.

The low-level API does not provide the CLI manifest's full repository freshness contract. Callers that set skip_level are responsible for using a cache produced from compatible source, toolchain, and CodeNib versions.

Remove Derived Stages

clear_cache() treats its argument as the highest stage to preserve:

indexer.clear_cache("graph")   # keep raw + decoded + graph
indexer.clear_cache("decode")  # keep raw + decoded; remove graph artifacts
indexer.clear_cache("raw")     # keep raw; remove decoded + graph artifacts
indexer.clear_cache("all")     # remove every pipeline artifact

The "graph" operation intentionally removes nothing. Use "all" to force a complete low-level rebuild.

Save Or Load A Graph Directly

CodeGraph persistence is a binary CodeNib format:

from codenib.graph.code_graph import CodeGraph

graph.save_graph("/path/to/graph.pkl")
loaded = CodeGraph.load_graph("/path/to/graph.pkl")

Use the conventional .pkl suffix so the storage format is clear. Persisted graphs contain range indexes and graph metadata; schema changes are guarded by CodeNib's graph schema version.

Graph Schema 5 Migration

Schema 5 adds three independently queryable facts while retaining the coarse node and edge types used by existing traversals:

• symbol vertices carry optional symbol_kind values such as interface, enum, and type_alias;
• every symbol vertex carries has_definition; only true means its file and range describe an observed definition;
• TypeScript and TSX graphs can carry anchored file-to-file import edges in addition to their ordinary observed reference edges.

Schema 4 graph.pkl files do not contain those facts and are intentionally not upgraded in place. CodeGraph.load_graph() rejects them with the existing schema-version diagnostic. Rebuild each CLI-managed repository once:

codenib index /path/to/repository --preset graph --rebuild

Low-level callers may reuse a compatible index.decoded and reconstruct only the graph stage with skip_level="decode"; they must not relabel an old pickle as schema 5. Packaged, demo, and evaluation artifacts must be regenerated by their owning pipeline before publication.

Relocate State

The CLI state root defaults to ~/.codenib; set CODENIB_HOME to move it. Temporary low-level indexer output defaults below $CODENIB_TEMP_DIR (normally $TMPDIR/codenib). An explicit output_dir always takes precedence for the LSIndexer instance.