nap — Narrative Addressing Protocol

NAP is a protocol that makes narrative resources addressable, resolvable, and interoperable across tools, storage systems, formats, and AI workflows.

Characters, locations, scenes, props, and entire fictional repositories — NAP gives each one a stable URI, a human-and-machine-readable manifest, a content-addressed history, and a resolver that connects them all.

In the same way that IPFS content-addressed files and OCI container-addressed images, NAP is narrative-addressed — a universal namespace for the building blocks of stories.

Why NAP?

Today, narrative assets live in silos:

• Worldbuilding docs in Notion or Google Docs
• Character sheets in spreadsheets
• Concept art in Dropbox or S3
• Scene breakdowns in Final Draft or Fade In
• AI prompts scattered across chat logs
• 3D assets on Sketchfab or Polycam

None of these tools talk to each other. NAP unifies them under a single addressing and resolution layer.

nap://starwars/character/lukeskywalker
nap://starwars/location/tatooine
nap://starwars/scene/cantina
nap://toystory/prop/andy-hat

Core Primitives

NAP is built on four primitives:

1. URI — Identity

A nap:// URI identifies any narrative resource. Version and branch are orthogonal selectors passed alongside the URI — never encoded in the path (mirrors Git, OCI, and package managers).

nap://starwars/character/lukeskywalker#references.appears_in
────┬── ───┬──── ────┬──── ──────┬────── ─────────────┬───────────
 scheme repository  entity_type entity_id          fragment (query)

2. Manifest — Current State

A YAML manifest is the durable representation of a narrative resource. It is simultaneously:

• Human-editable — readable by worldbuilders
• Machine-editable — structured, schema-validated
• Agent-readable — subtree-queryable for AI workflows
• Portable — no runtime dependency, just a file
• Signable — hash the content, sign the hash (Ed25519 in v0+)
• Versionable — the manifest is what gets committed

id: "nap://starwars/character/lukeskywalker"
name: "Luke Skywalker"
entity_type: character
version: 17
properties:
  homeworld: "nap://starwars/location/tatooine"
  species: human
representations:
  reference_image:
    hash: "sha256:e3b0c44..."
    format: png
provenance:
  model: "midjourney-v6"
  prompt_hash: "sha256:abc123..."
head: "a72c9f3b..."

3. Commit — History

Commits are content-addressed (BLAKE3) snapshots with patch metadata. The manifest stores only head — a pointer to the latest commit. Full history lives in the VCS, keeping manifests bounded.

4. Resolver — URI → Manifest

The resolver turns a nap:// URI into a manifest (or a subtree of one). With optional selectors for branch or commit hash, it supports versioned resolution and fragment-based queries for efficient data access.

Scene Clips as Representations

Scenes can own generated video clips the same way characters own reference images. A generated clip is not usually a representation of one character; it is a representation of a scene, with references back to the characters, locations, props, and style guides that shaped it.

nap create scene cantina -u starwars -n "Cantina"
nap add nap://starwars/scene/cantina clip-01 ./cantina-clip-01.mp4 --format mp4 -m "Add cantina scene clip"

The scene manifest remains simple and durable:

id: "nap://starwars/scene/cantina"
name: "Cantina"
entity_type: scene
version: 3
properties:
  summary: "Luke and Obi-Wan enter a crowded cantina while searching for passage off Tatooine."
  time_of_day: night
  mood: tense
references:
  characters:
    - "nap://starwars/character/lukeskywalker"
    - "nap://starwars/character/obiwankenobi"
  location: "nap://starwars/location/mos-eisley-cantina"
representations:
  clip-01:
    hash: "blake3:af1349b9..."
    format: mp4
    uri: "clip-01.mp4"
head: "a72c9f3b..."

When resolved with provenance, NAP returns versioned per-file provenance for the manifest and each direct representation. This keeps generation metadata attached to the committed files without requiring users to manage the underlying VCS directly.

nap resolve nap://starwars/scene/cantina --provenance

