Persistent Character Infrastructure
Characters that survive across time.
Getting Started | UI Guide | Migration | Configuration | Developer Guide | Architecture
Platform setup: Windows/WSL | macOS | Linux | Docker | MCP Setup
Woven Imprint is infrastructure for building AI characters that persist. Characters accumulate memories across sessions, maintain consistent personalities, and develop relationships that evolve over weeks and months of interaction.
Your NPC remembers the player who helped them three weeks ago. Your companion recalls a conversation from last summer. Your training partner adapts to the learner's progress over hundreds of sessions.
Every interaction leaves an imprint. Every memory is woven into who the character becomes.
Most AI characters reset every session. They forget who you are, what you told them, and what happened between you. The few systems that try to persist memory do it poorly — stuffing facts into a prompt window until it overflows.
Games, companions, simulations, and interactive fiction all need characters that:
- Remember the player weeks later — not just the last 5 minutes
- Stay consistent — same personality, same backstory, same voice
- Develop relationships — trust builds slowly, betrayal has consequences
- Grow — opinions shift, habits form, characters change through experience
No existing tool does all of this. Woven Imprint does.
pip install woven-imprintRequires Python 3.11+ and an LLM backend (Ollama, OpenAI, or Anthropic).
Configure your provider in ~/.woven_imprint/config.yaml or via env vars — see Configuration.
See Getting Started for platform-specific setup.
pip install woven-imprint[demo]
woven-imprint demoOpens a browser with:
- Chat with Meridian (our demo wizard) or your own characters
- X-Ray panel showing memory, emotions, and relationships updating in real time
- Character management — create, import (JSON/PNG/SillyTavern cards), export, migrate
- Provider support — Ollama, OpenAI, Anthropic, DeepSeek, NVIDIA NIM, or any OpenAI-compatible API with live model discovery
Use --host 0.0.0.0 to expose on your local network or a remote server.
from woven_imprint import Engine
engine = Engine("characters.db")
# Create a character with persistent identity
alice = engine.create_character(
name="Alice",
birthdate="1998-03-15", # age derived automatically, increments on birthday
persona={
"backstory": "A sharp-witted detective who left the force after her partner's death.",
"personality": "witty, skeptical, secretly lonely",
"speaking_style": "clipped sentences, dark humor, avoids emotional topics",
"occupation": "private investigator",
},
)
# Conversation — memories persist automatically
response = alice.chat("Hey Alice, how's the case going?")
# End session — generates summary, stores to long-term memory
alice.end_session()
# Days later... she remembers
response = alice.chat("Remember the harbor case we discussed?")
# Character reflects on accumulated experiences
alice.reflect()
# Relationship tracking — trust, affection, respect evolve per interaction
print(alice.relationships.describe("player_1"))
# Export full character state — portable, self-contained
alice.export("alice_v1.json")- Buffer — raw observations from recent interactions
- Core — consolidated memories, session summaries, reflections
- Bedrock — fundamental identity, defining moments, core beliefs
Reciprocal Rank Fusion across five rankers: semantic similarity, BM25 keyword match, recency decay, importance scoring, and relationship context boost.
Four constraint levels: hard (immutable identity), temporal (age from birthdate, location changes), soft (personality traits that evolve), emergent (formed through interaction).
Five emotional dimensions (trust, affection, respect, familiarity, tension) with bounded change per interaction, trajectory detection, and key moment tracking.
Memories carry certainty scores. Contradictions are tracked, not overwritten — characters can genuinely change their mind while remembering what they used to believe.
Bring characters from other platforms — persona, memories, and relationship history are automatically extracted and baselined:
woven-imprint migrate conversations.json # ChatGPT export
woven-imprint migrate character_card.png # SillyTavern / TavernAI
woven-imprint migrate --text "You are Marcus..." # Custom GPT instructions
woven-imprint migrate /path/to/claude/project/ # Claude Code project
woven-imprint migrate persona.md # Any markdown/text fileThe system analyzes conversation history to calculate relationship baselines (trust, affection, familiarity) so characters don't start from zero.
- Game NPCs — characters with real memory across play sessions
- AI Companions — persistent personality that remembers and evolves
- Interactive Fiction — characters that develop relationships over branching narratives
- Training Simulations — consistent role-playing partners that adapt over time
- Virtual Personalities — maintained identity across platforms and contexts
We tested Woven Imprint by simulating 16 key scenes from Jane Austen's Pride and Prejudice (public domain, Project Gutenberg). The engine tracked 6 characters across the full story arc with no scripted outcomes — all relationship changes are LLM-assessed from conversation content.
The arc matches the novel: hostility peaks at the Hunsford proposal (trust -0.22, tension 0.39), flips after Darcy rescues the Bennets (affection turns positive), and resolves at the second proposal (trust +0.06, affection +0.22, familiarity 0.99).
14/14 deterministic benchmarks (97.9% avg) + 4 live persistence tests with real LLM. Covers memory recall, cross-session persistence, consolidation, belief revision, relationship bounds, persona consistency, adversarial persona resistance, and contradiction handling.
Full results: docs/RESULTS.md
We ran woven-imprint on characters from the LIGHT dataset (Facebook Research, MIT License) — a public dataset of 1,324 fantasy characters across 661 locations. No hand-crafted scenarios; all character data is verifiable from the source.
Characters interact through character.chat(), and woven-imprint handles everything behind the scenes: memory accumulation, relationship updates, persona consistency. The visualization shows agents clustering by affinity (force-directed layout), edge colors shifting from gray (neutral) to green (trust) or red (tension), and speech bubbles with LLM-generated dialogue.
Three LIGHT rooms simulated over 15 turns each: a palace dungeon (prisoners vs. royalty), a castle bazaar (knights, farmers, vendors), and a great hall (kings, servants, visitors). A separate 282-character world simulation across 107 rooms produced 175 emergent relationships.
Full breakdown: docs/LIGHT_SIMULATION_RESULTS.md
- Local-first — SQLite default, runs on consumer hardware, no cloud dependency
- Model-agnostic — config-driven provider selection (Ollama, OpenAI, Anthropic, vLLM, llama.cpp)
- Infrastructure, not app — provides the persistence layer via clean Python API
- Characters survive across time — the core differentiator
Architecture influenced by academic research on memory-augmented LLM agents, persona consistency, and relationship modeling — including work by Park et al. (Generative Agents), Mem0, Engram, and NLI-based persona consistency methods.
Full citations and synthesis: docs/RESEARCH.md
Apache 2.0 — the core engine is open and easy to adopt.