How does serena keep cached index files up to date?

[nickolay-kondratyev]

Indexing my Kotlin repo takes a couple minutes. So I run the following to index the repository.

    uvx --from git+https://github.com/oraios/serena serena project index --timeout 300

The typical usage involves the client (Claude Code, Claude Desktop, etc.) running the MCP server as a subprocess (using stdio communication.

The question that comes up, how does serena make sure that the indexes are up to date and NOT stale.

Does it update the index cache files (like $PROJECT/.serena/cache/kotlin/document_symbols_cache_v23-06-25.pkl) while it is being utilized by claude code? And if there are changes to the file while claude code is not running in this case then do we have to run entire re-index again or is there some faster command?

    uvx --from git+https://github.com/oraios/serena serena project index --timeout 300

[MischaPanch]

The cache is always updated when file content changes. The only thing that's not taken care of is pruning the cache, so the file may grow large over time. But information from the cache is never stale

[nickolay-kondratyev]

So 1) if there are any new files added between runs serrena will scan file system and detect them and 2) if there is cached content for a file and it is outdated serena will detect based on some hashing/timestamping? Correct?

[MischaPanch]

Yes, and yes - where 2) only uses hashing