Entroly is an open-source context-control layer for AI agents. It combines repository indexing, budgeted selection, compression, provenance, recoverable handles, memory, output-risk signals, and guarded adaptation. Those capabilities are available through different runtime surfaces; installing one package does not imply that every optional path is active.
This document describes implementation boundaries. Numeric public claims belong in the public evidence ledger, where each result is tied to a protocol and artifact.
eligible sources
↓
index + fingerprint + dependency metadata
↓
query-conditioned scoring and deduplication
↓
explicit token-budget selection
↓
full / skeleton / reference representations
↓
context receipt + omitted-evidence record + recovery handles
↓
configured model or agent runtime
↓
optional output-risk signals and request-bound outcome recording
Entroly does not silently turn an omitted fragment into proof that the fragment was irrelevant. Receipts expose the decision so a caller can inspect, rehydrate, retry, or change the budget.
| Surface | Role | Important boundary |
|---|---|---|
| Python package | Reference SDK, CLI, MCP server, proxy, memory, and verification paths | pip install entroly can use the Python fallback; verify native capability separately |
| Optional Rust core | Accelerates supported indexing, scoring, selection, and receipt operations through PyO3 | Importability alone is not a readiness check; use capability probes |
| Rust binary | Standalone supported native paths without a Python runtime | Validate target architecture and operating-system dependencies |
| npm MCP package | Node-distributed MCP entry point | Package identity and supported commands are version-specific |
| WASM package | Browser/Node-compatible supported algorithms | It is a separate runtime, not proof of full Python parity |
| OpenClaw plugin | Context-engine integration after OpenClaw normalizes provider messages | OpenClaw retains provider selection, authentication, failover, and wire ownership |
See product-surface.md for the current command and package map.
The index stores fragments, token estimates, fingerprints, source metadata, and supported dependency information. Startup reconciliation and change listeners update stale entries rather than assuming a previous snapshot is current.
Important boundaries:
Entroly can combine lexical relevance, entropy-derived signals, dependencies, recency, provenance, risk, and diversity. A knapsack solver selects against Entroly’s scoring objective and explicit budget.
“Optimal” applies only to the stated objective and eligible candidates for an exact solver path. It does not mean the selected context is universally best for answer quality. Learned, heuristic, fallback, and submodular paths must identify themselves as such.
Token reduction, answer quality, latency, cache behavior, and provider cost are separate measurements.
Selected content can be represented at multiple resolutions:
Content-Compressed Retrieval and Context Commit paths can attach handles and commitments to captured content. Recovery depends on retaining the corresponding state and authorization. A valid hash proves integrity of bytes, not truth, safety, or entitlement to disclose them.
Recovery stores should follow the same access, retention, deletion, and backup policy as the original source.
Receipts can record selected and omitted fragment identities, source hashes, budgets, model metadata, costs, and decision traces. Coverage depends on the integration path; Entroly does not claim that every response automatically receives every receipt type.
Byte-level, symbol, relational, and semantic verifiers emit risk signals. They can produce false positives and false negatives. A “pass” is not a correctness proof and does not replace compilation, tests, execution, review, or domain validation.
See limitations.md and context-commits.md.
Memory OS separates short-lived working state, episodic records, consolidated knowledge, and retrieval policy. Task dreaming can recall related memories and bounded current-source excerpts to prepare a task overlay.
Durable task memory is fail-closed:
An overlay is task context, not an authority to modify repository policy or impersonate expertise. Stable project instructions remain in the repository’s human-reviewed guidance files.
See memory-ecosystem.md and verified-dreaming.md.
Structural synthesis can create a candidate tool from repository structure without a provider call. Local compute, filesystem access, and operational cost still apply.
The lifecycle is:
gap → candidate → output-contract benchmark → testing → promote or prune
Candidate execution is disabled by default. Promoted-skill execution requires explicit enablement. Promotion requires at least one eligible benchmark run under the current contract; a tool that merely returns a successful process exit cannot pass when its structured output is wrong, empty, unsafe, or stale.
Generated tools return bounded source excerpts and remain subject to the same security and authorization rules as handwritten tooling.
The dreaming loop uses scenarios to diversify bounded policy proposals. A world model may rank which proposals deserve a real evaluation. Synthetic transitions do not promote a policy.
Promotion requires real benchmark evidence and Pareto gates. The stronger verified-dream controller additionally requires disjoint committed candidate and incumbent holdout transitions bound to one policy version. Entroly must not manufacture duplicate holdout evidence merely to satisfy that gate.
All adaptive paths need a retained incumbent and a rollback path. Insufficient evidence means “keep testing,” not “promote.”
Core protections include:
“Local-first” means core analysis paths can run locally. When a cloud model is configured, selected prompt content still goes to that provider. Review SECURITY.md and first-run-trust.md before production use.
The dashboard and receipts can show source tokens, selected tokens, cache signals, model identity, and modeled cost. Its Context Health panel separately reports retrieval-adjusted net tokens after re-expansion, provider-observed cache categories, hash-only prefix continuity, recovery tax, receipt integrity, omission recoverability, and observed unsupported-claim suppressions. The privacy-safe share text contains aggregate counters only. Economic net value remains unavailable without a paired baseline; a modeled dollar value depends on the configured price table and is not a provider invoice; unmeasured source freshness remains unavailable.
No-provider-call paths still use local CPU, memory, storage, and operator time. Public copy should say “no additional provider call” rather than “free.”
Critical workflows should either complete atomically or fail visibly:
Silent failure, partial publication, and unlabelled fallback are trust defects.
Start with:
pip install entroly
cd /path/to/repository
entroly verify-claims
That command is a bounded local install smoke, not an answer-quality or billing guarantee. For benchmark commands, raw artifacts, scope, and known limitations, use:
Keep failures in benchmark denominators. Publish repository revision, package version, environment, budget, cache state, and uncertainty. Never generalize a single workload into universal superiority.
Python orchestrates; the Rust core (entroly-core, via PyO3) does the
compute-heavy work, and a separate Node runtime ships through WASM. The Rust
core is a required dependency of the base install, not an extra: query
conditioned selection is gated on it, so an install without it fills the token
budget without ever reading the query. entroly verify-claims reports the
engine mode it actually exercised.
pip install entroly # MCP server + Rust engine
pip install entroly[proxy] # + HTTP proxy
pip install entroly[full] # everything
npm install -g entroly # WASM runtime, no Python needed
docker pull ghcr.io/juyterman1000/entroly:latest
entroly[native] still resolves — it is kept as a compatibility alias for
install instructions already published, and now installs the same thing as a
plain pip install entroly.
abi3 wheels are published for macOS universal2, Linux glibc and musl
(x86_64/aarch64), and Windows x64. On a platform with no published wheel the
install fails rather than silently degrading; build the core from source
(cd entroly-core && maturin develop --release) for those. If the engine is
missing at runtime, Entroly installs it from PyPI before measuring anything —
see the note under Install; ENTROLY_NO_SELF_HEAL=1
disables that, and the reported figure is then labelled unearned.
Single binary, no Python — a standalone Rust proxy that auto-detects Anthropic/OpenAI/Gemini and stays cache-aligned:
cd entroly/entroly-core && cargo build --release --bin entroly-rs --features proxy
./target/release/entroly-rs proxy --upstream https://api.anthropic.com
| Command | What it does |
|---|---|
entroly go |
One shot: detect IDE, wrap your agent, open the dashboard |
entroly wrap <agent> |
Wrap a specific coding agent (38 supported) |
entroly unwrap <agent> |
Remove Entroly’s persistent MCP registration without changing other tools |
entroly capabilities --json |
Report installed runtime surfaces offline without claiming provider connectivity |
entroly attach create/list/revoke |
Grant, inspect, or revoke scoped and expiring MCP access for Claude Code, Codex, or OpenClaw |
entroly proxy |
Start the HTTP proxy on localhost:9377 |
entroly as an MCP stdio command |
Start the installed Python MCP server when launched by an MCP client |
entroly serve |
Start through the Docker image by default; set ENTROLY_NO_DOCKER=1 for the installed Python runtime |
entroly daemon |
Supervise proxy + dashboard + MCP + file watcher |
entroly dashboard |
Open the live metrics dashboard |
entroly demo |
Before/after token + cost estimate on your repo |
entroly ingest |
Ingest documents into a local Context Receipt index |
entroly select |
Select context under budget and write a Context Receipt |
entroly context-commit |
Create or verify a replayable, recoverable context artifact |
entroly proof prepare/advance/inspect/run |
Run the durable, bounded proof-guided exact-recovery protocol |
entroly receipt |
Render a Context Receipt as a Markdown report |
entroly explain |
Explain why a chunk was selected or omitted |
entroly compress / entroly recover |
Compress one file with a receipt; recover the exact original from a digest |
entroly simulate |
Local no-LLM savings estimate with an explicit baseline |
entroly perf |
Local no-LLM savings and optimizer latency |
entroly value |
Evidence-classified provider value, local token reduction, and legacy history |
entroly benchmark |
Local comparison: Entroly vs raw context vs top-K |
entroly health |
Codebase health grade (A–F) |
entroly cache stats |
Persistent cross-session cache stats |
entroly ravs report |
Model-routing cost-savings report |
entroly witness |
Check an answer against supplied evidence |
entroly verify-claims |
Run the packaged self-test → JSON report |
Receipt-producing selection workflows record what was used, what was omitted, why, and what risks remain. This is useful for hard multi-document work such as contracts, policies, addenda, code reviews, and audit evidence where a bare top-k result is not enough.
entroly ingest ./docs
entroly select --query "Does this contract have a change-of-control clause?" --budget 8000
entroly receipt .entroly/receipts/cr_example.json
entroly audit .entroly/session_chain.json
entroly explain --why-omitted chk_example --receipt .entroly/receipts/cr_example.json
The receipt JSON includes selected chunks, omitted relevant chunks, ranking reasons, dependency links, source fingerprints, token ratio, warnings, and a reproducibility hash. It also includes a selection certificate: bounded frontiers record exact optimality for Entroly’s internal retrieval-score objective; larger frontiers record a conservative regret ceiling and a ranked recovery frontier instead of pretending to be optimal. The Markdown report is designed for human review before a compressed context is trusted.
An independent exhaustive oracle found pure rank-order packing suboptimal in 378 of 47,862 declared small-graph/budget cases. The certified selector improved all 378, regressed in zero, and matched the oracle in all 47,862—with zero partial dependency closures, budget violations, or invalid certificates. Inspect the machine-readable result. This is a synthetic internal-objective result, not an answer-quality or competitor claim.
Implementation notes:
entroly-core/src/context_receipts.rs) handles deterministic ingestion, BM25-style ranking, dependency scans, selection, and hashes when the native wheel is available.entroly/context_receipts/) provides CLI wiring and a pure-Python fallback for source checkouts.Examples:
| Area | Representative implementation |
|---|---|
| Index and reconciliation | entroly/auto_index.py, entroly/change_listener.py |
| Selection and compression | entroly/sdk.py, entroly-core/src/knapsack.rs, entroly/proxy_transform.py |
| Receipts and recovery | entroly/context_commit.py, entroly/ccr.py, entroly/provenance.py |
| Memory and task overlays | entroly/memory_os.py, entroly/task_dream.py |
| Skill lifecycle | entroly/skill_engine.py, entroly/evolution_daemon.py |
| Dreaming and world model | entroly/autotune.py, entroly/verified_dreaming.py |
| Security and attach | entroly/context_firewall.py, entroly/session_attach.py |
| MCP and proxy surfaces | entroly/server.py, entroly/proxy.py |
| Public trust gate | scripts/verify_public_trust.py, tests/test_public_trust.py |
The source and tests are authoritative when documentation drifts. If a public statement cannot be reproduced from a committed artifact or inspected code path, treat it as unverified and correct it.