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

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.

Versioning

• v0.2.0 (current) — compatibility-first observation adapters for composition manifests, parsed episode YAML, and descriptor-light directory snapshots
• v0.1.1 — strict authored episodic-memory types and JSON Schema
• The package release is 0.2.0; the authored memory schema remains episodic-memory.v1.0
• Schema version is encoded in the schemaVersion field, independently of 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.