Provides a governed experiential-memory ledger that allows AI agents to log task outcomes and promote verified lessons through multi-actor evidence.
Also known as leocelis/stele, stele-mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 402
- Latest version
- 18.16.4
- Last commit
- Nov 6, 2026
- License
- MIT
What is Stele MCP?
Stele provides a governed experiential-memory ledger that allows AI agents to log task outcomes and promote verified lessons through multi-actor evidence.
Summary generated from the project's README
About Stele MCP server
Stele provides a centralized ledger designed for AI agents to record and verify task outcomes. Instead of simple memory, it functions as a governed experiential-memory system where agents log successes and failures. To prevent the entrenchment of errors, new lessons are kept in a quarantined state and only become searchable once a different named actor promotes them using specific evidence. This mechanism ensures that agents build context from verified experiences rather than unverified self-reflection.
Developers can run this server locally via stdio using the stele-mcp package or connect to a hosted HTTP service. The local setup requires a specified STELE_STORE path, while the hosted version uses Bearer authentication via API keys. The core version offers 35 governed-ledger tools including add, promote, search, and doctor. For those needing more extensive capabilities, the full version provides over 2,000 tools from a research library of agent patterns and PEFT tools.
What you can do with it
- 1Log task outcomesAn agent can record a specific failure or success to the ledger to prevent repeating mistakes.
- 2Verify agent lessonsA second actor can promote a quarantined lesson by providing supporting evidence like test results.
- 3Retrieve verified contextAn AI client can search the ledger to find distilled, proven experiences relevant to a current project scope.
- 4Maintain ledger healthDevelopers can use diagnostic tools to check the integrity and hygiene of the stored memory.
Written from the project's README. Every use case is checked against a quote from it.
How to install Stele MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Stele MCP in Claude Code
$ claude mcp add stele -- uvx stele-mcpInstall Stele MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"stele": {
"command": "uvx",
"args": [
"stele-mcp"
]
}
}
}Install Stele MCP in VS Code
.vscode/mcp.json
{
"servers": {
"stele": {
"type": "stdio",
"command": "uvx",
"args": [
"stele-mcp"
]
}
}
}Install Stele MCP in VS Code CLI
$ code --add-mcp '{"name":"stele","type":"stdio","command":"uvx","args":["stele-mcp"]}'Install Stele MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"stele": {
"command": "uvx",
"args": [
"stele-mcp"
]
}
}
}Install Stele MCP in Codex
$ codex mcp add stele -- uvx stele-mcpInstall Stele MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.stele] command = "uvx" args = ["stele-mcp"]
Install Stele MCP in Gemini CLI
$ gemini mcp add -s user stele uvx -- stele-mcpInstall Stele MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"stele": {
"command": "uvx",
"args": [
"stele-mcp"
]
}
}
}Configuration
STELE_API_KEYSSTELE_STOREPath to the ledger store. Default ./.stele-store
| Name | Description | |
|---|---|---|
| STELE_API_KEYS | — | |
| STELE_STORE | Path to the ledger store. Default ./.stele-store |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableleocelis/stele is public and reachablegithub.com/leocelis/stele ↗Pass
- Package names this repository as its sourcestele-mcp names leocelis/stele as sourcepypi.org/project/stele-mcp/ ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-06github.com/leocelis/stele ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from stele-mcpPass
- No critical advisory in the package or its dependencies31 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubWhat 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)
| Problem | Evidence | Stele answer |
|---|---|---|
| Recall wins ≠ better actions | MemoryArena (arXiv:2602.16313) | Task-outcome harnesses, not recall@k marketing |
| Self-reflection can entrench errors | Survey (arXiv:2603.07670) | Quarantine until another named actor promotes it with supporting evidence |
| Every framework is a silo | memorywire (arXiv:2606.01138) | JSON Schema + projection helpers |
| Facts change over time | LongMemEval (arXiv:2410.10813) | Bi-temporal supersede + stale_policy |
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:
| Surface | SSE | Streamable HTTP | Tools |
|---|---|---|---|
| Full | /sse |
/mcp |
2003 (ledger + PEFT/pattern research library) |
| Core (governed ledger only) | /core/sse |
/core/mcp |
35 — see list below |
Production:
- URL:
https://stele.leocelis.com/sse· core:https://stele.leocelis.com/core/sse(Bearer required, no self-serve keys; to host your own seedeploy/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; reportstool_counts: {full, core}/sse+/mcp(full) and/core/sse+/core/mcp(ledger-only) — both Bearer viaSTELE_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.
| Doc | Link |
|---|---|
| OSS guide (start here) | docs/OSS_GUIDE.md |
| Quickstart | docs/QUICKSTART.md |
| PRD | docs/PRD.md |
| TECH_SPEC v1.1 | docs/TECH_SPEC.md |
| Entry JSON Schema | docs/schemas/entry.schema.json |
| Intent (C1–C8) | stele_system_intent.yaml |
License
MIT · Copyright (c) 2026 Stele contributors
Stele MCP questions
How do I add Stele MCP to Claude Code?
Run claude mcp add stele -- uvx stele-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Stele MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does Stele ensure memory quality?
It uses a governance gate where lessons are quarantined and kept out of search until another named actor promotes them with supporting evidence.
Is there a hosted version of Stele available?
Yes, there is a hosted version providing both a full research library and a core governed ledger via HTTPS.