Search & recall

Search runs on a local index inside the graph folder. There is nothing to configure either way: the best available backend is picked automatically.

Two embedders

Lexical (default)Semantic (opt-in)
InstallNothing extrapip install "kgl-memory[semantic]"
How it matchesBag-of-words similarity (hashing vectoriser)Learned semantic similarity (all-MiniLM-L6-v2, 384 dimensions)
NetworkNeverDownloads the model once on first use, then cached; after that fully offline
Weak spotMisses memories worded very differently from the queryA ~90 MB model to load at start-up

Installing the extra is the only step needed to upgrade; it is auto-selected. Use --no-semantic on any command to force the lexical backend for a fast, fully offline start.

After switching embedders, re-embed once. Old vectors have a different dimension than new ones; search skips mismatched rows rather than crashing, but they won't match until rebuilt:
from kgl_memory.store import MemoryStore
from kgl_memory import ops

ops.reindex(MemoryStore("memory/graph"))

What get_context returns

  1. Short-term. The most recent messages of the session (a cheap read of the tail of one file).
  2. Long-term. Hybrid search hits over the graph, with facts and preferences ranked first.
  3. Graph expansion. One bounded hop of linked nodes from each hit, so related entities and reasoning come along.

Everything is packed into a token budget (default 2000 tokens) so recall never floods the agent's context. Reasoning traces linked to the hits are included by default.

Prefer get_context over search_memories unless you specifically want raw hits with no expansion or session context.

Editing files by hand

Writes through the tools keep the indexes current. If you edit .kgl files outside the tools, rebuild the indexes so search and aliases catch up. See Maintenance.