# Memory

> Let future runs reuse durable project knowledge without treating the complete transcript as a
> permanent prompt.

Clarvis memory is a workspace-local Markdown wiki. It keeps useful, non-obvious knowledge such as
verified commands, architectural decisions, recurring failure symptoms, and the reasons behind a
workaround. It uses ordinary Markdown files — no vectors or embeddings — so the project owner can
read and edit what was retained.

## Distinguish memory from sessions and context

- A **session transcript** is the durable record of what people and agents said and did.
- **Model context** is the bounded working set sent to one model call and may be compacted.
- **Memory** is curated knowledge extracted for reuse across runs in the same workspace.

Memory does not copy every conversation. Most completed runs should produce no memory change. When
knowledge is worth keeping, the wiki stores detail in `MEMORY.md` leaves, compiles it into topic
summaries, and keeps a workspace-wide `PROFILE.md` as the root index.

```text
<workspace>/.clarvis/memory/
├── PROFILE.md
└── build/
    ├── TOPIC.md
    └── bun/
        └── MEMORY.md
```

## Turn memory on

Open `/settings/memory`, choose global or workspace scope, create the memory block, and select the
model used to extract durable knowledge. Save the change for future runs. The session row lets you
temporarily turn configured memory on or off without rewriting settings.

Memory needs an effective extraction model. It uses the memory-specific model when configured and
otherwise the effective default model. If neither resolves, Clarvis keeps memory configured but
warns that it cannot learn.

## Follow how one run learns

At run start, Clarvis adds the bounded `PROFILE.md` summary to the agent's context. Agents with
memory access can search and read deeper documents. The lead can update memory through the guarded
memory tools; sub-agents receive read access but cannot independently grant themselves write
authority.

After a run ends, Clarvis durably queues a background indexing pass. That pass reviews the task,
result, and bounded tool evidence, then either makes a coherent wiki update or leaves memory
unchanged. The next user task does not have to wait for indexing to finish.

## Tell Clarvis what deserves a note

Add plain Markdown guidance in either or both locations:

| File                                    | Scope                       | Share it?            |
| --------------------------------------- | --------------------------- | -------------------- |
| `~/.clarvis/memory-policy.md`           | your preference everywhere  | no                   |
| `<workspace>/.clarvis/memory-policy.md` | this project's expectations | optionally commit it |

The two policies combine, global first. Write editorial guidance about **what** is useful, not a
replacement wiki structure:

```md
Record the exact command that fixed a build and explain why it worked.
Do not retain customer data, temporary credentials, or personal shell aliases.
```

Policy edits apply to the next indexing pass without a restart.

## Keep memory inspectable and safe

The default file backend lives inside the workspace's Clarvis data and remains directly readable as
Markdown. Secrets are redacted from bounded run snapshots before indexing, but a memory policy is
still important: do not instruct an agent to retain sensitive data that should not be part of the
project's long-lived knowledge.

Clarvis can also use a configured MCP or plugin memory provider. The effective provider owns its
storage and capabilities; a read-only provider is never sent an indexing write. Changing providers
does not replay queued writes into a different backend.

## See also

- [How Clarvis works](/explanation/how-clarvis-works)
- [Configuration](/reference/configuration#prompt-and-memory-control)
- [Daily use](/guide/daily-use)
- [Safety and control](/guide/safety)

---

[Canonical HTML](https://clarvis.dev/guide/memory)

[Documentation index](https://clarvis.dev/llms.txt)