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

# Episodic memory

> Separate raw agent sessions from durable semantic pages using frontmatter conventions and merge reports.

KiwiFS provides a **data model** for agent memory systems: episodic files accumulate raw observations, semantic pages hold durable knowledge, and a **merge report** shows which episodes are not yet referenced by any downstream page.

KiwiFS does not run an LLM. Consolidation is your job; KiwiFS gives you conventions and tooling.

## Two layers

<CardGroup cols={2}>
  <Card title="Episodic memory" icon="clock-rotate-left">
    Per-run or per-session raw notes. High volume, append-friendly, lives under `episodes/`.
  </Card>

  <Card title="Semantic memory" icon="book">
    Durable curated knowledge on entity and concept pages. Built from episodes after consolidation.
  </Card>
</CardGroup>

## Provenance vs consolidation

| Frontmatter    | Set by                              | Meaning                                                  |
| -------------- | ----------------------------------- | -------------------------------------------------------- |
| `derived-from` | KiwiFS (from `X-Provenance` header) | Which run or job **produced** this file                  |
| `merged-from`  | You (or your consolidation job)     | Which episodes were **folded into** this downstream page |

<Info>
  `derived-from` records authorship. `merged-from` records consumption. The memory report uses only `merged-from` to determine coverage.
</Info>

## Classify pages with `memory_kind`

| Value           | Role                                  |
| --------------- | ------------------------------------- |
| `episodic`      | Raw run or session material           |
| `semantic`      | Durable curated knowledge             |
| `consolidation` | Staging area before merge to semantic |
| `working`       | Scratch, high churn                   |

<Note>
  `memory_kind: semantic` or `consolidation` prevents a file from being treated as episodic even when it lives under the episodes path prefix.
</Note>

## Path convention

By default, markdown under **`episodes/`** is treated as episodic when `memory_kind` is absent or set to `episodic`.

```toml .kiwi/config.toml theme={null}
[memory]
episodes_path_prefix = "episodes/"
```

## Episodic identity and `merged-from`

Prefer **`episode_id`** in episodic frontmatter. If absent, KiwiFS falls back to `id`.

```yaml frontmatter example theme={null}
merged-from:
  - type: episode
    id: run-7f3a
    date: "2026-04-27T12:00:00Z"
    note: "merged into concepts/auth from nightly job"
```

An episode is **covered** when any page references it in `merged-from` — by `id` or by compatible `type` (`run`, `session`, `trace`, `event`, `ingest`).

## Operator workflow

<Steps>
  <Step title="Agents write episodes">
    Write under `episodes/` with `X-Provenance` and optional `episode_id` in frontmatter.
  </Step>

  <Step title="Consolidation job runs">
    Read unmerged episodes, consolidate with your LLM or rules, then update `pages/` with `merged-from`.
  </Step>

  <Step title="Verify coverage">
    Re-run the memory report until `unmerged` is empty or acceptable.
  </Step>
</Steps>

## Check coverage

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    kiwifs memory report --root ./knowledge
    kiwifs memory report --root ./knowledge --json
    kiwifs memory report --episodes-prefix raw/
    ```
  </Tab>

  <Tab title="REST">
    ```bash theme={null}
    curl -s 'http://localhost:3333/api/kiwi/memory/report'
    curl -s 'http://localhost:3333/api/kiwi/memory/report?episodes_prefix=raw/&limit=10&offset=0'
    ```
  </Tab>

  <Tab title="MCP">
    Call **`kiwi_memory_report`** with optional `episodes_prefix`, `limit`, and `offset`.
  </Tab>
</Tabs>

## Related documentation

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration#memory">
    `[memory]` section in config.toml.
  </Card>

  <Card title="Analytics API" icon="chart-bar" href="/api/analytics#memory-report">
    Response fields for the memory report endpoint.
  </Card>
</CardGroup>