Skip to main content
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

Episodic memory

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

FrontmatterSet byMeaning
derived-fromKiwiFS (from X-Provenance header)Which run or job produced this file
merged-fromYou (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

ValueRole
episodicRaw run or session material
semanticDurable curated knowledge
consolidationStaging area before merge to semantic
workingScratch, 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

1

Agents write episodes

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

Consolidation job runs

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

Verify coverage

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

​
Check coverage

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

Configuration

[memory] section in config.toml.

Analytics API

Response fields for the memory report endpoint.
Last modified on May 23, 2026