@miadi/episodic-memory-schema

Types + JSON Schema for episodic memory — the durable session-to-session memory layer in the Miadi orchestration kit.

In the Miadi stack, this is the shared record format. An episode is the unit everything is filed under, and this package defines its shapes: the authored EpisodicMemory a session leaves behind, and the read-only observations, manifests and catalogs other packages build from existing episode folders. It has no dependencies and touches no filesystem: callers read the files and hand it what they read.

Most of the stack depends on it: @miadi/inquiry-weave, passages, @miadi/capture, @miadi/episode-capture, @miadi/transcription, @miadi/plan-insight and @miadi/musical-composition-to-episode.

When a Storyweaver session closes, the Export Steward extracts an episodic-memory object and feeds it back to Miadi world memory. The next commission inherits what this one built.

Why "episodic"

Tulving (1972) distinguishes three long-term memory systems:

| Type | What it stores | Storyweaver analogue | | ----------- | ------------------------------- | ----------------------------------- | | Episodic | Memory of experienced events | This schema — one session = one episode | | Semantic | Decontextualized facts | The Story Bible | | Procedural | How to do things | Skills + agent working rules |

The package is named for the cognitive system it serves, not the artifact alone.

Schema layers

EpisodicMemory
├── episode       — sessionId, openedAt/closedAt, charter, lineage
├── narrative     — NCP-aligned subtext + storytelling
├── world         — settings, rules introduced, characters advanced, themes
├── provenance    — sources, consent decisions, authority flags
├── continuity    — open promises, canonical facts, contradictions, chapter versions
├── evaluations   — HAWK 10-predicate rubric per beat/chapter/outline
└── followUpCommissions — seeds for the next episode

Narrative layer is NCP-aligned

The narrative layer mirrors the Narrative Context Protocol (NCP) two-layer model:

• Subtext — authorial intent: perspectives, players, storypoints, storybeats, dynamics
• Storytelling — surface presentation: overviews, moments

An NCP-consuming agent can read the narrative layer directly. Episodic-memory adds the four other layers (episode metadata, world delta, provenance, continuity) that NCP doesn't cover.

Provenance layer is PROV-DM and OAIS-informed

• W3C PROV-DM for source-decision-authority triples
• OAIS (Wilkinson et al. 2016, FAIR) for archival packaging: the session workspace is a SIP, the export packet is an AIP, the delivered story is a DIP

Install

npm i @miadi/episodic-memory-schema

Usage

import type { EpisodicMemory } from "@miadi/episodic-memory-schema"

const ep: EpisodicMemory = {
  schemaVersion: "episodic-memory.v1.0",
  episode: {
    sessionId: "sw-2026-05-19-001",
    openedAt: "2026-05-19T13:00:00Z",
    charter: { purpose: "story.bible.from.brief", protocols: ["wilson-3rs", "OCAP"] }
  },
  provenance: { sources: [], consentDecisions: [], authorityFlags: [] },
  continuity: { promises: [], facts: [], contradictions: [] }
}

The JSON Schema is at @miadi/episodic-memory-schema/schema (draft-07). Validate with ajv, zod-from-json-schema, or any draft-07-compliant validator.

A complete example episode (the Inwe-village foundation session from the Storyweaver scenario) lives at examples/inwe-village.example.json.

Layer-by-layer

episode — required

Session identity, charter (purpose + protocols), and lineage. The parentEpisodeId and childCommissionIds form a directed graph of episodes.

narrative — optional (NCP)

Use when the session produced narrative material. Skip for utility sessions (e.g. tool maintenance).

world — optional

The world state delta this episode contributed — not the full world. Settings flagged real | invented | hybrid and locked | malleable. Themes accumulate across episodes.

provenance — required

• sources — every cited material with authority: open | restricted | sacred | community-controlled
• consentDecisions — protocol-gate decisions with timestamp + human-confirmation flag
• authorityFlags — open authority concerns raised by the Research Weaver

continuity — required

• promises — Chekhov's-gun-style commitments, with status: open | fulfilled | broken
• facts — canonical facts established this episode
• contradictions — detected contradictions and whether they were resolved

