Metadata-Version: 2.4
Name: kestrel-feature-story-archive
Version: 0.2.2
Summary: Schema-rich agent life-story archive for Kestrel Sovereign
Project-URL: Homepage, https://kestrelsovereign.com
Project-URL: Source, https://github.com/KestrelSovereignAI/kestrel-feature-story-archive
Project-URL: Issues, https://github.com/KestrelSovereignAI/kestrel-feature-story-archive/issues
Author: UncleSaurus
Maintainer: UncleSaurus
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,kestrel,sovereign-memory,story-archive,timeline
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.15,>=3.11
Requires-Dist: alembic>=1.13
Requires-Dist: kestrel-feature-entities<0.2,>=0.1
Requires-Dist: kestrel-sovereign-sdk<0.20,>=0.17
Requires-Dist: kestrel-sovereign<1,>=0.16
Requires-Dist: numpy>=1.26
Requires-Dist: pgvector>=0.2
Requires-Dist: psycopg[binary]>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: sqlalchemy[asyncio]>=2.0
Provides-Extra: test
Requires-Dist: aiosqlite>=0.19.0; extra == 'test'
Requires-Dist: hypothesis>=6.0; extra == 'test'
Requires-Dist: pytest-asyncio>=1.1.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.3.1; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Requires-Dist: testcontainers[postgres]>=4.0.0; extra == 'test'
Description-Content-Type: text/markdown

# kestrel-feature-story-archive

Schema-rich agent life-story archive for Kestrel Sovereign.

An agent maintains a queryable, semantic archive of its life-story:
interactions, observations, and reflections, organized as a timeline
with vector search and contradiction detection. This is a reusable
framework capability — a sibling package alongside
`kestrel-feature-healthcare` / `-visual` / `-reflection` / `-observability`
— not a host-product feature. Any Kestrel host can consume it.

## Status

Bootstrap skeleton (FEAT-1). Business logic lands in FEAT-2..5:

- **FEAT-2** — entity models (Story, StoryChunk, StoryEvent) + Alembic migrations
- **FEAT-3** — TimelineBuilder (session → Story/StoryEvent/StoryChunk extractor)
- **FEAT-4** — VectorSearch integration for semantic story retrieval
- **FEAT-5** — sharing, replay, export, contradiction detection services

This package migrates the 8,240-LOC Story Archive stack from Frinz into
a reusable feature package so other consumers (RemoteCares/RPM Azure
pilot) can leverage it. Records are scoped to `agent_did` (the canonical
owner identity per the Agent Identity Contract).

## Installation

```bash
uv pip install kestrel-feature-story-archive
```

The package registers `StoryFeature` through the
`kestrel_sovereign.features` entry-point group and registers its entity
models via the `kestrel_entities.models` entry-point for Alembic
autogen.

## Development

```bash
uv sync --extra test
uv run --extra test pytest
```

## Architecture

Records are `agent_did`-scoped and persisted via kestrel-feature-entities
ORM layer. The feature consumes the `DatabaseBackend` from the host and
leverages the Timeline and VectorSearch protocols (kestrel-sovereign-sdk
v0.16.0+).

No product-specific terminology anywhere in this package — vocabulary is
`agent` / `agent_did` / `owner` throughout. This is a framework capability.
