Seizn

Seize your memories. Seizn is the memory layer for AI characters, agents, and creative IP systems.

This README is written as the repo-level orientation file for human and AI operators. After reading only this file, another agent should understand what Seizn is, where the product is pivoting, how the codebase is organized, and which commands and guardrails matter.

Current Product Thesis

Seizn is not an LLM, not a vector database, and not a generic chatbot shell. It is a stateful memory operating layer around AI applications.

The core product stores, retrieves, governs, and explains long-lived context:

• memories: facts, preferences, events, instructions, experiences, relationships
• profile/persona state: stable user, character, or agent traits
• graph state: entities, relationships, provenance, external IDs, observations
• retrieval context: hybrid search, RAG, reranking, answer contracts, traceable evidence
• runtime controls: replay, budget controls, policy checks, retention, audit logs, webhooks

The current strategy is a hybrid wedge:

• Seizn Author: authoring memory for serial fiction, VN, TRPG, manga, drama rooms, and IP builders. This is the 2026-05 candidate direction. The KNOT integration is the first dogfood and PMF test.
• Seizn Live: runtime memory middleware for game NPCs and AI characters. This is the 2026-04 NPC memory pivot and remains valid.

The unifying wedge is:

Build IP and character memory in an authoring surface, then export the same memory graph into a game or agent runtime.

The product should not be positioned as "a better memory API" in the abstract. The sharper pitch is:

• memory layer for IP builders
• AI memory layer for serial fiction
• persistent memory for AI NPCs
• replayable, governable, debuggable memory for AI systems

Why This Pivot Exists

The first pivot narrowed Seizn toward game NPC memory middleware. The reasoning was that Inworld, Convai, NVIDIA ACE, and similar stacks are strong at dialogue, voice, and expression, but long-lived memory and relationship persistence remain thin.

The 2026-05 candidate pivot adds an authoring angle. While working on KNOT, the useful stack became clear:

Seizn memory + persona/profile + world/relationship graph

That same stack is valuable before runtime, while writers and IP builders are designing characters, relationships, episodes, and continuity. The market may be broader and faster to test than game studio middleware alone.

Current decision state:

• Do not treat Seizn Author as a completed full pivot yet.
• Use KNOT as the first dogfood loop.
• If the authoring workflow gives strong signal, build a Seizn Author web surface and test with a small beta group.
• If signal is weak, keep Author as an internal KNOT tool and continue Seizn Live for games.
• Core assets survive either path: SDK, MCP, Graph, Profile, memory search, replay, governance.

Differentiation

Do not sell Seizn as "better semantic search." That is commodity in 2026.

The stronger differentiation is:

The roadmap filter for new features is:

Does this make AI memory more reproducible, governable, debuggable, exportable, or useful for creators building persistent characters?

Canonical Domain Model

The active graph/person model is graph_entities, not a separate characters table.

For creative and NPC work:

• person or NPC: graph_entities row with type = "person"
• faction, location, object, incident, scene: graph_entities with the appropriate type
• relationship: graph relationship edge between entities
• memory: timestamped textual or multimodal note tied to user, namespace, agent, scope, and optional graph context
• profile/persona: stable derived state used to shape recall and context
• external ID: stable mapping from game/editor/world-bible object IDs into Seizn graph IDs

Primitive mapping for games and fiction:

Seasonal Architecture

The codebase uses seasonal codenames. They are not marketing fluff; they are the main architecture map.

These four layers are meant to compose:

Application event
  -> Spring extracts/stores memory
  -> Summer retrieves grounded context
  -> Fall records and replays behavior
  -> Winter enforces policy, deletion, residency, and auditability

Product Surfaces

Key APIs

Common production entry points:

• POST /api/v1/memories: create a memory
• GET /api/v1/memories: browse/search memories
• GET /api/v1/memories/{id}: retrieve memory details
• DELETE /api/v1/memories: delete or flush memory scope
• POST /api/v1/graph: create/list memory graphs
• POST /api/v1/graph/{graphId}/entities: create graph entities
• GET /api/v1/graph/{graphId}/entities?type=person: list people/NPCs
• GET /api/v1/graph/{graphId}/entities/by-external-id/{externalId}: map game/editor IDs to Seizn IDs
• GET /api/v1/graph/{graphId}/relationships: list relationships
• POST /api/summer/rag: document/RAG answer pipeline
• GET /api/retrieval/traces/{id}: inspect retrieval trace
• POST /api/webhooks: manage memory webhooks

Auth uses bearer API keys with the szn_ prefix. Cookie-authenticated dashboard mutations use CSRF protection.

Technology Stack

For a deeper stack inventory, see .github/TECH_STACK.md. Treat that file as implementation inventory, and this README as product and architecture orientation.

Repository Map

