Episodic memory

Keep raw agent observations apart from durable knowledge, and track which episodes have been consolidated.

KiwiFS gives agent memory systems a data model on top of plain files. Episodes hold raw, per-session observations. Semantic pages hold curated knowledge. A coverage report shows which episodes have not yet been folded into a semantic page.

KiwiFS does not run an LLM. Consolidation is your agent’s or scheduler’s job; KiwiFS provides the conventions, the tools, and the report.

Episodic memory

Raw notes per run or session. High volume and append-friendly. Lives under episodes/.

Semantic memory

Durable entity and concept pages, built from episodes during consolidation.

Start a workspace with this layout using kiwifs init --template memory. It ships episodes/, pages/, log.md, and a playbook for ingest, recall, and consolidation.

Record and retire memories

MCP

kiwi_remember writes an episode to episodes/<YYYY-MM-DD>/<episode_id>.md with memory_kind: episodic, a created timestamp, and optional scope and tags. It generates an episode_id when you omit one.

kiwi_forget retires a page without deleting it. It sets memory_status: superseded, valid_until to now, and an optional superseded_reason, and keeps the body.

REST

Write episodes like any other file, with X-Provenance to record the run:

Terminal

curl -X PUT 'http://localhost:3333/api/kiwi/file?path=episodes/2026-05-21/run-7f3a.md' \
  -H 'X-Actor: agent:assistant' \
  -H 'X-Provenance: run:run-7f3a' \
  --data-binary $'---\nepisode_id: run-7f3a\nscope: user:alice\n---\nUser prefers email over Slack.'

Frontmatter conventions

memory_kind: what a page is

Value	Role
episodic	Raw run or session material
semantic	Durable, curated knowledge
consolidation	Staging area before a merge into semantic pages
working	Scratch, high churn

Any page under the episodes prefix counts as episodic unless it sets memory_kind: semantic or consolidation.

memory_status: where a page is in its lifecycle

Value	Effect
active	Default. Retrieved normally.
contested	A contradiction was flagged. Still retrieved, counted in the report.
superseded	Replaced. Hidden from search unless you pass include_superseded=true.
stale	Aged out

scope: who a memory belongs to

Partition memories by user, project, or tenant with values such as user:alice or project:billing. Pass scope to kiwi_search, kiwi_search_semantic, or GET /api/kiwi/search to see only that partition.

Time: expires_at, ttl, valid_from, valid_until

expires_at (RFC3339) or ttl (such as 7d or 24h, counted from created) flag a page for review once it passes. kiwifs janitor reports it as expired-memory; nothing is deleted.

valid_from and valid_until record when a fact was true, such as a policy that applied only for a quarter.

contradicts: conflicting pages

Set contradicts to the path or wiki link of a conflicting page, and prefer memory_status: contested over silently overwriting. The link is indexed with relation contradicts and appears in the target’s backlinks. KiwiFS records contradictions you declare; it does not detect them.

Production versus consolidation

Two frontmatter lists answer different questions.

Field	Set by	Answers
derived-from	KiwiFS, from X-Provenance or the MCP provenance argument	Which run produced this file
merged-from	You or your consolidation job	Which episodes were folded into this page

Coverage uses only merged-from. An episode is identified by its episode_id, or id when that is absent.

pages/communication-preferences.md

merged-from:
  - type: episode
    id: run-7f3a
    date: "2026-05-21T12:00:00Z"
    note: "nightly consolidation"
  - type: episode
    path: episodes/2026-05-22/run-8b1c.md

An episode counts as merged when any page lists it as type: episode with a matching id or path. Entries of type run, session, trace, event, or ingest with the same id also count, so consolidators that key on run IDs match too.

Consolidation workflow

1. Agents write episodes

   Use kiwi_remember, or write under episodes/ with X-Provenance and an episode_id.

2. Find what is unmerged

   Run the memory report and take the unmerged list as your queue.

3. Consolidate

   Read those episodes, merge them into pages/ with your model or rules, and list them in merged-from. Retire episodes you no longer need with kiwi_forget.

4. Verify

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

Memory report

CLI

Terminal

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

REST

Terminal

curl 'http://localhost:3333/api/kiwi/memory/report'
curl 'http://localhost:3333/api/kiwi/memory/report?episodes_prefix=raw/&limit=10&offset=0'

MCP

Call kiwi_memory_report with optional episodes_prefix, limit, and offset.

Field	Meaning
coverage_pct	Share of episodes listed in some merged-from
unmerged, total_unmerged	Episodes not yet consolidated
episodic_files, total_episodic	All episodes
contradictions	Pages with contradicts or memory_status: contested
contested_count, expired_count	Pages contested or past expiry
avg_age_days	Mean age of active pages
scope_counts	Pages per scope value

limit and offset page episodic_files and unmerged; the total_* fields stay unpaginated.

To use a folder other than episodes/ for the report and episode classification, set it in config. kiwi_remember always writes under episodes/.

.kiwi/config.toml

[memory]
episodes_path_prefix = "episodes/"

Related

Agent playbook

The files that tell agents how to remember and consolidate.

Analytics API

Full response for the memory report.

Search

Scope filters and superseded pages.

Configuration

The [memory] section.