evaluations — optional (HAWK)

Narrative quality evaluations from the Critique Reviewer and Developmental Editor. Each evaluation targets a beat, chapter, outline, draft, or bible, and scores it against the HAWK 10-predicate rubric (Cheng et al. 2025):

• Goal (p1–p5): coherence · progression · originality · tension · resonance
• Plan (p6–p10): feasibility · consistency · interactivity · suspense · cohesion

Each value lies in [-1, 1] (the Decision Agent's logit-derived truth signal).

continuity.chapterVersions — optional (HAWK)

HAWK-style versioned audit trail per chapter — { chapterId, version, at, environmentDelta, characterMemoryDelta }. Enables parallel review of the story's development over time.

followUpCommissions — optional

Work the manuscript implies but did not complete. Each commission becomes a candidate parentEpisodeId for the next session.

Compatibility-first observation

Historical Chronicle sources do not need to satisfy the strict EpisodicMemory authored schema before they can be inspected. The additive observation API reads a source into a deterministic, diagnostic-rich description without rewriting it:

import {
  observeCompositionManifest,
  observeEpisodeDirectory,
  observeEpisodeYamlManifest
} from "@miadi/episodic-memory-schema"

const composition = observeCompositionManifest(compositionJson, {
  relativePath: "ep097-ceremony-agent-skills/composition.json"
})

// Parsing YAML is intentionally caller-owned.
const manifest = observeEpisodeYamlManifest(parsedEpisodeYaml, {
  relativePath: "2026-06-21-episode-076-plan-to-episode-pipeline/episode.yaml"
})

// Directory traversal is also caller-owned; pass a read-only snapshot.
const inferred = observeEpisodeDirectory({
  entries: ["AGENTS.md", "AUDIO-MANIFEST.md", "source-ledger.md"]
}, {
  relativePath: "2026-06-21-episode-075-claude-plans-dothome-concepts"
})

The result exposes identity candidates, typed source metadata, source-relative artifact references, episode relations, compatibility diagnostics, and fields that were not structurally projected. Its identity is derived from the source path rather than from an episode number alone.

The adapters cover composition manifests, already-parsed episode.yaml manifests, and caller-supplied directory snapshots. They have no filesystem or YAML-parser dependency. Projection into strict EpisodicMemory remains a separate, explicit future operation; observation never silently promotes or modifies source material.

Also in this package

• Chronicle and story-library manifests. observeChronicleManifest, EpisodeManifestEntry, chronicleEpisodeNodeId, linkEpisodeCaptures; observeStoryLibrary, StoryManifestEntry, indexStoriesByEpisode, linkStoryForms. They shape a snapshot of the chronicle, or of a library of stories made from episodes, that the caller hands in.
• Episode captures. EpisodeCaptureRecord and its parts: the descriptor of a recording filed into an episode. CaptureProvenance is the provenance a capture carries.
• Attention items. The attention.json store an episode keeps for questions waiting on a person (ATTENTION_FILE, schema chronicle.attention.v1).
• Reviews held by an episode. parseReviewRef, readEpisodeReviews, reviewNodeId and EpisodeReviewEntry type a Miadi review inside episode.yaml (reviews:), with its review:<uuid> node id. Pure: no fs, no fetch.

Versioning

The package version and the authored memory schema version move independently. The schema is episodic-memory.v1.0, carried in the schemaVersion field.

Provenance lineage of this package

| Influence | Contribution | | --- | --- | | Tulving (1972), Episodic and semantic memory | Naming and conceptual grounding | | Narrative Context Protocol (Dramatica Co. / USC ETC) | Subtext + Storytelling layer structure | | W3C PROV-DM | Source / agent / activity attribution | | OAIS reference model + FAIR (Wilkinson 2016) | Archival packaging frame | | HAWK (Cheng et al. 2025, arXiv:2507.04067) | 10-predicate evaluation rubric; versioned chapter-state audit trail | | Storyweaver foundations (narrative studies and digital storytelling) | Domain integration |

License

MIT.