Memory

What your agents have learned. Memory holds durable insights a later session can recall: patterns, gotchas, decisions, task summaries, and importantly, things that were tried and failed.

Part of the brain.

Where memories come from#

You rarely write these by hand:

• After a coding run. The final step of code-task records what it learned about the project.
• After any worker session. When a Claude Code, Codex, Copilot or Cursor worker ends, its transcript is summarized into project-scoped learnings and failed-approach notes, out of process, so even a quick one-off leaves a trace.
• During a session. An agent can record something the moment it learns it.
• By hand, from board or the CLI.
• In bulk, from a file. toryo memory remember-batch <file> files one memory per JSONL line and reports stored, near-duplicate, invalid and failed entries. --receipt F makes retries skip lines already filed. An absent file produces an empty report. With --fail-open, even a pass that could not run exits successfully: check the report's ran before trusting its counts.

Disputes, or negative knowledge#

A dispute records "we tried X, it failed because Y". It is the most valuable kind of memory and is treated differently from the rest:

• It never decays.
• It outranks every positive memory type in recall.
• It is tagged with the files it concerns, so an agent about to edit a file can find out what already failed there.

This is what stops an agent from confidently re-attempting the approach that broke last month.

Correcting a memory#

Write the replacement with --supersedes <id>; the agent tool accepts the same supersedes link. Once the correction is live and approved, recall stops returning the original. Board, list and get still show it, and get names its replacement. Forgetting the correction brings the original back.

A global correction awaiting review retires nothing until approved. A correction can pass the near-duplicate gate despite resembling what it replaces. A hand-typed supersedes: tag that disagrees with --supersedes is refused: the tag cannot fake a retirement.

Recall#

A query is embedded and matched semantically, then re-ranked on more than similarity: how important the memory is, how recent, how often it has been useful, whether it shares code identifiers with what you asked, and whether it has been useful before. That last signal is real feedback, since a memory that helped a run that merged gets rated up, so recall improves with use.

After every worker session, a local model judges which recalled memories helped, in batches of eight. A long session can receive partial ratings (partially_rated) rather than none. A code-task run also gets credit for the memories shown to its implement step before it started, through record-recall.

Recall says when it degraded. If the local model host is unavailable, recall falls back to keyword matching. The agent result names the retrieval that ran, so an empty answer is distinguishable from a degraded one. Scripts can request the same information with toryo memory recall --envelope.

A write during an outage is stored without a vector and says so. It remains keyword-only until toryo memory reembed runs.

The gate on global writes#

A memory scoped to one project is stored immediately. A global memory, one claiming to be true everywhere, is judged first by a local model. A confident accept stores it; a confident reject discards it; anything less lands in a review queue you work in board.

The gate fails closed. If the judge cannot run, the write still succeeds but lands pending, never silently approved.

For a global write a human has already approved, --pre-approved on remember or remember-batch stores it approved without the judge. Anything able to run the command can use this bypass; the stored memory does not show that the judge was skipped.

Near-duplicates are rejected too: a write very close to something already stored in the same scope is skipped rather than stored twice.

The judge needs a chat model pulled locally. The embedding model is not enough. A host serving only it will embed fine and fail every judgement, and because the gate fails closed you will see a growing review queue rather than an error. toryo doctor checks for this specifically. Once the model is present, rejudge drains the backlog.

Decay#

Memories fade on a schedule set by their type: a passing note fades in weeks, a real learning persists for months. Past its window a memory loses importance, and eventually is soft-deleted.

Anything you want kept permanently can be pinned, which exempts it from decay entirely. Disputes are pinned automatically.

Decay runs nightly on the scheduler's system lane.

In board#

The Memory screen browses and filters everything stored, works the global review queue, and lets you pin, rate, edit, or forget individual memories.

The Judge pill counts sessions rated by the recall judge in the last 24 hours. Judge stale means none were rated in that window: recall has stopped learning, usually because the chat model is missing.

From a terminal:

toryo memory list --order-by importance --min-importance 0.7
toryo memory count --min-importance 0.7
toryo memory stats  # totals and the recall judge's last 24 hours

The importance floor applies before the page limit, so important older memories are not lost behind newer ones.

Full command surface: CLI & contract reference.