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 this server.

Default (`stele-mcp`): 35 governed-ledger tools — add, promote, search, doctor, export, …

export STELE_STORE=./.stele-store

stele-mcp

{

"mcpServers": { "stele": { "command": "uvx", "args": ["stele-mcp"], "env": { "STELE_STORE": "/absolute/path/to/.stele-store" } } } }

Pass ts on every write; the store never reads the clock.

Full research library (~2000 PEFT/agent-pattern tools): stele-mcp-full.

MCP (hosted HTTP)

Same tools over HTTPS (SSE + streamable HTTP). Two independent tool surfaces, same process, same auth, same store:

Production:

• URL: https://stele.leocelis.com/sse · core: https://stele.leocelis.com/core/sse (Bearer required, no self-serve keys; to host your own see deploy/README.md)
• Client setup: docs/integrations/CURSOR.md · CLAUDE_CODE.md · CLAUDE_DESKTOP.md
• Agent rule: docs/cursor-rules/stele-hosted-mcp.mdc

Local run (dev):

bash deploy/build.sh

STELE_API_KEYS=stl_local_dev STELE_AUTH_DISABLED=false \ STELE_STORE=./.stele-store \ python deploy/wsgi.py --port 8080

• GET /health — unauthenticated; reports tool_counts: {full, core}
• /sse + /mcp (full) and /core/sse + /core/mcp (ledger-only) — both Bearer via STELE_API_KEYS
• Hosted durable SoT: STELE_STORE_DSN + TLS CA (DSN wins over file path)
• Never commit API keys, DSNs, or PEMs

{

"mcpServers": { "stele": { "url": "https://stele.leocelis.com/core/sse", "headers": { "Authorization": "Bearer YOUR_KEY_HERE" } } } }

35 governed-ledger tools (TECH_SPEC §7.1-7.9 — everything create_core_app() exposes): add · update · promote · supersede · delete · search · reflect · link · list_contested · resolve_contested · verify · reviewer_corrections · hydrate · export · record_outcome · pin · stale_report · reverify · related · stats · timeline · verify_pack · attach · snapshot · doctor · entry_schema · purge_by_provenance · diff_stores · add_batch · entangled_suspects · hygiene_candidates · forget_compliance · lineage · belief_at · conflict_surface

Architecture

See docs/ARCHITECTURE.md. Planes: Contract · Tools · Governance · Retrieval · Export · Living ledger · Ops.

License

MIT · Copyright (c) 2026 Stele contributors