@miadi/episodic-memory-schema

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

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 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

pnpm add @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.

Versioning

• v0.1.0 (current) — initial schema; expect minor additions before v1.0
• Schema version is encoded in the schemaVersion field, not just the package version

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 (foundations/narrative-studies-and-digital-storytelling/) | Domain integration |

License

MIT.