io.github.litheonhq/author-mcp-server
Recall, check, search, timeline, and graph tools for fiction writers via Seizn Memory v3.
Ask AI about io.github.litheonhq/author-mcp-server
Powered by Claude · Grounded in docs
I know everything about io.github.litheonhq/author-mcp-server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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:
| Layer | Why it matters |
|---|---|
| Memory graph | Characters, users, factions, places, scenes, and incidents can persist as graph entities and relationships. |
| Persona/profile | Stable traits and preferences can be separated from transient chat context. |
| Deterministic replay | AI behavior can be reproduced from trace, seed, memory hash, and tool stubs. This is especially important for QA and compliance. |
| Compliance and deletion | RTBF, audit logs, DSR-style deletion, retention, data residency, and policy checks make memory shippable in production. |
| Budget controls | Hot/warm/cold memory tiers, caching, routing, and degrade events keep retrieval cost controllable. |
| Creative continuity | Memory and relationship state can help preserve long-running fiction, NPC history, and world-bible consistency. |
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_entitiesrow withtype = "person" - faction, location, object, incident, scene:
graph_entitieswith 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:
| Domain object | Seizn representation |
|---|---|
| NPC / character / author persona | graph_entities(type="person") plus profile |
| player / reader / user | memory owner, profile, graph entity when needed |
| faction / house / organization | graph entity |
| trust, grudge, kinship, alliance | relationship edge |
| event, quest, episode, scene | graph entity plus linked memories |
| world-bible fact | memory, entity property, or document chunk depending on source |
| "what happened last time" | retrieval context over memory + graph + trace |
Seasonal Architecture
The codebase uses seasonal codenames. They are not marketing fluff; they are the main architecture map.
| Season | Main job | Important paths |
|---|---|---|
| Spring | Memory lifecycle: create/search/update/delete, memory v4, candidates, edges, profiles, temporal search, multimodal memory | src/lib/spring/, src/app/api/spring/, src/app/api/v1/memories/ |
| Summer | RAG and document intelligence: ingestion, chunking, embeddings, retrieval, reranking, answer contracts, federated search | src/lib/summer/, src/app/api/summer/, src/app/api/rag/, docs/ARCHITECTURE_SUMMER.md |
| Fall | Observability and reliability: flight recorder, deterministic replay, evals, experiments, canaries, time travel, self-healing | src/lib/fall/, src/app/api/fall/, src/app/api/retrieval/ |
| Winter | Governance: policy engine, PII, encryption, retention, RTBF, residency, enterprise controls | src/lib/winter/, src/app/api/winter/, docs/compliance/ |
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
| Surface | Purpose | Key paths |
|---|---|---|
| Public web app | Marketing, docs, pricing, trust, localized landing pages | src/app/[locale]/ |
| Dashboard | Memories, usage, traces, orgs, API keys, governance, evals, integrations, webhooks | src/app/(dashboard)/dashboard/ |
| API v1 | Stable memory and graph API surface | src/app/api/v1/ |
| Spring API | Memory v4, candidates, temporal search, mindmap, edges, jobs | src/app/api/spring/ |
| Summer API | RAG, retrieval, explainability, cache, versions, RetOps | src/app/api/summer/ |
| Fall API | Traces, runs, replay, eval datasets, experiments, HNSW tuning | src/app/api/fall/ |
| Winter API | RTBF, org policy, graph permissions, transparency, OPA policy | src/app/api/winter/ |
| MCP server | Claude/Cursor/Windsurf/Codex memory bridge and graph tools | mcp-server/ |
| CLI | Local/offline memory, save/search/export/config/migrate commands | cli/seizn/ |
| SDKs and adapters | JS/Python packages, LangChain, Vercel AI, Spring/Summer SDKs | packages/, sdks/, sdk/ |
Key APIs
Common production entry points:
POST /api/v1/memories: create a memoryGET /api/v1/memories: browse/search memoriesGET /api/v1/memories/{id}: retrieve memory detailsDELETE /api/v1/memories: delete or flush memory scopePOST /api/v1/graph: create/list memory graphsPOST /api/v1/graph/{graphId}/entities: create graph entitiesGET /api/v1/graph/{graphId}/entities?type=person: list people/NPCsGET /api/v1/graph/{graphId}/entities/by-external-id/{externalId}: map game/editor IDs to Seizn IDsGET /api/v1/graph/{graphId}/relationships: list relationshipsPOST /api/summer/rag: document/RAG answer pipelineGET /api/retrieval/traces/{id}: inspect retrieval tracePOST /api/webhooks: manage memory webhooks
Auth uses bearer API keys with the szn_ prefix. Cookie-authenticated dashboard mutations use CSRF protection.
Technology Stack
| Category | Current stack |
|---|---|
| Runtime | Node.js 20, Next.js 16.1.6, React 18.3, TypeScript 5 |
| UI | App Router, Server Components, Tailwind CSS v4, Lucide, Recharts, React Flow |
| Data | Supabase PostgreSQL with pgvector, RLS, migrations under supabase/migrations/ |
| Auth | NextAuth v5 beta, Supabase password verification, OAuth, device flow, API keys |
| Cache/rate limit | Upstash Redis with in-memory fallback |
| AI providers | Anthropic, OpenAI, Google Generative AI, Vercel AI SDK |
| Embeddings | Voyage AI by default, with cache and fallback paths |
| Observability | OpenTelemetry, Sentry, PostHog, Web Vitals, custom flight recorder |
| Security/governance | CSRF, scoped API keys, OPA-style policy, PII scanner, BYOK/KMS, audit logs, retention and RTBF |
| Billing | Billing code contains active Stripe routes and older Paddle references; verify the current provider before changing billing |
| i18n | Custom dictionary system with 22 locales and RTL support |
| Deployment | Vercel production, Docker Compose, Helm, Nginx, Prometheus configs |
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.
| Package/tool | Role |
|---|---|
@seizn/spring | JS/TS memory SDK |
@seizn/summer | JS/TS RAG and document search SDK |
@seizn/core (packages/sdk-core) | Shared SDK primitives |
packages/vercel-ai | Vercel AI SDK integration |
packages/langchain | LangChain adapter/checkpointer integration |
packages/seizn-python | Python SDK package source |
mcp-server | MCP tools/resources for memories, graph, profile, webhooks, config sync |
cli/seizn | CLI with online API commands and offline local memory |
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
ghactive account islitheonhqfor 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:
- Authoring memory dogfood with KNOT: character/persona memory, world graph, continuity, relationship recall.
- Runtime NPC memory: external IDs, person entities, relationship edges, scene/event memory, SDK export.
- Deterministic replay and memory snapshots: QA-grade reproduction of AI behavior.
- Compliance and deletion: audit logs, RTBF, DSR, data residency, policy checks.
- Cost and retrieval control: hot/warm/cold tiers, semantic cache, budget degrade events, planner decisions.
- 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 quickstartdocs/openapi.yaml: API referencedocs/ARCHITECTURE_SUMMER.md: Summer RAG architecturedocs/AI_PLAYBOOK_SEIZN_INFRA.md: Fall/Winter implementation playbookdocs/architecture/TRACE_REPLAY_DESIGN.md: replay UI designdocs/compliance/SECURITY_WHITEPAPER.md: security postureSELF_HOSTING.md: self-hosting guide.github/TECH_STACK.md: detailed stack inventoryCLAUDE.mdandAGENTS.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.