manifest:
  id: "nap://starwars/scene/cantina"
  name: "Cantina"
  entity_type: scene
  version: 3
  representations:
    clip-01:
      hash: "blake3:af1349b9..."
      format: mp4
      uri: "clip-01.mp4"
provenance:
  revision: "a72c9f3b..."
  files:
    - role: manifest
      path: "scene/cantina.yaml"
      provenance:
        nap.provenance.kind: edit
        nap.provenance.author: worldbuilder
    - role: representation
      name: clip-01
      path: "scene/clip-01.mp4"
      uri: "clip-01.mp4"
      hash: "blake3:af1349b9..."
      format: mp4
      provenance:
        nap.provenance.kind: generation
        nap.provenance.model: video-generator
        nap.provenance.prompt.address: "blake3:b4d2..."

Entity Types

Repository Layout

Each repository is a Git repository on disk:

starwars/                    ← repository root (Git repo)
├── .nap/
│   └── config.yaml          ← repository configuration
├── repository.yaml            ← world manifest
├── characters/
│   ├── lukeskywalker.yaml
│   └── darthvader.yaml
├── locations/
│   └── tatooine.yaml
├── scenes/
│   └── cantina.yaml
└── props/

Installation

Installation Script

curl -fsSL https://github.com/portalshq/narrativeengine/releases/latest/download/install.sh | bash

The installation script installs both native binaries: nap and nap-mcp-server. The MCP server is dormant by default; agent clients start it on demand over stdio so sandboxed agents can use NAP through host-side CLI proxy calls.

Skills Install

Install these skills to use NAP with agent workflows, including entity-aware prompts, generation templates, and the resolve/update steps that keep character and scene output consistent.

npx skills add portalshq/narrativeengine

CLI & Server (Rust — compile from source)

git clone https://github.com/cinematiccanvas/nap.git
cd nap
cargo build --release

# Binaries land in target/release/
#   nap          — CLI tool
#   nap-server   — HTTP resolver server

Python SDK (prebuilt wheel, no Rust needed)

pip install narrativeengine

from narrativeengine import create_block, generate_candidate, render_lore_summary

block = create_block("char-1", "A brave adventurer")
candidate = generate_candidate(block)

TypeScript SDK (prebuilt binary, no Rust needed)

npm install @portalshq/narrativeengine

import { createBlock } from "@portalshq/narrativeengine";

const block = createBlock("char-1", "A brave adventurer");

Quick Start

# Initialize a repository (prompts for provider on first run)
nap init starwars

# Initialize with local provider
nap init starwars --provider local

# Configure provider only (no repository)
nap init --provider local

# Initialize with remote provider
nap init --provider remote --remote-url lore://localhost:41337 --workspace-id my-workspace

# Initialize with Portals Cloud
nap init --provider portals-cloud

# Check system status
nap status

# Run diagnostics
nap doctor

# Run diagnostics with auto-repair
nap doctor --repair

Create a Repository

# Initialize a new repository
nap init starwars

# See what you created
ls starwars/
# → .nap/  repository.yaml  characters/  locations/  scenes/  props/

Create & Inspect Entities

# Create a character
nap create character lukeskywalker -u starwars -n "Luke Skywalker"

# Create a location
nap create location tatooine -u starwars -n "Tatooine"

# Set properties
nap set nap://starwars/character/lukeskywalker species human
nap set nap://starwars/character/lukeskywalker homeworld "nap://starwars/location/tatooine"

# Resolve a manifest
nap resolve nap://starwars/character/lukeskywalker

# Query a specific field
nap resolve nap://starwars/character/lukeskywalker#properties.species
# → human

# Query a subtree
nap query nap://starwars/character/lukeskywalker properties

Version Control

# View commit history
nap history nap://starwars/character/lukeskywalker

# Create branches
nap branch starwars canon

# Sync with remote
nap sync starwars

# Publish to remote
nap publish starwars

Output Formats

nap resolve nap://starwars/character/lukeskywalker -f json
nap resolve nap://starwars/character/lukeskywalker -f yaml

MCP Server

The NAP installer bundles the native nap-mcp-server binary alongside nap. The MCP server is not a daemon; agent clients start it on demand over stdio, and it proxies tool calls to the host nap CLI.

