Metadata-Version: 2.4
Name: woven-imprint
Version: 0.1.5
Summary: Persistent Character Infrastructure — characters that survive across time
Author-email: Toni Mikkola <virtaava@gmail.com>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/virtaava/woven-imprint
Project-URL: Documentation, https://github.com/virtaava/woven-imprint/tree/master/docs
Project-URL: Bug Tracker, https://github.com/virtaava/woven-imprint/issues
Keywords: ai,character,memory,persona,llm,npc
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30; extra == "anthropic"
Provides-Extra: sentence-transformers
Requires-Dist: sentence-transformers>=3.0; extra == "sentence-transformers"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: pdf
Requires-Dist: pymupdf>=1.24; extra == "pdf"
Provides-Extra: ui
Requires-Dist: gradio>=5.0; extra == "ui"
Provides-Extra: all
Requires-Dist: openai>=1.0; extra == "all"
Requires-Dist: anthropic>=0.30; extra == "all"
Requires-Dist: sentence-transformers>=3.0; extra == "all"
Requires-Dist: mcp>=1.0; extra == "all"
Requires-Dist: pymupdf>=1.24; extra == "all"
Requires-Dist: gradio>=5.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# Woven Imprint

[![CI](https://github.com/virtaava/woven-imprint/actions/workflows/ci.yml/badge.svg)](https://github.com/virtaava/woven-imprint/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)

**Persistent Character Infrastructure**

Characters that survive across time.

**Setup**: [Windows/WSL](docs/setup-windows.md) | [macOS](docs/setup-mac.md) | [Linux](docs/setup-linux.md) | [Docker](docs/setup-docker.md) | [Developer Guide](docs/DEVELOPER_GUIDE.md) | [Architecture](docs/ARCHITECTURE.md) | [Benchmarks](docs/RESULTS.md) | [MCP Setup](examples/mcp_setup.md)

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.

## The Problem

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.

## Installation

```bash
pip install woven-imprint
```

Requires Python 3.11+ and an LLM backend ([Ollama](https://ollama.com), OpenAI, or Anthropic).
See [Getting Started](docs/GETTING_STARTED.md) for platform-specific setup.

**Prefer a graphical interface?**

```bash
pip install woven-imprint[ui]
woven-imprint ui
```

Opens a browser with chat, character management, migration, and settings — no terminal needed.

## Quick Start

```python
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")
```

## Architecture

### Three-Tier Memory
- **Buffer** — raw observations from recent interactions
- **Core** — consolidated memories, session summaries, reflections
- **Bedrock** — fundamental identity, defining moments, core beliefs

### Multi-Strategy Retrieval
Reciprocal Rank Fusion across five rankers: semantic similarity, BM25 keyword match,
recency decay, importance scoring, and relationship context boost.

### Persona Enforcement
Four constraint levels: hard (immutable identity), temporal (age from birthdate,
location changes), soft (personality traits that evolve), emergent (formed through interaction).

### Relationship Model
Five emotional dimensions (trust, affection, respect, familiarity, tension) with
bounded change per interaction, trajectory detection, and key moment tracking.

### Belief Revision
Memories carry certainty scores. Contradictions are tracked, not overwritten —
characters can genuinely change their mind while remembering what they used to believe.

### Migrate from Existing Systems

Bring characters from other platforms — persona, memories, and relationship history
are automatically extracted and baselined:

```bash
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 file
```

The system analyzes conversation history to calculate relationship baselines
(trust, affection, familiarity) so characters don't start from zero.

## Use Cases

- **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

## Evaluation: Pride and Prejudice

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.

![Elizabeth → Darcy Relationship Arc](docs/charts/elizabeth_darcy_arc.svg)

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

**13/13 synthetic benchmarks passing** (94.8% avg score) — memory recall, cross-session persistence,
belief revision, relationship bounds, persona consistency, character growth.
Benchmarks are deterministic and fully reproducible (no LLM needed).

Full results: [docs/RESULTS.md](docs/RESULTS.md)


## Design Principles

- **Local-first** — SQLite default, runs on consumer hardware, no cloud dependency
- **Model-agnostic** — works with any LLM (Ollama, vLLM, OpenAI, Anthropic)
- **Infrastructure, not app** — provides the persistence layer via clean Python API
- **Characters survive across time** — the core differentiator

## Research Foundations

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](docs/RESEARCH.md)

## License

Apache 2.0 — the core engine is open and easy to adopt.
