---
title: "Agent memory"
description: "Durable agent memory about the user and the project: remember writes readable notes, recall assembles context within a budget, search dedups first."
---

# Agent memory

Agent memory in Notarium isn't hidden magic or a separate database: it's ordinary notes of the `agent-memory` class, which the agent writes from its observations and which you can read, correct, and delete. The agent stores facts through `remember_about_user` and `remember_about_project`, and pulls context through `recall`. The key discipline is to **search before you write**, so you don't spawn duplicates.

## Two axes: about the user and about the project

Memory lives on two orthogonal axes:

- **About the user** — `remember_about_user` writes long-lived facts about you (preferences, context, current work) into the private memory of your personal domain. It's the same memory no matter which space you work in — it isn't mixed into every space.
- **About the project** — `remember_about_project` writes memory about a specific project into its subdirectory. Symmetric to writing about the user, but tied to the project.

Both axes use the `agent-memory` class. The agent **doesn't choose** the class, the folder, or the space: the tool itself enforces all of that. Shared knowledge that should live in the project tree as `user-doc` is written by a separate tool, [`create_note`](/docs/agents/intent-tools/), not by "remember."

## A file per category, not a file per observation

`remember_about_user(observation, category)` **appends** the observation to the category's file rather than spawning a micro-file for every fact. `category` is a label ("preferences"), not a path. A new category means a new file. The optional `summary` is a one-line digest of the category that feeds the derived profile index.

Correcting or deleting a single recorded fact is just editing an ordinary note: `edit_note` by the memory note's id (returned by `remember_*`) in `findReplace` mode (an empty `content` removes the snippet) or `replace` mode for the whole category. There's no separate "addressing by observation" — memory is edited with the same word-based modes as any note.

## recall ≠ search

Both tools read, but they solve different problems:

| | `search` | `recall` |
|---|---|---|
| What it returns | ranked snippets with `score` and `path` | a coherent context bundle within a token budget |
| Scope | relevant notes | relevant notes **plus** their graph neighbors (`depth` hops across the graph) |
| Memory | sees memory (for dedup) | pulls from knowledge and from personal memory |
| When to call | find something specific, check before writing | assemble context around a topic to work on |

`recall` is richer: it walks the graph around what it found and packs the result within `budgetTokens`, while `maxPerSource` keeps one large note from eating the whole bundle. `search` is precise: it's the very mechanism behind "search before you write."

## Search before you write

Memory is the only class without title-based duplicate protection, so `search` deliberately **covers the agent's memory too**. Always search before you write: this dedups both knowledge and memory.

> [!tip] The dedup discipline
> Before `remember_*`, call `search` on the fact's topic. If the category already exists, append to it through the same `remember_*` (it appends) or fix it with `edit_note`, instead of creating a synonym.

## What the owner sees

Memory is **hidden from normal navigation** (the tree, the Feed, ordinary search), but it isn't hidden from you: it's visible through a dedicated **Memory** lens in the explorer tree (notes open like any other, at `/m/<id>`), and you can mute a category in **Agents → Context**. The entry in the [revision log](/docs/concepts/versioning/) shows exactly what the agent recorded — this is how you catch anything an injection might have slipped in. You can't reorganize memory: the agent owns the section (a flat set plus a derived index), but moving it around is technically safe — identity rides on the note's id.

## Next

- [Context sets and pins](/docs/agents/context-pins/) — how to mute a memory category and what loads at startup.
- [Retrieval audit](/docs/agents/audit/) — what the agent searched for via `search`/`recall` and whether it found it.
- [Intent tools](/docs/agents/intent-tools/) — the full set of tools.