Keeping Structural Memory Fresh Without Losing Trust

deusdata/codebase-memory-mcp treats freshness as a lifecycle problem, not as a promise that a watcher makes the graph instantly current. This chapter follows a repository change through manifest comparison, incremental or full indexing, daemon coordination, worker supervision, validation, and publication. The practical judgment is whether the system can update its structural memory without exposing a half-built generation or erasing the last graph that was known to work.

That question matters because the graph is persistent. Once an agent has learned a qualified relationship from it, later calls may assume that the same project and generation still describe the source. A stale graph can mislead; a badly interrupted refresh can be worse, because it can leave no coherent graph at all. Codebase-memory-mcp's design therefore assigns meaning to transitions: what counts as a change, which state may be reused, who owns a live job, and when a new result becomes visible.

Change becomes evidence before it becomes a rebuild

The pipeline begins a refresh by establishing the inputs that matter. It discovers the current file set under the selected mode and records a semantic manifest for those inputs. The manifest includes more than a simple directory snapshot: it represents the source material and configuration that affect the meaning of the index. Before a new generation replaces the old one, the pipeline builds a fresh manifest again. If the semantic inputs changed during the run, the new result is not trusted for publication.

This second check protects a subtle race. A repository can be edited while a large index is being built. Without a final comparison, the system could publish a graph made from one mixture of source and metadata while the file hashes or source tree now describe another. The graph might look complete but have no single consistent input state. Rechecking just before publication makes the transition conditional on a stable enough basis.

When an existing database is available, codebase-memory-mcp first asks whether it is a valid generation to build upon. Integrity and stored format matter. A database that cannot be read safely, or whose format no longer matches the current graph identity rules, is not treated as a reliable incremental base. The pipeline can route that case to a full rebuild rather than trying to reuse unknown state.

An incremental route is also more than “only parse changed files.” Relationships can cross file boundaries. A changed definition may affect consumers that were not themselves edited. Codebase-memory-mcp persists cross-file LSP surfaces, referenced-name information, and governing configuration context so it can decide whether a dependent closure needs repair. If that information is missing or cannot safely bound the consequences, the safer answer is a full rebuild.

This is a useful way to understand incremental indexing. It is not an optimization that automatically wins. It is a claim that the unchanged part of the previous generation remains valid under the current semantic inputs and that the affected closure can be identified. The project spends storage and computation on the metadata needed to make that claim. A cheaper refresh that silently discards relationships would violate the purpose of structural memory.

Mode selection introduces another transition rule. A later request may ask for a cheaper index mode than the one that produced the current graph. If the system simply rebuilt at the cheaper mode, it could erase files and derived relationships that the existing generation intentionally retained.