Memory

Theus keeps two kinds of memory on your machine — plain-text memory files you edit by hand, and a local knowledge graph plus index it builds from your code — both stored under your home directory and never required to live on a remote service.

Two layers of memory

Theus separates what you tell it from what it learns from the code:

• Memory files — prose you write and curate. Persistent instructions, conventions and notes that Theus reads back on future sessions. You open and edit these with the /memory command.
• Knowledge graph + index — a structured graph Theus derives automatically from your repository: files, symbols, domain entities and the relationships between them, plus a local embedding index for retrieval.

Both live locally under the Theus config directory. Nothing here depends on a hosted service.

The /memory command

Run /memory inside an interactive session to edit a memory file. Theus shows a selector of the available memory files; when you pick one it:

1. Creates the config directory and the file if they do not exist yet (existing content is preserved).
2. Opens the file in your editor of choice.

The editor is chosen from your environment: Theus uses $VISUAL if set, otherwise $EDITOR, otherwise a sensible default. To pick your editor, export one of them before starting Theus:

export EDITOR="nvim"
# or
export VISUAL="code --wait"

Where memory lives

Theus stores its persistent knowledge under the config home, which is ~/.theus by default. The knowledge graph is namespaced per project so two repositories never collide: the project root is hashed and that hash becomes the directory name.

~/.theus/knowledge/<project-hash>/graph.json
~/.theus/knowledge/<project-hash>/embeddings.json

• graph.json — the serialized knowledge graph: every node and every typed edge.
• embeddings.json — the local embedding index, one vector per node, used for similarity search.

The <project-hash> is a short, stable hash of the absolute project root, so re-opening the same repository always resolves to the same memory, and moving between projects keeps their memories fully separate.

Relocating the config directory

If you move the Theus config dir with the THEUS_CONFIG_DIR environment variable, memory follows it — the knowledge base is always resolved relative to the same config home the rest of Theus uses.

export THEUS_CONFIG_DIR="/data/theus-config"
# knowledge now lives under /data/theus-config/knowledge/<project-hash>/

What the knowledge graph contains

When Theus indexes a project it walks the source tree (skipping node_modules, .git, build output and generated bundles) and extracts a lightweight structural graph. Every node is one of four kinds, connected by directed, typed edges.

Node ids are deterministic (<type>:<key>), so re-indexing the same repository upserts nodes instead of duplicating them. A memory about a given symbol is wired with derived-from edges to that symbol, so when you later ask about the symbol, the memory surfaces with it.

How retrieval works

Recall over the knowledge base is hybrid and runs entirely offline:

1. Keyword scoring — how many of your query's tokens appear in a node's text, with a small boost for an exact label match.
2. Vector similarity — cosine similarity against a local embedding index. The embeddings are deterministic, dependency-free hashed vectors computed on your machine — a cheap local stand-in, not a call to any external embedding service.
3. Graph traversal — the top-scoring seed nodes are expanded outward along their edges (imports, contains, references, defines, derived-from) to pull in structurally-related context.

The result is a ranked set of nodes plus the connected subgraph around them, which Theus can inject as compact context so relevant memory and code reach the model together.

Related

• CLI reference — the full command and flag list.
• Documentation home — the local index, dashboard and provider setup.