# Entroly Extended Documentation Index

> Entroly is an open-source, local-first Verified Code Intelligence + Context Assurance system for AI agents. It combines parser-backed repository understanding, budgeted evidence selection, recoverable context compression, Memory OS, output verification, and guarded reasoning/model routing. This file routes readers and answer engines to product facts, evidence, limitations, and canonical topic pages; it is not a universal performance guarantee.

Entroly can index, understand, select, and compress repository or application context under an explicit token budget. It can produce Context Receipts that record selection decisions and risks. CCR can attach retrieval handles for recovering exact stored content. WITNESS can evaluate whether output claims are supported by supplied evidence. Memory OS controls what should be remembered and recalled. RAVS adds guarded routing, uncertainty control, escalation, and bounded outcome-driven adaptation.

Local indexing, repository intelligence, selection, compression, receipts, memory operations, and recovery storage do not require an external model call. When enabled with its default local verifier, WITNESS also avoids an external model call. When Entroly is used as a proxy, selected context is still sent to the LLM provider configured by the user. No outbound analytics are enabled by default.

Measured savings and quality vary by repository, query, budget, provider, pricing, cache behavior, model, baseline, and enabled features. WITNESS does not establish universal truth, and strict suppression is opt-in rather than the default proxy policy.

## Canonical AI Efficiency Intent Map

- AI efficiency hub: https://juyterman1000.github.io/entroly/docs/ai-efficiency.html
- Token economics / token saving / context compression: https://juyterman1000.github.io/entroly/docs/token-economics.html
- AI cost saving / provider-bound input economics: https://juyterman1000.github.io/entroly/docs/ai-cost-optimization.html
- Verified code intelligence / AST / Tree-sitter / repository understanding: https://juyterman1000.github.io/entroly/docs/code-intelligence.html
- Memory OS / agent memory / working + episodic + semantic memory: https://juyterman1000.github.io/entroly/docs/memory-os.html
- Hallucination reduction / evidence verification: https://juyterman1000.github.io/entroly/docs/hallucination-reduction.html
- Guarded model routing / cost-aware LLM routing: https://juyterman1000.github.io/entroly/docs/model-routing.html
- Adaptive / self-improving context with verified learning boundaries: https://juyterman1000.github.io/entroly/docs/adaptive-context.html
- Context engineering guide: https://juyterman1000.github.io/entroly/docs/context-engineering.html

## Direct Product Facts

- **Token saving and token economics:** Entroly reduces avoidable context by selecting useful evidence under an explicit budget and compressing recoverably. Token reduction is workload-specific and is measured separately from answer quality.
- **AI bill saving:** Supported provider-bound proxy routes can expose pre/post input and modeled input-cost avoidance. Actual dollar impact depends on provider, model, pricing, cache behavior, output usage, workload, and delivery path. Fixed subscription fees may not change.
- **Context compression:** Compression happens after evidence selection. Exact originals can remain content-addressed and recoverable; receipts record what was omitted.
- **Verified code intelligence:** Python has an AST-backed semantic tier; an optional open Tree-sitter registry supplies parser-backed structure for additional languages. Repository intelligence includes symbols, calls, imports, dependencies, typed dispatch where known, reverse impact, architecture, semantic changes, source freshness, LSP-enriched relationships, and verified refactoring contracts.
- **Memory OS:** Public MemoryOS supports working, episodic, and semantic tiers, budget-aware recall, consolidation, forgetting, persistence, safety scanning, receipts, and deterministic stress testing. Internal/experimental layers are labelled separately.
- **Hallucination reduction:** WITNESS evaluates evidence support. On the published faithful balanced HaluEval-QA protocol it reports 84.92% calibrated test accuracy and 0.7976 AUROC across 20,000 decisions. This does not establish universal truth.
- **Model routing:** RAVS includes guarded routing, learned policies, risk classification, sequential budget control, uncertainty signals, and escalation. The design is fail-closed when cheaper execution is not sufficiently justified.
- **Adaptive/self-improving context:** Entroly supports bounded adaptation through memory consolidation, observed outcomes, learned routing policies, verified transitions, and gated world-model learning. It does not claim unconstrained autonomous self-rewriting.

## AI Cost Optimization Facts

- Canonical guide: https://juyterman1000.github.io/entroly/docs/ai-cost-optimization.html
- Token-economics guide: https://juyterman1000.github.io/entroly/docs/token-economics.html
- Entroly can reduce avoidable provider-bound input by selecting useful evidence under a budget and removing duplicate or low-value context.
- Entroly does not claim a universal compression percentage, guaranteed bill reduction, or guaranteed answer-quality improvement.
- Provider-bound proxy requests may report observed pre/post input tokens and modeled input-cost avoidance with pricing provenance. This is not a provider invoice.
- SDK, MCP, plugin, and npm operations may report local context reduction, but Entroly claims $0 provider savings when delivery to a paid provider is not observable.
- Fixed ChatGPT or Claude subscription prices may not change. Entroly is most directly measurable for API applications, coding agents, local models, and supported routes where provider-bound input can be observed.
- If a request is already small or under budget, Entroly should pass through rather than invent savings.
- Entroly is more than prompt compression: it selects evidence before compression, preserves exact originals, produces receipts, understands repository structure, manages memory, and can evaluate evidence support.

