Metadata-Version: 2.5
Name: stele-core
Version: 18.16.1
Summary: Governed experiential-memory ledger for AI agents — quarantine, oracle promotion, hybrid retrieval, pack export. Zero runtime dependencies.
Project-URL: Homepage, https://github.com/leocelis/stele
Project-URL: Documentation, https://github.com/leocelis/stele/blob/main/docs/OSS_GUIDE.md
Project-URL: Repository, https://github.com/leocelis/stele
Project-URL: Changelog, https://github.com/leocelis/stele/blob/main/CHANGELOG.md
Author: Stele contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,deterministic,experiential-memory,ledger,local-first,mcp,memory
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Provides-Extra: mysql
Requires-Dist: pymysql<2,>=1.1; extra == 'mysql'
Description-Content-Type: text/markdown

# stele-core

Governed experiential-memory ledger for AI agents.

Agents `ADD` distilled lessons into **quarantine**. Promotion requires
**external-oracle evidence**. Retrieval serves **promoted** entries only
(hybrid keyword + optional semantic + temporal), budgeted as slices.
Exports are redacted **packs** — the live store is never the sharing surface.

**Zero runtime dependencies.** Callers supply an optional embedder callable
for semantic search; the default path never networks and never calls an LLM.

## Install

```bash
pip install -e packages/stele-core
```

## Quick start

```python
from pathlib import Path
from stele_core import Stele

store = Stele.open(Path("./.stele-store"), store_id="demo")
result = store.add({
    "layer": "failure_lesson",
    "title": "Pin cache keys to calendar buckets",
    "body": "Day-scoped keys prevent stale cross-day reads.",
    "scope": "project:demo",
    "temporal": {"valid_from": "2026-08-20T00:00:00Z", "last_verified": "2026-08-20T00:00:00Z"},
    "provenance": {
        "agent": "agent-a",
        "task": "cache-fix",
        "environment": "local",
        "subject_id": "subj-demo",
        "source": "session:abc",
        "written_at": "2026-08-20T12:00:00Z",
    },
})
# result == {"id": "se_...", "state": "quarantined"}
```

See the repo [`docs/TECH_SPEC.md`](../../docs/TECH_SPEC.md) for the full contract.
