[Introduction](https://verity.md/docs) [Quickstart](https://verity.md/docs/quickstart) [Authentication](https://verity.md/docs/authentication) [How it works](https://verity.md/docs/how-it-works) [Moments](https://verity.md/docs/moments) [Formal verification](https://verity.md/docs/formal) [Findings & verdicts](https://verity.md/docs/findings) [The Standard](https://verity.md/docs/standard) [Org Standards](https://verity.md/docs/org-standards) [Standards on the web](https://verity.md/docs/web-standards) [The terminal editor](https://verity.md/docs/terminal-editor) [Memory](https://verity.md/docs/memory) [Org knowledge](https://verity.md/docs/org-knowledge) [Token telemetry & cost](https://verity.md/docs/cost) [The dashboard](https://verity.md/docs/dashboard) [CLI & commands](https://verity.md/docs/cli) [Files & configuration](https://verity.md/docs/files) [Security & privacy](https://verity.md/docs/security) [Troubleshooting](https://verity.md/docs/troubleshooting)

Concepts

# Memory

A Markdown knowledge base that records what your agents and their reviewer learn, and feeds it forward, so every task starts with what the last one found out. From CLI 0.36.0 you can edit, delete, query and consolidate it from the terminal.

Verity's memory lives at `.verity/memory/` as plain Markdown that you can read and edit, and that Obsidian can open. It is a small knowledge graph. Each note is a node with YAML frontmatter (id, kind, the files it applies to, confidence, status) and a Markdown body. Typed edges link related nodes. An auto-generated `index.md` lists the nodes, and your `CLAUDE.md` tells agents to scan that list before non-trivial work.

For a signed-in project, the Verity service holds the graph. The files on your machine are a copy: the session-start hook downloads it, and `verity memory pull` does the same by hand. If you are not signed in, the graph is only on this machine. Git ignores `.verity/memory/` in a new project, so generated notes stay out of your diffs and pull requests. To commit the graph on purpose, run `verity memory track`. `verity memory untrack` reverses that.

## Three horizons

Project memory is the durable layer, but it is not the only thing Verity remembers. Different facts have different lifespans, and mixing them is how a memory starts confidently recalling things that stopped being true:

| Horizon | Holds | Lives |
| --- | --- | --- |
| **Working memory** | What we are doing right now — the current goal, findings still open, what has already been reviewed. | On your machine, outside the repo, for the session. Deleted when it closes. |
| **Line of work** | What this task is about — survives a closed session, a new worktree, a different machine. | Service-side, as a task. |
| **Project memory** | What is true about this codebase — the notes below. | On the Verity service, with a copy in `.verity/memory/` on each machine. |

[How it works](https://verity.md/docs/how-it-works) covers how working memory is kept honest. The rest of this page is the durable layer.

## Organized by domain

| Domain | What lives here |
| --- | --- |
| `decisions` | Deliberate choices between alternatives, ADR-style. |
| `patterns` | Positive conventions established across the codebase. |
| `gotchas` | Footguns and surprising behaviour to avoid. |
| `security` | Trust boundaries and constraints learned from findings. |
| `quality` | Quality expectations clarified over time — including accepted risks. |
| `intent` | Recurring request types and what “done” means for them. |
| `domain` | Business rules and domain concepts. |
| `integrations` | External systems, API contracts, and their quirks. |

Nodes that are superseded move to `_archive/`; they are kept for history and ignored by retrieval.

## How it compounds

1. **Seed.** `verity init` creates the empty knowledge base; `verity memory seed` (or the optional `/verity-setup`) derives the first notes from your codebase, README and any `CLAUDE.md` (`--dry-run` to preview). A seed node that you deleted, or that a dream removed, stays removed: a fresh clone does not create it again.
2. **Inject, twice.** When you submit a prompt, the relevant notes are pulled into your agent's context before it starts — ranked by the files and words involved, within a token budget. When the reviewer runs, it walks the graph from the files that changed and reads the notes that apply, so it already knows your decisions and gotchas.
3. **Reflect.** As a task closes (and every few runs along the way), an extractor distils durable lessons from the run history into new notes — capped at a few per cycle so the graph stays signal-rich. Findings you marked as false positives become project-wide suppressions the same way.
4. **Close.** When a session ends, Verity writes a digest of what it observed across the whole session — the shape no per-task extraction can see. A session with nothing worth saying writes nothing.

Your prompts stay yours

The knowledge base is shared with everyone on the project, so what Verity writes there is its own output and derived facts — paths, counts, decisions, outcomes. The prose you typed is not the project's knowledge, and it is not written into a shared store.

## Reflection: the agent records, you correct

The highest-signal notes come from the task that just finished. At a natural task-completion moment — a PR created, a “ship it” — the agent drafts one to three concrete, cited observations (a decision, a gotcha, a pattern) and records them. There is no confirm step. The CLI prints each node id with the commands that correct it. To change or remove a wrong node, use the commands in “Curate it from the CLI”, below.

```
verity reflect --kind security --user-input "Every table in supabase/migrations/ needs an RLS policy."
verity reflect --kind gotcha --user-input - < lesson.md     # - reads the text from stdin
```

- **Kinds:** `decision`, `gotcha` (the default), `pattern`, `security`, `quality`, `intent`, `domain`, `integration`.
- **Title:** the first sentence of the first line, cut at a word boundary if it is longer than 120 characters. `--title` sets it (up to 200 characters).
- **Scope:** the files that the text names — paths, globs such as `config/*.yaml`, folders, and paths in backticks, read from the repository root. Each one must match a file in the repository. `--file-globs` sets them. A reflection that matches no file never surfaces in a review, and the CLI says so.
- **Who stands behind it:** a node is stored as `source: agent`. Add `--confirmed` only when a person wrote or dictated the exact words. The node is then `source: user`, at full confidence, and Verity never archives or rewrites it.
- A bare `verity reflect`, with no text, runs the extractor on the current task.

The `/verity-reflect` skill and the instructions that Verity installs in `CLAUDE.md` run this flow. `--autonomous` is ignored: a reflection is always recorded without a confirm step.

## Curate it from the CLI

Five commands change or query the graph from the terminal. An agent can run them as well as a person, so a wrong node does not have to wait for the dashboard.

| Command | What it does | Network |
| --- | --- | --- |
| `verity memory edit <node-id>` | Change a node's title, files, status or body, or upload a hand edit. | The Verity service |
| `verity memory delete <node-id>` | Archive a node and remove its file here. | The Verity service |
| `verity memory restore <node-id>` | Undo a delete. | The Verity service |
| `verity memory ask <question>` | Find the nodes that answer a question, and quote them. Also `recall`. | None |
| `verity memory dream` | Plan a clean-up of duplicates and placeholders. `--apply` makes it. | None for the plan. The Verity service for `--apply` and `--revert`. |

A command that changes a node needs a sign-in. It changes the service first, and it changes the file here only after the service confirms. It then reads the node back, and it reports success only when the service holds what it sent. The change reaches your team at once: it does not wait for the next review. Node ids are in `index.md`, and `verity memory ask` prints them.

### Change a node: `verity memory edit`

```
verity memory edit n042-check-the-gateway --title "Check the Gateway over HTTP, not TCP"
verity memory edit n042-check-the-gateway --file-globs scripts/health.sh "src/gateway/**"
verity memory edit n042-check-the-gateway --status superseded
verity memory edit n042-check-the-gateway --body - < new-body.md
verity memory edit n042-check-the-gateway      # no option: upload the file as it is on disk
```

| Option | Effect |
| --- | --- |
| `--title <text>` | The new title, up to 200 characters. The `#` heading in the file follows it. |
| `--file-globs <glob...>` | Replace the files the node is about. Each glob must match a file in the repository. |
| `--status <status>` | `active`, `archived` or `superseded`. A node that is not active no longer surfaces in reviews. |
| `--body <text>` | Replace the body. `-` reads it from stdin. The service keeps 8,192 characters, so a longer body is refused. |
| `--force` | Upload even when the service has a newer, different copy of the node. That copy is overwritten. |

- **Verity checks the change before it writes anything.** A glob that matches no file, a body over 8,192 characters or a title over 200 characters is refused, and nothing changes, here or on the service.
- **A teammate's newer change is not overwritten.** If someone changed the node on the service after your copy, `edit` refuses and changes nothing. `verity memory pull` gets their version. `--force` overwrites it.
- **Authorship stays with the node.** The source, author, confidence and evidence come from the copy on the service, so an edit does not turn an agent's node into a person's.
- **With no option**, `edit` uploads the file as it is on disk. Use it after you edit a node file by hand, or to send a node whose earlier edit never reached the service.

### Remove a node: `verity memory delete` and `restore`

```
verity memory delete n042-check-the-gateway --reason "The health check moved to the load balancer"
verity memory restore n042-check-the-gateway
```

- `delete` archives the node on the service and removes its file here. It no longer surfaces in reviews, for anyone on the project. The next analysis and the next `memory pull` do not bring it back.
- `--reason` is optional: 1 to 500 characters, and `-` reads it from stdin. **The reason stays on this machine**, in `.verity/.memory-trash/` and `.verity/memory/log.md`. The service does not store it, so your teammates do not see it.
- `restore` makes the node active on the service again and puts its file back from `.verity/.memory-trash/`. If this machine has no trash record (the node was deleted on another machine or on the dashboard), `restore` activates it on the service and pulls the file.

### Ask a question: `verity memory ask`

`ask` (also `recall`) finds the nodes that answer a question and quotes the sentences that match, each with its node id. It runs on your machine, on the files in `.verity/memory/` and the org knowledge mirrored here. **No model runs, and nothing leaves the machine.** It works offline and costs nothing.

verity memory ask

```
$ verity memory ask "why does the health check use HTTP and not TCP?"
Answer, quoted from the nodes (read the nodes before you rely on it):
  - A TCP connect succeeds while every route returns 503. scripts/health.sh calls /health over HTTP instead. [n001-check-the-gateway-at-the-api-level]

1 node(s), best first:

1. n001-check-the-gateway-at-the-api-level · gotcha · score 6.15
   Check the Gateway at the API level, not just TCP
   .verity/memory/gotchas/n001-check-the-gateway-at-the-api-level.md · scope: scripts/health.sh
   "A TCP connect succeeds while every route returns 503. scripts/health.sh calls /health over HTTP instead."
```

| Option | Effect |
| --- | --- |
| `--limit <n>` | At most this many nodes, 1 to 50. The default is 5. |
| `--json` | The quoted answer, and each node with its id, path, score and body. |
| `--full` | Each node's whole body, not only the matching sentences. |
| `--all` | Include archived and superseded nodes that are still on disk. |

A question of `-` is read from stdin, so its words do not pass through shell quoting. The ranking is BM25 over each node's title, body and file globs: a shared word counts for more when few nodes use it. A file path in the question also favours the nodes scoped to that file. The answer is copied from the nodes, never paraphrased, so the agent that asked writes its own summary. **Limit:** `ask` matches words, not meaning. If a question uses other words than the node, try again with the words the code uses.

### Consolidate the graph: `verity memory dream`

`dream` finds near-identical nodes, nodes the graph marks as superseded, and empty placeholders. With no option it prints a plan and changes nothing:

verity memory dream

```
$ verity memory dream
# Dream plan (nothing changed yet)

Scanned 4 active node(s).

## Merge near-duplicates (1)

- n003-keep-the-gate-non-blocking-and-advisory → into n002-keep-the-gate-advisory-and-non-blocking (overlap 1), scope +scripts/health.sh — Keep the gate non-blocking and advisory

## Prune placeholders (1)

- n004-express — express

Apply it: verity memory dream --apply
```

| Change | When | Result |
| --- | --- | --- |
| Merge | Two active nodes of the same kind have a word overlap of 0.6 or more, on a scale of 0 to 1. | The weaker node is superseded. The node that stays takes its file globs, so no file loses its knowledge. |
| Retire | A node's `superseded_by` names an active node. | Superseded. |
| Settle | Two nodes are marked as contradicting, and a person confirmed exactly one of them. | The other one is superseded. |
| Prune | A node with nothing of its own to say: a seeded “This project uses X” placeholder, or an empty node. | Archived. |

Everything that needs judgement goes to a review list in the plan, and `dream` does not change it: a pair with an overlap from 0.4 to 0.6, a pair where one node negates the other, a contradiction that no person settled, and any change that would touch a node a person confirmed. **A node with `source: user` is never changed.**

```
verity memory dream --apply                               # make the changes and save a report
verity memory dream --list                                # the dreams applied on this machine
verity memory dream --revert dream-20261112-105518-412    # undo one
```

- `--apply` saves a record in `.verity/dreams/` (a `.json` file and a `.md` report) before the first change, and again after each change. It then changes the service one node at a time. A node that stays takes the scope before its duplicates are retired.
- `--revert <dream-id>` puts every node back as it was. It also works after a run that stopped half-way. If someone changed a kept node on the service after the dream, `--revert` does not overwrite it: it names the node, and you fix it with `verity memory edit`.
- `--json` prints the plan, or the outcome, as JSON.
- **Limit:** word overlap does not see paraphrases. Two nodes that say the same thing in different words are not merged. Read them in the review list, or find them with `verity memory ask`.

## It is just Markdown

You can read a node file and edit it by hand. The next analysis uploads the hand edit, and `verity memory edit <node-id>` with no option uploads it at once. In Claude Code, `/verity-memory` lists, shows, walks, adds, edits, archives, searches and lints nodes; `/verity-learn` is the shorter tour. Open `.verity/memory/index.md` directly, or point Obsidian at the directory. The **Knowledge base** page in the [dashboard](https://verity.md/docs/dashboard) shows the same graph — domains, growth over the last 30 days, the graph itself, recent nodes and recent reflections — and which notes each review cited.

Some of what one repository learns holds for every repository in its org. That shared layer is [org knowledge](https://verity.md/docs/org-knowledge).

Machine-local by default

Git ignores `.verity/memory/` in a new project, and the service sends the graph to every checkout. A project that already committed its graph keeps it in git. `verity memory untrack` stops that (the files stay on disk), and `verity memory track` records that you commit it on purpose. `verity doctor` shows which way your project is set up.

[Previous The terminal editor](https://verity.md/docs/terminal-editor) [Next Org knowledge](https://verity.md/docs/org-knowledge)

Source: https://verity.md/docs/memory
