Memory — what the next run knows

Plain files, one CLI

Memory is the agentry mem command over Markdown files. Nothing runs in the background and nothing listens on a port: each call reads the files, answers and exits. The agents run it in Bash, and so can you.

• The project root, .agentry/memory/ in the repo's main checkout, holds what is true for this repository. A call from any of its worktrees reaches the same store.
• The global root, ~/.agentry/memory/, holds what is true across your work. AGENTRY_GLOBAL_DIR moves it.
• The files are the truth. The search index is built with Node's node:sqlite in memory on each call and never written to disk. There is no database file.

The commands

Command	What it does
recall	The few ranked memories for a task (five by default); --mode prime is the session's warm set.
write	Captures a gotcha, decision, preference or repo fact. A near-duplicate reinforces the fact already stored instead of copying it.
search	Full-text search over the active facts, with snippets.
feedback	Records which recalled memories a run used and whether it passed.
episode	Records a run: what was done, how it ended and what to remember.
distill · consolidate	List undistilled episodes with draft facts; propose skills from facts that recur. Nothing is installed.
update · forget · recover	Patch a fact in place, remove one, or bring an archived one back.
stats · resync	Counts across the store and any file that could not be read; rebuild the index from the files.

$ agentry mem recall --query "bundling node:sqlite" --limit 3
$ agentry mem write --type gotcha --scope repo --text "esbuild must mark node:sqlite external"

Every subcommand takes --json, and agentry mem <subcommand> --help prints its flags, exit codes and an example.

How recall ranks

Recall scores each fact by relevance × confidence × (1 + usefulness). Relevance comes from the text index, confidence from how true the fact is held to be, usefulness from how often it helped. A run's feedback moves them: memories a passing run used gain usefulness, ones recalled and never used decay, and a fact that keeps missing is archived until recover brings it back.

Runs become facts

A lane closes by writing its episode to the project store in one call, with the run's lesson and the memories it used. /agentry:reflect distills episodes into facts with their provenance, and /agentry:remember captures one now. The next task that meets the same decision recalls it instead of deriving it again.