> ## 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 Files Reference

> The v2 memory store layout — index, topics, log segments, and archive.

## Overview

Drevon v2 memory is a small set of markdown files organized into three tiers by how eagerly
they load. The agent reads only the index at session start and pulls detail in on demand.

```
.drevon/memory/
├── INDEX.md            Tier 0 — eager, budget-capped
├── topics/             Tier 1 — read on demand
│   ├── architecture.md   project mode
│   ├── patterns.md
│   └── decisions/        one file per decision
├── log/                Tier 2 — episodic, never eager
│   ├── <YYYY-MM>.md
│   └── summaries.md
└── archive/            compacted / migrated originals (non-destructive)
```

## Tier 0 — `INDEX.md`

The **only file read at session start**. It is generated and maintained by Drevon (via the
`drevon memory` commands) — you don't hand-write it. It stays within a token budget
(`memory.eagerBudgetTokens`, default \~2,000).

```markdown theme={null}
# Memory Index

## Project
<one-line project summary>

## Active Work
<current focus — set via `drevon memory note`>

## Topics
- [Architecture](topics/architecture.md) — project context, structure, key files
- [Patterns](topics/patterns.md) — code conventions, gotchas
- [Decisions](topics/decisions/) — 29 decisions (latest: …)

## Recent Log
- 2026-07-18 — <headline>
- …  (last 5)
```

## Tier 1 — `topics/`

Small, on-demand files. The index points to each one.

| File (project mode)                 | Contains                              | Written by                                 |
| ----------------------------------- | ------------------------------------- | ------------------------------------------ |
| `topics/architecture.md`            | Project context, structure, key files | `drevon memory learn --topic architecture` |
| `topics/patterns.md`                | Code conventions, gotchas             | `drevon memory learn --topic patterns`     |
| `topics/decisions/<date>-<slug>.md` | One decision per file                 | `drevon memory decide`                     |

In **hub mode**, the topics are `user.md`, `projects.md`, and `systems.md` instead of
architecture/patterns.

A decision file looks like:

```markdown theme={null}
# Use Postgres

- **Date:** 2026-07-18
- **Why:** ACID guarantees and mature tooling
```

## Tier 2 — `log/`

The episodic activity journal, split into **monthly segments** so it never loads as one
monolith. Never read eagerly; searchable via `drevon memory search`.

```markdown theme={null}
# Log — 2026-07

### 2026-07-18 — Shipped the v2 memory system
```

`log/summaries.md` holds the headlines of months that compaction has archived:

```markdown theme={null}
# Log Summaries

## 2026-03 _(cold)_
- 2026-03-05 — …
```

## `archive/`

Non-destructive storage: pre-migration originals (`archive/pre-v2-<date>/`) and the bodies of
log months that `drevon memory compact` has rolled up. Nothing here is ever loaded eagerly;
nothing is ever deleted by Drevon.

## Configuration

```json theme={null}
{
  "memory": {
    "enabled": true,
    "directory": ".drevon/memory",
    "layout": "v2",
    "indexFile": ".drevon/memory/INDEX.md",
    "eagerBudgetTokens": 2000,
    "retentionMonths": 3,
    "files": {
      "index": ".drevon/memory/INDEX.md",
      "architecture": ".drevon/memory/topics/architecture.md",
      "patterns": ".drevon/memory/topics/patterns.md"
    }
  }
}
```

* **`eagerBudgetTokens`** — soft cap on the index; it trims its recent-log tail to stay under.
* **`retentionMonths`** — log months older than this are eligible for `compact` (default 3).

## The memory protocol

Every compiled agent config (`CLAUDE.md`, `AGENTS.md`, `copilot-instructions.md`) carries the
v2 protocol, which tells the agent to:

1. **Read `INDEX.md` only** at session start.
2. **Load a topic file only when relevant** — the index says which.
3. **Write via `drevon memory log | decide | learn | note`** — never hand-edit the log.
4. **Recall older history with `drevon memory search`.**

## Migrating from v1

Legacy stores (`context.md`, `decisions.md`, `patterns.md`, `log.md`) port over with:

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

See the [`drevon memory` reference](/docs/cli-reference/memory).