The brain
Every run is fed by a local brain that knows your project. It has five layers, all stored on your machine in one SQLite index — nothing is uploaded to recall.
| Layer | What it holds | How it's used |
|---|---|---|
| Memory index | A lexical (FTS) + vector index of your repo's files | Relevant files are recalled into a run |
| Skills | Recorded macros + learned procedures, usage-scored | Auto-applied on matching tasks; attach one with /skill |
| Code graph | Symbols, references, clusters (graphify) | Recall starts structure-aware, not just text-aware |
| System profile | Your machine — distro, tools, quirks | Injected so agents stop rediscovering your setup |
| User profile | How you like to work (Settings → About you) | Honored in every session |
Recall, without draining tokens
When you send a message, Lectern finds the files most relevant to it by fusing two signals — keyword search and vector similarity — and ranking the results together. The key design choice is what happens next:
- Pointer, not payload. The agent is handed the paths of the relevant files and reads only the ones it actually needs with its own tools. Lectern never bulk-loads your whole memory into the prompt.
- A relevance floor. A match has to clear a similarity threshold to count. A greeting like "hey how's it going" has no genuine match, so it recalls nothing — instead of surfacing whatever scored least-badly.
- Snippets, not whole files. When content itself is needed, only the most relevant window of a file enters context, not the entire file. In practice a task's recalled context drops by roughly 9× versus injecting whole files.
Together these mean recall costs a handful of tokens on a real task and zero on small talk — you get the right context without paying to re-load everything each turn.
Indexing
Opening a workspace indexes its text files (build output, node_modules, .git, and generated graph caches are skipped). Re-indexing is throttled per workspace, so an active session never pays the indexing cost twice. You can turn the brain off entirely for a run with an environment flag if you want a purely stateless agent.
LECTERN_NO_BRAIN=1 lectern run "..." # no recall, no skill matching
The code graph
If you build a graphify graph for a repo, recall becomes structure-aware: alongside text matches it can surface the functions and types related to your task, and the Brain view shows the graph's size and its most connected symbols. The graph's own cache is excluded from recall so it never crowds out real source.
What leaves your machine
- Recall, indexing, skills, and profiles are entirely local.
- The only thing sent to a model is the task plus the short list of recalled paths (and any snippet the agent chooses to read).
- Turn it off per run with LECTERN_NO_BRAIN=1; delete the index by removing the workspace from Lectern.