Memory

Persistent memory tools available to the agent.

hordecode gives the agent a persistent memory system, exposed as built-in tools it can call during a session. The system is built from separate layers: a memory store that holds the entries, keyword and semantic retrieval that search them, and a research pipeline that works next to memory. Each layer is described below, followed by the tool reference and configuration.

How memory is organized

Memory store. Memory entries are markdown files in the memory folder of the hordecode data directory. An index in the main database (hordecode.db by default) holds each entry’s text and its vector. Entries are grouped into the scopes global, projects, sessions and cc (see CC memory), and memory_session saves episodic session summaries.

Keyword retrieval. Keyword search runs on SQLite FTS5 and ranks results with BM25. It is on by default, needs no download, and works on every platform. The built-in memory tool and memory_recall both use it.

Semantic retrieval. Semantic (vector) search is opt-in through the memory.embedding config key, which is off by default. It runs on-device with onnxruntime and @huggingface/transformers. The model is bge-small-en-v1.5, and all-MiniLM-L6-v2 is the fallback if the first one does not load. When vectors exist, memory_recall fuses the keyword and vector rankings with Reciprocal Rank Fusion (k = 60), then applies an entity boost and MMR diversity. On-device embeddings run on Linux (glibc, x64 and arm64), Windows (x64 and arm64) and macOS on Apple silicon. Keyword search works on every platform.

Research pipeline. The research agent gathers new information in nine stages, from scope to a cited report and a decision record, and writes its outputs under findings/<run-id>/, separate from the memory store. The research skill asks the agent to record its decisions with memory_add. See Use research.

Also in the memory system

Checkpoints and context injection. Checkpoint rebuilds and context thresholds place memory into the agent’s context automatically.
Dream jobs. Dream jobs write memory files, not vectors.
Trajectory history search. The history tool searches its own index, history_fts, separate from the memory index.

Tools

Tool	Purpose
`memory_add`	Write a new memory entry to a scope (`global`, `projects`, `sessions` or `cc`), with an optional scope id.
`memory_recall`	Search memory (hybrid: keyword + semantic + entity boost, RRF-ranked, with MMR diversity). Widens the scope when nothing matches.
`memory_update`	Update one entry by id: its body, its type, or both.
`memory_session`	Save a session summary for a thread.
`memory_status`	Report memory health: counts by scope and type, vector count, last reconcile, checkpoint pointer and embedding state.
`memory_dump`	List memory entries page by page (50 per page by default, up to 200).
`memory_gc`	Run the retention sweep and remove exact duplicates.

The built-in memory tool searches the markdown memory files with keyword search (BM25).

Keyword by default, semantic opt-in

Memory recall is keyword search (BM25) out of the box and needs no download. It works on every platform.

Semantic (vector) search is opt-in. Enable it in your config:

{
  "$schema": "https://hordecode.com/config.json",
  "memory": {
    "embedding": true
  }
}

On first use, hordecode downloads the embedding model once (about 133 MB) into <cache>/models. Recall stays keyword-only until the model is ready, then becomes hybrid (lexical + semantic + entity boost, RRF-ranked).

Semantic search runs on-device on Linux (glibc, x64 and arm64), Windows (x64 and arm64) and macOS on Apple silicon. Keyword search works everywhere.

memory_status reports the current mode and vector count. horde debug embedding-check verifies the embedding pipeline in the compiled binary.

The memory.embedding config key switches semantic search on.

Configure

Memory behavior is configured through the memory option:

{
  "$schema": "https://hordecode.com/config.json",
  "memory": {
    "disable_write": false,
    "cc_index": false,
    "embedding": false
  }
}

disable_write — Stop WRITING new memory. Default: false (memory is written). When true, no new memory is produced — session checkpoint.md, project MEMORY.md, notes.md and per-task progress.md are never written, the high-pressure “save your learnings to memory” nudge is suppressed, and dream and distill runs are skipped. Existing memory stays READABLE on demand: the builtin memory search tool keeps working and the files can still be read directly. What does stop is the AUTOMATIC injection — checkpoint rebuild is short-circuited to compaction while writing is off, and the memory dumps that a rebuild would have placed in context are only produced by that rebuild, so nothing is loaded on its own; an agent that wants memory has to search or read for it. Nothing is ever deleted — set it back to false to resume writing on top of the existing files.
cc_index — Index Claude Code memory (~/.claude/projects/<slug>/memory) and expose under scope cc. Default: false. When enabled, every hordecode agent (build/explore/subagents) can search these memories via the builtin memory tool — including CC’s type: user (your role/preferences) and type: feedback (your guidance) categories. CC originally writes them for future CC sessions; flipping this on widens the consumer set to hordecode agents on the same machine. Leave disabled (default) if you don’t want personal context recallable from a prompt-injection-vulnerable agent.
embedding — Enable semantic (vector) memory search. Default: false. When true the embedding model (about 133 MB) is downloaded once into <cache>/models on first use; search stays keyword-only until it is ready.

CC memory

When memory.cc_index is enabled, hordecode indexes Claude Code’s own memory files under the cc scope and makes them searchable through the same memory_recall tool. This includes CC’s type: user and type: feedback categories.

This widens who can read that memory to any hordecode agent running on the same machine, including subagents. Leave cc_index disabled (the default) if you don’t want personal context recallable from a prompt-injection-vulnerable agent.