> ## Documentation Index
> Fetch the complete documentation index at: https://drevon.trysudosu.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory System

> Persistent cross-session memory that stays cheap as it grows — an index plus lazily-loaded detail.

## Overview

The memory system gives AI agents **persistent context across sessions** — they remember
what happened, what decisions were made, and what patterns emerged. Without memory, every
session starts from zero. With it, agents compound knowledge over time.

Drevon's memory (v2) is built around one principle the whole industry has converged on:
**bounded eager load, lazy detail.** Instead of reading every memory file at the start of
every session — which grows unbounded and both costs tokens and *degrades* answer quality —
the agent reads a small, budget-capped **index** and pulls in individual detail files only
when they're relevant.

<Note>
  On a real workspace this cut the per-session eager load from **\~59,000 tokens to \~260** —
  a 99.5% reduction — with **no loss in answer quality** (measured live: agents still cite
  the exact right source, just retrieved on demand instead of dumped up front).
</Note>

## The three tiers

```
.drevon/memory/
├── INDEX.md            Tier 0 — the ONLY file read eagerly at session start (budget-capped)
├── topics/             Tier 1 — read on demand
│   ├── architecture.md   (project mode) — context, structure, key files
│   ├── patterns.md       code conventions, gotchas
│   └── decisions/        one file per decision: YYYY-MM-DD-slug.md
├── log/                Tier 2 — episodic; never read eagerly
│   ├── 2026-07.md        current month's append target
│   ├── 2026-06.md        older monthly segments
│   └── summaries.md      compacted headlines of archived months
└── archive/            non-destructive home for compacted/superseded content
```

**Hub mode** uses `topics/user.md`, `topics/projects.md`, `topics/systems.md` in place of
architecture/patterns.

## How it works

<Steps>
  <Step title="Session start — read the index only">
    The agent reads **`INDEX.md`** and nothing else. It carries the project summary, the
    current focus, one-line pointers to every topic file, and the most recent log headlines
    — all within a small token budget (default \~2,000).
  </Step>

  <Step title="During work — load detail on demand">
    When a task needs a specific decision or pattern, the agent opens *that one file*
    (the index points to it), or runs `drevon memory search` to find older history. It never
    reads the whole memory directory up front.
  </Step>

  <Step title="Writing — via the CLI, never by hand">
    Agents record memory with `drevon memory log | decide | learn | note`. These append to
    small files and refresh the index automatically — so a write never requires re-reading a
    large file.
  </Step>

  <Step title="Compaction — keep it small over time">
    `drevon memory compact` rolls old log months into summaries and archives their bodies, so
    memory stays fast no matter how long the project runs. Run it periodically, or use the
    shipped `memory-compact` prompt for an agent-driven consolidation pass.
  </Step>
</Steps>

## Writing to memory

Agents (and you) record memory through the CLI so entries land cheaply and the index stays
in sync:

| Command                                                            | Use when                           |
| ------------------------------------------------------------------ | ---------------------------------- |
| `drevon memory log "<what happened>"`                              | After a significant action         |
| `drevon memory decide "<title>" --why "<rationale>"`               | A technical decision is made       |
| `drevon memory learn "<insight>" --topic <patterns\|architecture>` | A pattern/convention is discovered |
| `drevon memory note "<current focus>"`                             | The active-work focus changes      |

<Warning>
  Never hand-edit the files under `log/`. Append through `drevon memory log` so the segment
  and the index stay consistent. The full history remains searchable with
  `drevon memory search`.
</Warning>

## Keeping memory relevant

* **Retention scoring** ranks content by an Ebbinghaus-style forgetting curve (salience by
  type + recency), so compaction knows what to summarize. **Decisions and architecture are
  never auto-evicted** — only summarized in place.
* **`drevon doctor`** warns when the index exceeds its budget (run `compact`) or when a
  Codex `AGENTS.md` approaches the 32 KiB truncation cap.
* **`drevon memory status`** shows the eager load, per-tier token usage, and the budget.

## Upgrading from v1

Older workspaces used four monolithic, append-only files (`context.md`, `decisions.md`,
`patterns.md`, `log.md`). To port them to v2:

```bash theme={null}
drevon memory migrate      # non-destructive; add --dry-run to preview
```

Migration splits the monoliths into the tiered layout, backs up every original under
`archive/pre-v2-<date>/`, and rewrites your config. It's idempotent and also runs
automatically on `drevon sync` / `drevon upgrade` (pass `--no-migrate` to skip). See the
[migration guide](/docs/cli-reference/memory) for details.

## Disabling memory

```json theme={null}
{ "memory": { "enabled": false } }
```

Or during init: `npx drevon init --no-memory`.

<Note>
  Memory is one of Drevon's most valuable features — and in v2 it's nearly free at session
  start. Keep it on.
</Note>