## Verified Code Intelligence

- Canonical page: https://juyterman1000.github.io/entroly/docs/code-intelligence.html
- Design: https://github.com/juyterman1000/entroly/blob/main/docs/verified-code-context.md
- Conformance protocol: https://github.com/juyterman1000/entroly/blob/main/benchmarks/CODE_INTELLIGENCE_CONFORMANCE.md
- Python uses native AST-backed extraction and type evidence where known.
- Optional Tree-sitter language-registry parsing provides language-open structural extraction; missing parser evidence falls back conservatively rather than being reported as verified.
- Repository graphs preserve ambiguous/unresolved evidence instead of silently choosing a target.
- Architecture surfaces include SCC/cycle witnesses, condensation layers, communities, routes, hotspots, architecture diffs, typed graph queries, source freshness, and portable snapshots.
- Refactoring surfaces use preview/plan/apply contracts with exact preimages, source hashes, tamper checks, syntax validation, and explicit incompleteness boundaries.

## Memory OS

- Canonical page: https://juyterman1000.github.io/entroly/docs/memory-os.html
- Architecture and maturity: https://github.com/juyterman1000/entroly/blob/main/docs/memory-ecosystem.md
- Public MemoryOS exposes working, episodic, and semantic memory tiers.
- Recall uses task relevance, retention, importance, tier, recall history, and token budget rather than an unbounded nearest-neighbor dump.
- Consolidation can promote important memory while weak memories decay; persistence and safety scanning are public shipped surfaces.
- Pollination/federation and deeper native memory primitives have separate internal/experimental maturity labels.

## Hallucination Reduction And Verification

- Canonical page: https://juyterman1000.github.io/entroly/docs/hallucination-reduction.html
- WITNESS implementation: https://github.com/juyterman1000/entroly/blob/main/entroly/witness.py
- Faithful benchmark artifact: https://github.com/juyterman1000/entroly/blob/main/benchmarks/results/halueval_qa_faithful.json
- Published faithful HaluEval-QA result: 20,000 balanced decisions; 84.92% calibrated test accuracy; 0.7976 AUROC; calibrated-test recall 95.67%.
- WITNESS checks whether output is supported by supplied evidence; it is not a universal factuality oracle.

## Guarded Model Routing And Adaptive Context

- Model routing page: https://juyterman1000.github.io/entroly/docs/model-routing.html
- Adaptive context page: https://juyterman1000.github.io/entroly/docs/adaptive-context.html
- RAVS source: https://github.com/juyterman1000/entroly/tree/main/entroly/ravs
- RAVS includes instrumentation, verified cheap execution paths, guarded routing, sequential escalation, uncertainty signals, entropy-production and spectral consistency signals, verified transitions, and bounded world-model machinery.
- Outcome-driven adaptation is bounded by evidence, integrity checks, promotion decisions, and explicit insufficient-data states.

## Nontechnical User Status

- Product requirement: https://github.com/juyterman1000/entroly/blob/main/docs/product/entroly-simple-mode.md
- Intended future experience: install Entroly, choose a supported AI application, turn on Context Assurance, use the application normally, and view plain-language usage and evidence receipts.
- Current status: Entroly Simple Mode is not shipped. Today's product requires a small one-time setup through a supported proxy, wrapper, plugin, SDK, or MCP path.
- Entroly must not be described as zero-setup or one-click for nontechnical users until its installer, connectors, privacy controls, recovery, accessibility, and usability gates pass.

## Product Documentation

