Graph Cache¶

CodeNib has two cache layers with different contracts:

the codenib index and codenib wiki commands manage repository manifests and view freshness below $CODENIB_HOME/repositories;
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.

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.