src/app/                  Next.js app routes, dashboard, public pages, API route handlers
src/app/api/              All server API domains
src/lib/spring/           Memory v3/v4, candidates, profiles, graph edges, temporal search
src/lib/summer/           RAG, ingestion, chunking, retrieval, versions, federated search
src/lib/fall/             Flight recorder, replay, evals, experiments, canaries, healing
src/lib/winter/           Policy, RTBF, retention, residency, privacy controls
src/lib/memory/           Shared memory search, encryption, lifecycle, router learning
src/lib/graph*/           Graph RAG and external ID helpers
src/lib/ai-gateway/       Multi-provider AI gateway, routing, retry, load balancing
src/lib/connectors/       External connectors and federated sources
src/components/           Dashboard, graph, devtools, memory, budget, governance UI
src/i18n/                 Locale config and dictionaries
supabase/migrations/      Database schema and RLS migrations
docs/                     Architecture, compliance, quickstarts, procurement, deployment docs
mcp-server/               Model Context Protocol server
cli/seizn/                CLI and local offline memory store
packages/                 SDKs and integrations
sdks/                     Additional SDK code
deploy/                   Docker, Helm, Nginx, Prometheus
e2e/                      Playwright tests
scripts/                  Build, verification, migration, docs, market scripts

Development

Prerequisites:

• Node.js 20+
• npm, using the root package-lock.json
• Supabase/PostgreSQL-compatible environment variables
• Provider keys only when exercising provider-backed paths

Install and run:

npm ci
npm run dev

Quality gates:

npm run typecheck
npm run lint
npm run test:run
npm run build

Useful focused checks:

npm run check:routes
npm run verify:e2e-encryption-db
npm run verify:runtime-primitives
npm run test:security
npm run test:security:strict

npm run build runs scripts/check-route-conflicts.js before next build. It requires a valid local env; never commit .env.local or secrets.

Migration Workflow

For DB changes, use the repo migration wrapper:

node scripts/run-migration-file.mjs <path-to-sql>
npm run verify:e2e-encryption-db

The wrapper runs E2E encryption/search-RPC verification by default. If SQL is applied manually in Supabase Dashboard, run the verifier manually once afterward.

Do not regenerate or stage broad migration bundles unless the task explicitly asks for that. Supabase temp files and generated all-migration dumps are common local noise.

SDK, MCP, and CLI

Seizn is meant to be used by applications and AI tools, not only through the web dashboard.

The MCP server exposes memory and graph operations to Claude, Cursor, Windsurf, Cline, and config-sync paths for Copilot/Aider/Codex-style tools.

Security and Governance Notes

Important implemented boundaries:

• API key auth uses hashed szn_ keys.
• Cookie-authenticated mutations require CSRF checks.
• E2E confidential memories store ciphertext and are excluded from normal search/embedding.
• RTBF and retention paths live under Winter.
• Webhooks perform SSRF checks and pin validated public IPs before delivery.
• Federated source admin routes must enforce organization membership before service-role writes.
• Logs should never include raw bearer tokens, cookies, API keys, private keys, or provider secrets.

When adding memory features, think about deletion, auditability, and replay at the same time as retrieval quality.

AI-Agent Operating Guardrails

This repo often has a dirty root worktree. Do not stage broad mixed changes as one blob.

Before committing or pushing:

• verify local repo state with git status --short --branch
• verify identity is the Litheon identity for Seizn
• verify gh active account is litheonhq for GitHub-sensitive work
• stage only files in the current task scope
• avoid .vercelignore, Supabase temp files, generated migration bundles, and unrelated brand assets unless explicitly requested
• run the relevant gates and report what was not run

Deployment rule:

• Preview deployments are prohibited.
• If deployment is requested, use production-only flows or stop when production deployment is unsafe.

Current Strategic Priorities

Near-term Seizn work should bias toward:

1. Authoring memory dogfood with KNOT: character/persona memory, world graph, continuity, relationship recall.
2. Runtime NPC memory: external IDs, person entities, relationship edges, scene/event memory, SDK export.
3. Deterministic replay and memory snapshots: QA-grade reproduction of AI behavior.
4. Compliance and deletion: audit logs, RTBF, DSR, data residency, policy checks.
5. Cost and retrieval control: hot/warm/cold tiers, semantic cache, budget degrade events, planner decisions.
6. Memory explainability: why a memory was recalled, why it was not, trace receipts, answer contracts.

Avoid chasing generic benchmark wins unless they directly improve production value for creators, game teams, or governed AI systems.

Documentation Pointers

• docs/quickstart.md: SDK/API quickstart
• docs/openapi.yaml: API reference
• docs/ARCHITECTURE_SUMMER.md: Summer RAG architecture
• docs/AI_PLAYBOOK_SEIZN_INFRA.md: Fall/Winter implementation playbook
• docs/architecture/TRACE_REPLAY_DESIGN.md: replay UI design
• docs/compliance/SECURITY_WHITEPAPER.md: security posture
• SELF_HOSTING.md: self-hosting guide
• .github/TECH_STACK.md: detailed stack inventory
• CLAUDE.md and AGENTS.md: local operating instructions for agents

License

Most package metadata in this repo declares MIT; the MCP server declares Apache-2.0. This checkout does not currently include a root LICENSE file, so check the relevant package metadata before publishing or redistributing artifacts.