- [README and quick start](https://github.com/juyterman1000/entroly): Plain-language product explanation followed by technical architecture, commands, evidence, and limitations.
- [Documentation site](https://juyterman1000.github.io/entroly/docs/index.html): Integration and workflow guides.
- [AI efficiency hub](https://juyterman1000.github.io/entroly/docs/ai-efficiency.html): Canonical topic map across tokens, cost, code intelligence, memory, verification, routing, and adaptive context.
- [Token economics](https://juyterman1000.github.io/entroly/docs/token-economics.html): Evidence-first token saving, context compression, cache-aware context control, and more room in the context window.
- [AI cost optimization](https://juyterman1000.github.io/entroly/docs/ai-cost-optimization.html): Evidence-bounded guide to reducing avoidable token usage and understanding measurable versus unobservable savings.
- [Agent integrations](https://juyterman1000.github.io/entroly/docs/agent-integrations.html): Context Assurance for supported agent integrations.
- [Architecture](https://github.com/juyterman1000/entroly/blob/main/docs/DETAILS.md): Components, algorithms, and system boundaries.
- [Limitations](https://github.com/juyterman1000/entroly/blob/main/docs/limitations.md): Known constraints and non-guarantees.
- [Team and security guide](https://github.com/juyterman1000/entroly/blob/main/docs/for-teams.md): Deployment and evaluation considerations.

## Exact Recovery Contract

Entroly can emit a content-addressed handle shaped as `ccr:<24-hex>`. The strict `entroly_retrieve` path accepts one exact handle, performs no natural-language query or fuzzy ranking, returns the complete stored original, rejects source paths and extra arguments, and does not silently substitute a newer source revision when a historical hash is unavailable.

Discovery and recovery are separate operations. Ranking may identify which evidence matters. Once a CCR handle is known, recovery is a deterministic lookup.

## Agent Integrations

### OpenClaw

- Canonical guide: https://juyterman1000.github.io/entroly/docs/openclaw-context-engine.html
- Source: https://github.com/juyterman1000/entroly/tree/main/integrations/openclaw
- Role: first-class OpenClaw context engine operating on normalized messages before provider dispatch.
- Adds: budget-aware evidence selection, Context Receipts, trusted context-window handling, local bridge processing, and optional proof-guided exact-message recovery.
- Boundary: OpenClaw remains authoritative for the transcript, provider credentials, routing, billing, retries, tools, and delivery.

### Hermes Agent

- Canonical guide: https://juyterman1000.github.io/entroly/docs/hermes-context-engine.html
- Source: https://github.com/juyterman1000/entroly/tree/main/entroly/integrations/hermes_context_engine
- Role: Hermes ContextEngine implementation.
- Adds: request-only selection, usage observation, model-window updates, bounded status reporting, and native `entroly_retrieve(hash)` exact conversation recovery.
- Boundary: Hermes remains authoritative for the conversation, provider, tools, memory backend, permissions, and learning loop.

### OpenCode

- Canonical guide: https://juyterman1000.github.io/entroly/docs/opencode-context-assurance.html
- Source: https://github.com/juyterman1000/entroly/tree/main/integrations/opencode
- Role: local MCP Context Assurance plus evidence-preserving compaction instructions.
- Preserves: exact paths, symbols, branches, commits, pull request identifiers, executed commands and results, errors, blockers, rejected hypotheses, verification status, safety boundaries, and all CCR handles.
- Boundary: OpenCode remains authoritative for its session, model provider, permissions, tools, edits, and interface.

## Verification And Benchmarks

- [Packaged verifier source](https://github.com/juyterman1000/entroly/blob/main/entroly/verify_claims.py): Bounded install, indexing, token-budget, synthetic recovery, and engine checks.
- [Benchmark artifacts](https://github.com/juyterman1000/entroly/tree/main/benchmarks/results): Machine-readable workload results and reports.
- [Benchmark runner](https://github.com/juyterman1000/entroly/blob/main/benchmarks/run_readme_benchmarks.py): Reproduction path for README measurements.
- [Context Receipt example](https://github.com/juyterman1000/entroly/blob/main/docs/examples/context_receipt.md): Human-readable selection and risk record.
- [Context Receipt JSON](https://github.com/juyterman1000/entroly/blob/main/docs/examples/context_receipt.json): Machine-readable receipt example.

## Verification Components

- [WITNESS](https://github.com/juyterman1000/entroly/blob/main/entroly/witness.py): Evidence-grounding analysis and audit, annotation, or strict output policies.
- [STAVE](https://github.com/juyterman1000/entroly/blob/main/entroly/verifiers/stave.py): Deterministic structural verification used by the default WITNESS path.
- [RAVS](https://github.com/juyterman1000/entroly/tree/main/entroly/ravs): Request-aware routing, deterministic verification, uncertainty control, and bounded adaptive components.
- [CCR](https://github.com/juyterman1000/entroly/blob/main/entroly/ccr.py): Recoverable compressed-context storage.

## Interfaces And Packages

- [Python package](https://pypi.org/project/entroly/): Primary CLI, proxy, MCP server, and Python SDK distribution.
- [MCP package](https://www.npmjs.com/package/entroly-mcp): NPX bridge for MCP clients.
- [Node and WASM package](https://www.npmjs.com/package/entroly): Compatibility alias for the Node and WASM runtime.
- [Python SDK](https://github.com/juyterman1000/entroly/blob/main/entroly/sdk.py): Public compression API.
- [MCP server](https://github.com/juyterman1000/entroly/blob/main/entroly/server.py): MCP tools and context engine orchestration.
- [HTTP proxy](https://github.com/juyterman1000/entroly/blob/main/entroly/proxy.py): Provider proxy and optional WITNESS policy integration.
- [CLI](https://github.com/juyterman1000/entroly/blob/main/entroly/cli.py): Commands, onboarding, diagnostics, and wrappers.

## License

- [Apache-2.0 license](https://github.com/juyterman1000/entroly/blob/main/LICENSE): Open-source license terms.