background design decisions

Design decisions

Lode favors local operation, simple storage, and bounded agent responses. Most design choices are visible in README.md, pyproject.toml, and the core modules under src/lode.

Local-first by default

The default runtime dependency list in pyproject.toml is empty, and the storage path in src/lode/config.py points at a local data directory. This keeps repository source and derived facts on the developer's machine unless an operator chooses to wire optional services.

SQLite as the hot path

src/lode/storage.py uses SQLite tables and FTS5 for lookups that agents need inside a normal turn: search, symbol lookup, graph neighbors, context packs, and impact traversal. This keeps the common path fast and easy to inspect.

Kuzu as a projection

src/lode/kuzu_store.py treats Kuzu as a rebuildable projection from SQLite, not the source of truth. That choice lets contributors experiment with graph queries while keeping one primary fact store.

Embeddings are optional

src/lode/embeddings.py calls a configured local endpoint and docker-compose.yml provides a local TEI service. Exact search and graph traversal still work when no embedding service is running.

CLI and daemon share core functions

src/lode/cli.py and src/lode/daemon.py call the same indexing, storage, graph, and context functions. This reduces behavioral drift between command-line and HTTP use.

Related pages

• Architecture
• Storage and search
• Embeddings and Kuzu