Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Project Graph

Every Lexa command operates on a single per-project graph file.

Where the graph lives

The default location is <project>/.lexa/graph.lexa. Lexa resolves the graph path in this order:

  1. --graph <path> (global flag) — applies to the current invocation.
  2. ./.lexa/graph.lexa relative to the canonicalized project root.
  3. ./graph.lexa relative to the current working directory.

If no graph is found and the command allows it, Lexa indexes the project on the fly. Use --no-graph to run a command entirely in memory without loading or persisting a snapshot.

What's in the graph

The graph is a single binary snapshot that combines:

  • File metadata — language, line count, byte size, modification time.
  • Symbols — functions, structs, classes, traits, methods, types, etc.
  • Imports — both resolved project-file edges and unresolved local imports.
  • Text index — trigram and word indexes for fast substring, exact-word, and fuzzy search.
  • Content cache — LRU of recent file contents, with FNV-1a 64-bit content hashes in lower-case hex.
  • Change log — session-local, capped at 100 versions per file.

Change history is session-local

lexa changes [since] and the MCP changes tool return edits made during the current process. Snapshots persisted to .lexa/graph.lexa do not include the change log — it is rebuilt on every restart.

Hash format

Every hash Lexa emits (CLI and MCP) is the lower-case hex of an FNV-1a 64-bit content hash. Use it as an opaque token; the format may evolve.

Recreating the graph

lexa reindex .          # rebuild the in-memory graph from disk
lexa clear-index        # remove the persisted snapshot

If a snapshot file is unreadable (incompatible version, partial write, etc.) Lexa prints a hint to run lexa reindex . or lexa clear-index.