Episodic memory

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

Per-run or per-session raw notes. High volume, append-friendly, lives under episodes/.

Semantic memory

Durable curated knowledge on entity and concept pages. Built from episodes after consolidation.

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

derived-from records authorship. merged-from records consumption. The memory report uses only merged-from to determine coverage.

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

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

Path convention

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

.kiwi/config.toml

[memory]
episodes_path_prefix = "episodes/"

Episodic identity and `merged-from`

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

frontmatter example

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

Agents write episodes

Write under episodes/ with X-Provenance and optional episode_id in frontmatter.

Consolidation job runs

Read unmerged episodes, consolidate with your LLM or rules, then update pages/ with merged-from.

Verify coverage

Re-run the memory report until unmerged is empty or acceptable.

Check coverage

CLI
REST
MCP

kiwifs memory report --root ./knowledge
kiwifs memory report --root ./knowledge --json
kiwifs memory report --episodes-prefix raw/

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'

Call kiwi_memory_report with optional episodes_prefix, limit, and offset.

Configuration

[memory] section in config.toml.

Analytics API

Response fields for the memory report endpoint.

Getting Started

Core Concepts

Guides

Data Import

Data Export

Deployment

Episodic memory

Two layers

Episodic memory

Semantic memory

Provenance vs consolidation

Classify pages with `memory_kind`

Path convention

Episodic identity and `merged-from`

Operator workflow

Check coverage

Configuration

Analytics API

​Two layers

Episodic memory

Semantic memory

​Provenance vs consolidation

​Classify pages with memory_kind

​Path convention

​Episodic identity and merged-from

​Operator workflow

​Check coverage

​Related documentation

Configuration

Analytics API

Two layers

Provenance vs consolidation

Classify pages with `memory_kind`

Path convention

Episodic identity and `merged-from`

Operator workflow

Check coverage

Related documentation