Memory System

Persistent, cross-session memory for the agent. Notes are stored as Markdown files and surfaced back into the model’s context via a search step before the agent acts.

Source: crates/core/src/memory.rs. Tools are registered in crates/core/src/tools/builtin.rs.

Backends

Memory is pluggable behind the MemoryBackend trait. Two backends exist:

ZkBackend — zettelkasten built on the zk CLI. Keyword-based full-text search. Always available, including lite builds. This is the default for lite.
QmdBackend — hybrid BM25 + vector search via the qmd CLI, using zk for note authoring. Available only in ranch (non-lite) builds, where it is the default (memory_backend = "qmd").

The backend is selected by the memory_backend config key ("qmd" or "zk"). qmd_min_score (default 0.4) sets the relevance cutoff for the qmd backend. If a lite build is asked for qmd, it falls back to zk.

Because the harness runs as a WASM plugin and cannot spawn processes directly, each backend method returns a shell command string. The harness executes it, receives the result, and parses stdout into notes.

Tools

The agent interacts with memory through two built-in tools:

__MEMORY_SAVE__ — write a note.
__MEMORY_SEARCH__ — search notes.

Notes

A parsed note (MemoryNote) has:

Field	Meaning
`id`	identifier, usually the filename without extension
`title`	title from the note’s frontmatter
`path`	full path to the note file
`tags`	tags associated with the note
`body`	note body (may be truncated)
`score`	relevance score 0.0–1.0; only set by `QmdBackend`

Directory layout

Notes live under <cowboy_dir>/memory/, a zettelkasten managed by zk:

<cowboy_dir>/memory/
  .zk/        # zk configuration and index
  daily/      # YYYY-MM-DD.md journals
  facts/      # atomic knowledge notes
  decisions/  # decision records
  templates/  # zk note templates

<cowboy_dir> is $HOME on a ranch install and $XDG_DATA_HOME/cowboy (default ~/.local/share/cowboy) in lite mode.

Pre-tool retrieval

Memory search is wired in as a retrieval step before the agent runs tools, gated by the pre_tool_retrieval config flag (default on). When enabled, the harness searches memory based on the conversation and injects matching notes into context so the model can use prior knowledge without an explicit search. Retrieval does not fire inside sub-agents.

The MemoryBackend trait also exposes init_commands(), recent(limit), search_deep(query), remember(title, content, template), journal(entry), and an optional search_skills_deep(query) for searching skill files alongside memory.