Connect with Codex

Codex stores MCP configuration in ~/.codex/config.toml alongside the rest of its config. The Codex CLI, the ChatGPT desktop app, and the IDE extension all share that MCP configuration, so you only need to register nap once.

Add the server with the CLI:

codex mcp add nap --env NAP_DIR="$HOME/.nap" -- /bin/sh -lc 'exec nap-mcp-server'

If nap-mcp-server is not on PATH, use the full installed path instead, usually ~/.local/bin/nap-mcp-server or /usr/local/bin/nap-mcp-server.

You can also configure it manually in ~/.codex/config.toml:

[mcp_servers.nap]
command = "/bin/sh"
args = ["-lc", "NAP_DIR=\"$HOME/.nap\" exec nap-mcp-server"]
enabled = true

Project-scoped config works too for trusted projects:

[mcp_servers.nap]
command = "/bin/sh"
args = ["-lc", "NAP_DIR=\"$HOME/.nap\" exec nap-mcp-server"]
enabled = true

Use the same block in .codex/config.toml inside a trusted project if you want the server scoped to that repository.

Other MCP Clients

Claude Desktop and other MCP clients use the same stdio pattern. Add a server entry that runs the bundled nap-mcp-server command on demand, and keep NAP_DIR pointed at your NAP workspace if you need a non-default data directory.

Example host-side launch command:

/bin/sh -lc 'NAP_DIR="$HOME/.nap" exec nap-mcp-server'

Use the same command/args form in any client that supports stdio MCP servers.

Inside sandboxes, use the MCP tools instead of shelling out to nap directly for network-backed operations. Direct nap CLI commands remain the right choice for humans and host-local shells.

NAP CLI Reference

The nap command-line interface (v0.5.4) provides tools for creating, resolving, and managing narrative resources using the Narrative Addressing Protocol.

Command Overview

Global Options

Output Formats

Most commands support --format (-f) with values yaml (default) or json.

When stdout is not a terminal, JSON is used automatically. Override with $NAP_OUTPUT.

Common Examples

# Initialize a repository
nap init starwars

# Create an entity
nap create character lukeskywalker -u starwars -n "Luke Skywalker"

# Resolve a manifest
nap resolve nap://starwars/character/lukeskywalker

# Query a subtree
nap query nap://starwars/character/lukeskywalker properties

# View commit history
nap history nap://starwars/character/lukeskywalker

HTTP Server

The NAP resolver server provides a REST API for resolution and commits.

# Start the server (defaults to port 3100, base path = current directory)
nap-server

# Custom port and base path
NAP_PORT=8080 NAP_BASE_PATH=/path/to/repositories nap-server

Configuration

NAP core uses environment variables for configuration. All variables serve specific purposes with minimal overlap.

Storage Configuration

Lore VCS Configuration

Constants

Note: The environment variable NAP_DIR (storage base directory) and the constant NAP_DIR (metadata directory name) serve different purposes and do not overlap.

Endpoints

Query parameters for resolution: branch, commit, path (subtree query).

CLI Command Reference

Complete reference for all nap CLI commands.

Design Principles

1. Content-addressed — Every piece of content is identified by its cryptographic hash. Manifests are immutable once committed.

2. URI-addressed — Every entity has a stable, portable URI. URIs are never invalidated by renames or moves.

3. Human-readable — YAML manifests are readable by worldbuilders and AI agents alike.

4. Portable — No runtime dependencies. A manifest is just a YAML file. A repository is just a Git repo.

5. AI-native — Subtree queries let AI agents fetch exactly the data they need. Provenance tracking records generation metadata.

6. Schema-validated — All manifests conform to a JSON Schema. Invalid manifests are rejected at commit time.

7. Decentralized — Repositories are Git repositories. They can be cloned, forked, merged, and published independently.

8. Extensible — New entity types, representation formats, and merge strategies can be added without breaking existing data.

Status

This is a v0 prototype. APIs and formats may change.

License

MIT

Status

This is a v0 prototype. APIs and formats may change.

License

MIT