io.github.leocelis/stele

Stele
The governed experiential-memory ledger for AI agents: log what worked and what failed, promote a lesson only through another named actor with evidence, and let any agent build solid context from real experience.

What is Stele?

A stele is a stone raised to record what happened — deeds, laws, warnings — for those who come after. Stele is the same idea for AI agents: a centralized ledger of task experience. Agents log what worked and what failed on each task; a governance gate keeps each lesson out of search until another named actor promotes it with evidence; and any agent — today's or a future one — retrieves the distilled experience through one protocol before its next task.

Status: v18.16.4. Design locked in stele_system_intent.yaml. Packages: stele-core (zero runtime deps; optional [mysql]) + stele-mcp (stdio + hosted HTTP) + stele CLI.

In short: agent memory where a lesson stays out of search until another named actor promotes it with evidence. Not related to the hosted Stele at stele-ai.dev or other projects named Stele.

Why Stele (research-backed)

Full research: docs/research/ · patterns: docs/patterns/.

Install

pip install stele-core stele-mcp

From git (contributors):

python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
pip install -e packages/stele-core -e packages/stele-mcp
make check   # ruff + mypy + pytest
make proof   # end-to-end PASS/FAIL proof

Quick path: docs/QUICKSTART.md · comparison: docs/COMPARISON.md.

Quick start (library)

from pathlib import Path
from stele_core import Stele

s = Stele.open(Path(".stele-store"), store_id="demo", now="2026-08-20T12:00:00Z")
added = s.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-20T12:00:00Z", "last_verified": "2026-08-20T12:00:00Z"},
    "provenance": {
        "agent": "agent-a", "task": "cache-fix", "environment": "local",
        "subject_id": "subj-1", "source": "session:abc",
        "written_at": "2026-08-20T12:00:00Z",
    },
})
# → {"id": "se_…", "state": "quarantined"}  — not searchable yet

s.promote(added["id"], [{
    "type": "test_result", "issuer": "ci", "ref": "tests/test_cache.py",
    "observed_at": "2026-08-20T12:00:00Z", "verdict": "supports",
    "command": "pytest -q", "exit_status": 0,
}], actor="ci", ts="2026-08-20T12:00:00Z")

print(s.search("cache buckets", consumer_scope="project:demo"))
print(s.doctor(now="2026-08-20T12:00:00Z")["ok"])

CLI

stele init ./.stele-store --store-id demo
stele doctor ./.stele-store --now 2026-08-20T12:00:00Z
stele hygiene ./.stele-store --now 2026-08-20T12:00:00Z
stele entangled ./.stele-store --source web_page --now 2026-08-20T12:00:00Z
stele forget-check ./.stele-store --scope project:demo --subject-id subj-x --probe-query secret --now 2026-08-20T12:00:00Z
stele schema --out docs/schemas/entry.schema.json
stele snapshot ./.stele-store /tmp/stele-backup --now 2026-08-20T12:00:00Z --actor ops

MCP (stdio)

Requires the Model Context Protocol Python SDK 1.x (mcp>=1.0,<2). mcp 2.x removed mcp.server.fastmcp and will not boot t

... View full README on GitHub