Store a context fragment with automatic dedup and entropy scoring.

Fragments are fingerprinted via SimHash for O(1) duplicate detection. Each fragment's information density is scored using Shannon entropy. Duplicates are automatically merged with salience boosting.

Args: content: The text content to store (code, tool output, etc.) source: Origin label (e.g., 'file:utils.py', 'tool:grep') token_count: Token count (auto-estimated if 0) is_pinned: If True, prioritize exact inclusion within the pinned budget reserve; excess pinned content remains a high-priority compressed candidate so the total token ceiling stays honest.

Select the mathematically optimal context subset for a token budget.

Uses 0/1 Knapsack dynamic programming to maximize relevance within the budget. Scores fragments on four dimensions: recency (Ebbinghaus decay), access frequency (spaced repetition), semantic similarity (SimHash), and information density (Shannon entropy).

QUERY REFINEMENT: Vague queries like "fix the bug" or "add feature" are automatically expanded into precise master prompts using the files already in memory. This improves context selection accuracy and reduces hallucination from selecting wrong files. The response includes query_refinement.refined_query so you can see what drove selection.

Output is ordered for optimal LLM attention: pinned/critical first, high-dependency foundation files early, then by relevance.

This is the core tool — call it before sending context to the LLM.

Args: token_budget: Maximum tokens allowed (default: 128K) query: Current query/task for semantic relevance scoring (can be vague)

Retrieve exact source content omitted by compressed context.

Use the retrieval handle attached to a skeleton/reference fragment for exact historical recovery. A visible source path also works and lazily resolves the latest ingested version. With no argument, lists currently materialized CCR entries without returning their content.

Args: source_or_handle: Source path or content-addressed ccr:... handle.

Semantic recall of the most relevant stored fragments.

Uses SimHash fingerprint distance + multi-dimensional scoring with feedback loop (fragments that previously led to successful outputs are boosted).

Args: query: The search query top_k: Number of results to return

Record whether selected fragments led to a successful output.

This feeds the reinforcement learning loop: fragments that contribute to successful outputs get boosted in future selections, while unhelpful fragments get suppressed.

Args: fragment_ids: Comma-separated fragment IDs success: True if output was good, False if bad

NOTE on RAVS v1: this tool's success flag is also recorded into the RAVS event log as an agent_self_report event with strength=weak and include_in_default_training=False. Default labeling rules ignore it. Use the structured record_test_result / record_command_exit / record_ci_result tools for honest signals you want offline evaluation to actually train against.

Record that tests RAN and either passed or failed for a request.

This is a STRONG signal — distinct from record_outcome which is the agent's self-report. Call this when actual test execution produced a real pass/fail outcome.

Args: request_id: the trace_id from the optimize_context call passed: True if all tests passed, False if any failed suite: optional name of the test suite (e.g. "pytest", "cargo test") details: optional short summary of what was tested

Record the exit code of a command that was generated and executed.

STRONG signal: a real subprocess produced a real exit code. Convention: exit_code == 0 → "success", anything else → "failure".

Args: request_id: the trace_id from the optimize_context call exit_code: subprocess exit code; 0 = success command: optional short representation of what was run

Record CI pipeline pass/fail status for a request.

STRONG signal: CI is independent infrastructure that ran the change and produced a verdict. The honest top of the signal hierarchy.

Args: request_id: the trace_id from the optimize_context call passed: True if CI green, False if any required check failed pipeline: e.g. "github_actions", "gitlab_ci", "buildkite" url: optional link to the CI run

Record whether the user accepted, reverted, or retried an AI edit.

STRONG signal: user behavior directly indicates whether the generated code was successful.

Args: request_id: the trace_id from the optimize_context call outcome: "accepted", "reverted", or "retried" files_modified: number of files touched by the edit

Explain why each fragment was included or excluded in the last optimization.

Shows per-fragment scoring breakdowns with all dimensions visible: recency, frequency, semantic, entropy, feedback multiplier, dependency boost, criticality, and composite score.

Also shows context sufficiency (what % of referenced symbols have definitions included) and any exploration swaps.

Call this after optimize_context to understand selection decisions.

Create a Context Receipt from supplied documents.

documents_json may be:

• a JSON object mapping source path to text

• a JSON array of [source_path, text] pairs

• a JSON array of objects with source_path/text or source/content keys

The receipt records selected context, omitted relevant context, dependency links, fingerprints, token ratio, warnings, and risk controls. It does not call an LLM.

Set recoverable=True to also persist a project-local recovery bundle, so any omitted chunk can later be recovered byte-exact and verified via recover_receipt_omission.

Create a Context Receipt from a local document file or directory.

Supports text-like documents currently handled by the local receipt ingester (.md, .txt, .rst). The result is deterministic and local.

Render a Context Receipt JSON artifact as a Markdown report.

Explain why a chunk was omitted from a Context Receipt.

Recover the full text of context a Context Receipt omitted.

Receipts explain what was dropped; this hands back the exact content, byte-for-byte. Works on receipts created with recoverable=True — the recovery bundle is read from the local store. Pass chunk_id to recover one chunk, or leave it empty to recover everything that was omitted.

Each result carries verified=true only when the returned text is provably identical to what was omitted (matched against the chunk's recorded fingerprint and a storage-integrity hash) — never a guess.

Save current state to disk for crash recovery and session resume.

Checkpoints include all fragments, dedup index, co-access patterns, and custom metadata. Stored as gzipped JSON (~50-200 KB).

Args: task_description: What the agent is working on current_step: Where in the task it currently is

Resume from the latest checkpoint.

Restores all context fragments, dedup index, co-access patterns, and custom metadata from the most recent checkpoint.

Predict and pre-load context that will likely be needed next.

Combines static analysis (imports, callees, test files) with learned co-access patterns to predict what the agent will need.

Args: file_path: The file currently being accessed source_content: The source code content (for static analysis) language: Programming language (python, typescript, rust)

Get comprehensive session statistics.

Shows token savings, duplicate detection counts, entropy distribution, dependency graph stats, checkpoint status, and cost estimates.

Show the real, live value Entroly is providing to YOUR session right now.

Pulls from actual engine state — not synthetic data. Shows: Money saved: exact $ amounts from token optimization Performance: sub-millisecond selection speed vs API latency Bloat prevention: context compression ratio and memory footprint Selection quality: per-fragment scoring and context sufficiency Safety: duplicates caught, stale fragments filtered

Call this anytime to see exactly what Entroly is doing for you.

Scan code content for security vulnerabilities (SAST analysis).

Uses a 55-rule engine with taint-flow simulation and CVSS-inspired scoring. Detects hardcoded secrets, SQL injection, path traversal, command injection, insecure cryptography, unsafe deserialization, XSS, and authentication misconfigurations.

Args: content: The source code to scan. source: File path / identifier (used for language detection and confidence scoring). E.g. "auth/login.py".

Returns JSON with: - findings: [{rule_id, cwe, severity, line_number, description, fix, confidence, taint_flow}] - risk_score: CVSS-inspired aggregate [0.0, 10.0] - critical_count, high_count, medium_count, low_count - top_fix: most impactful remediation action

Generate a session-wide security audit across all ingested fragments.

Scans every fragment in the current session and returns an aggregated report showing: which fragments are most vulnerable, overall risk posture, finding distribution by category, and the single most important fix.

Returns JSON with: - fragments_scanned, fragments_with_findings - critical_total, high_total, max_risk_score - most_vulnerable_fragment (fragment_id) - findings_by_category: {category: count} - vulnerable_fragments: sorted list by risk_score

Analyze the health of the ingested codebase.

Runs 5 analysis passes over all fragments in the current session:

1. Clone Detection — SimHash pairwise scan for Type-1/2/3 code clones

2. Dead Symbol Analysis — defined but never referenced symbols

3. God File Detection — files with > μ+2σ reverse dependencies

4. Architecture Violation Detection — cross-layer imports

5. Naming Convention Analysis — Python/Rust/React convention breaks

Returns a JSON HealthReport with: - code_health_score [0–100] and health_grade (A/B/C/D/F) - Per-dimension scores: duplication, dead_code, coupling, arch, naming - clone_pairs, dead_symbols, god_files, arch_violations, naming_issues - summary (human-readable) and top_recommendation (most impactful action)

Ingest an architecture or flow diagram into the context memory.

Converts Mermaid, PlantUML, DOT/Graphviz, or informal diagram text into a structured semantic fragment capturing nodes, edges, and relationships. The result is stored as a normal context fragment and is retrievable by optimize_context and recall_relevant.

Args: diagram_text: Raw diagram source (Mermaid/PlantUML/DOT/text description). source: Identifier (e.g., 'arch_overview.mmd', 'db_schema.puml'). diagram_type: 'mermaid', 'plantuml', 'dot', 'text', or 'auto' (default).

Returns JSON with ingestion result (same as remember_fragment).

Ingest a voice/meeting transcript into the context memory.

Converts pre-transcribed text (from Whisper, AssemblyAI, etc.) into a structured fragment capturing decisions, action items, open questions, technical vocabulary, and key discussion excerpts.

Args: transcript: The full transcript text. source: Identifier (e.g., 'design_meeting_2026-03-07.txt').

Returns JSON with ingestion result plus: - decisions, actions, open_questions (counts) - tech_terms_identified

Ingest a code diff/patch into the context memory.

Converts a unified diff (git diff output) into a structured change summary: intent classification (bug-fix/feature/refactor), symbols changed, files modified, and line delta. Particularly useful for understanding recent changes and their architectural impact.

Args: diff_text: Raw unified diff text (git diff output). source: Identifier (e.g., 'pr_42_auth_refactor.diff'). commit_message: Optional commit message for better intent classification.

Returns JSON with ingestion result plus: - intent: bug-fix/feature/refactor/test/security/performance - files_changed, added_lines, removed_lines - symbols_changed: functions/classes modified

Route a query through the CogOps Epistemic Ingress Controller.

Inspects 4 signals (intent, belief coverage, freshness, risk) and selects one of 5 canonical flows:

① Fast Answer: Belief → Action (fresh, verified, low-risk) ② Verify Before Answer: Belief → Verification → Action (stale/risky) ③ Compile On Demand: Truth → Belief → Verification → Action (no beliefs) ④ Change-Driven: Event → Truth → Belief → ... (PR/commit/incident) ⑤ Self-Improvement: Misses → Evolution → Belief (repeated failures)

Call this BEFORE optimize_context to understand how the system should approach your query. Existing tools work exactly as before.

Args: query: The user query or event description is_event: True if this is a change-driven event (PR, commit, etc.) event_type: Type of event (pr, commit, release, incident, scheduled)

Show the current state of the CogOps Knowledge Vault.

Initializes the vault directory structure if needed, then returns a coverage index: total beliefs, verification status, confidence distribution, and routing statistics.

The vault is the persistent Living Exocortex — the system's machine-auditable understanding of your codebase.

Write a belief artifact to the CogOps Knowledge Vault.

Beliefs are durable system understanding — what Entroly thinks the codebase is. Each belief carries machine-auditable frontmatter: claim_id, entity, status, confidence, sources, last_checked.

Args: entity: The system entity this belief is about (e.g., 'auth::token_rotation') title: Human-readable title body: The belief content (markdown) confidence: Machine-assigned confidence 0.0-1.0 (default: 0.7) status: observed|inferred|verified|stale|hypothesis (default: inferred) sources: Comma-separated source paths (e.g., 'src/auth.rs:142,src/token.rs:58') derived_from: Comma-separated component names that produced this belief

Query the CogOps Knowledge Vault for existing beliefs.

Use this to check what the system already knows before compiling new understanding. Supports lookup by entity name or listing all.

Args: entity: Entity name to look up (fuzzy match) list_all: If True, return all beliefs with frontmatter summary

Write a task output or report to the CogOps Knowledge Vault.

Action artifacts are developer-facing outputs: PR briefs, answers, architecture diagrams, slide decks, task reports. They live in actions/ and are timestamped for traceability.

Args: title: Title of the output content: Full markdown content action_type: Type tag (report, pr_brief, answer, diagram, context_pack)

Compile source code into belief artifacts (Truth → Belief pipeline).

Scans a directory for source files (.py, .rs, .ts, .js), extracts code entities (classes, functions, structs, traits, imports), resolves cross-file dependencies, and writes belief artifacts to the vault with full frontmatter (claim_id, entity, status, confidence, sources, last_checked, derived_from).

Args: directory: Path to scan. Defaults to the project root. max_files: Maximum files to process (default: 200)

Run a full verification pass on all beliefs in the vault.

Checks for:

• Staleness (beliefs past their freshness window)

• Contradictions (conflicting claims about the same entity)

• Confidence divergence between same-entity beliefs

• Low confidence scores

Writes verification artifacts to vault/verification/.

Analyze the blast radius of file changes on existing beliefs.

Given a list of changed files, determines which beliefs need re-verification, which may be invalidated, and the overall risk level (low/medium/high).

Args: changed_files: Comma-separated list of changed file paths

Process a code change through the Change-Driven pipeline (Flow ④).

Full pipeline: Diff → ChangeSet → Review → Blast Radius → Vault

Classifies intent (bugfix/feature/refactor/test/security/performance), runs code review (hardcoded secrets, TODOs, broad exceptions, unsafe), computes belief impact, and returns a structured PR brief.

Args: diff_text: Raw unified diff text (git diff output) commit_message: Optional commit message for intent classification pr_title: Optional PR title

Execute a full canonical epistemic flow end-to-end.

Routes the query through the Epistemic Ingress Controller (4 signals: intent, belief coverage, freshness, risk), then chains the appropriate pipeline steps automatically:

① Fast Answer: Belief → Action ② Verify Before Answer: Belief → Verification → Action ③ Compile On Demand: Truth → Belief → Verification → Action ④ Change-Driven: Event → Truth → Belief → Verification → Action ⑤ Self-Improvement: Misses → Verification → Evolution → Belief

Args: query: The user query or event description diff_text: Raw diff for change-driven flows (Flow ④) is_event: True if this is a change-driven event event_type: Type of event (pr, commit, release, incident, scheduled)

Create a new skill from a capability gap (Evolution layer).

When the system repeatedly fails on a topic, this generates a full skill package in vault/evolution/skills//:

• SKILL.md — procedure/SOP

• tool.py — executable Python tool

• metrics.json — fitness tracking

• tests/test_cases.json — regression tests

Args: entity_key: The entity this skill handles (e.g., 'protobuf_analysis') failing_queries: Pipe-separated list of failing queries intent: The intent class for this skill

Manage the CogOps skill lifecycle (Evolution layer).

Actions:

• list: Show all skills with status, fitness, and run counts

• benchmark: Run test cases and compute fitness score (0.0-1.0)

• promote: Promote (fitness >= 0.7) or prune (fitness <= 0.3)

Args: action: list | benchmark | promote skill_id: Required for benchmark/promote actions

Find source files with no corresponding belief in the vault.

Scans a directory for source files (.py, .rs, .ts, .js) and checks which ones have no belief artifact. Useful for identifying blind spots before running compile_beliefs.

Args: directory: Path to scan. Defaults to the project root.

Mark beliefs as stale after file changes (Flow ④ doc-refresh).

Given changed files, finds related beliefs and marks their status as 'stale' so the next verify_beliefs pass will flag them for re-compilation.

Args: changed_files: Comma-separated list of changed file paths

Synchronize workspace file changes into the belief and verification layers.

Detects new, modified, and deleted source files, marks affected beliefs stale, recompiles changed files into fresh beliefs, runs a verification pass, and writes a sync report into actions/.

Return the canonical Entroly file map across the Python, Rust core, and WASM repos.

Use this to understand ownership boundaries and where logic currently lives. Supported formats: markdown, json.

Start a background workspace listener that continuously feeds repo changes into CogOps.

This is the long-running change-driven bridge from repo activity into Belief CI.

Full-text search across all belief artifacts in the vault.

Uses TF-IDF ranking with entity-name boosting (3x) to find the most relevant beliefs. Much cheaper than listing all beliefs — returns only the top matches with excerpts.

Args: query: Natural language search query (e.g., "how does knapsack work?") top_k: Maximum number of results to return (default: 5)

Compile markdown documentation files into belief artifacts.

Ingests project-level docs (README.md, ARCHITECTURE.md, docs/, CONTRIBUTING.md, etc.) into the vault as documentation beliefs with confidence 0.80 (human-authored > machine-inferred code beliefs).

Args: directory: Project root to scan. Defaults to the project root. max_files: Maximum doc files to process (default: 50)

Export vault beliefs as JSONL training data for LLM finetuning.

Generates instruction-following pairs from compiled beliefs: question about entity → belief body as answer. Filters out stale and low-confidence beliefs. Output is OpenAI-compatible JSONL.

Uses PRISM scoring dimensions for quality-weighted sampling: only beliefs with confidence >= 0.5 and non-stale status are included in the training set.

Args: output_path: Path to write JSONL file (default: training_data.jsonl) format: Output format, currently only 'jsonl' supported

Verify that LLM-generated code is grounded in the provided context.

Uses BIPT (Byte-level Information Provenance Tracer) to measure how much of each identifier in the generated code originates from the context. Returns an Identifier Provenance Deficit (IPD) score:

IPD = 0.0 → fully grounded (all identifiers come from context) IPD = 1.0 → fully invented (no identifiers match context)

Use this after an LLM generates code to check for hallucinated APIs, invented function names, or fabricated imports before accepting output.

Args: code: The LLM-generated code to verify context: The repository context that was provided to the LLM

Verify LLM-generated code and suggest repairs for hallucinations.

Combines BIPT verification with rejection analysis to identify hallucinated identifiers and suggest which real APIs/symbols from the context should be used instead.

This is a single-shot verification + feedback tool — it does NOT call an LLM. For the full repair loop (FORGE), use the Python SDK: from entroly.verifiers import forge_loop

Args: prompt: The original user request that generated the code code: The LLM-generated code to verify context: The repository context provided to the LLM

Verify an AI-generated response for hallucination using the 4-signal fusion cascade.

Runs the same hallucination detection pipeline as the proxy (WITNESS + ECE + EPR + Spectral) but callable directly from any MCP client. Use this after generating a response to check for factual claims that aren't grounded in the provided context.

Returns a structured verification report with:

• fused_risk: Combined hallucination probability [0.0 = safe, 1.0 = hallucinated]

• verdict: "pass", "warn", or "flag"

• per-signal scores (entity_coverage_gap, ece_curvature, epr_rate, spectral_consistency)

• flagged_claims: List of specific claims that may be hallucinated

• recommendation: Suggested action (accept / review / reject)

All computation is 100% local — zero LLM calls, zero API calls.

Args: response: The AI-generated text to verify context: The source context that was provided to the AI prompt: The original user prompt/query (helps calibrate verification)

Verify a single claim against evidence using the EICV pipeline.

Returns a structured EICVCertificate with:

• phi: epistemic support density [0=fully hallucinated, 1=fully grounded]

• hallucination_score: 1 - phi

• decision: "supported" | "abstain" | "hallucinated"

• layer_scores: per-layer breakdown (T(G), NLI, RNR, gamma, H_sem)

• n_claim_atoms / n_ev_atoms: structural decomposition counts

• unsupported_fraction: fraction of claim atoms with no support

• contradiction_fraction: fraction with active contradiction

• elapsed_ms: per-call latency

Computed locally with no neural model and no LLM calls. Accuracy on public benchmarks (FEVER, SQuAD v2, HaluEval-QA) is documented in benchmarks/results/. False-positive and false-negative rates are non-zero — review those JSONs before relying on the output for compliance-sensitive decisions.

Args: evidence: The grounding context (retrieved passages, source material) claim: The single claim to verify against evidence profile: "rag" | "qa" | "summarization" | "dialogue" | "fact_check" | "default". Selects the abstain decision band.

Verify an LLM response and optionally rewrite hallucinated claims.

Returns the (possibly rewritten) output and per-claim audit trail. Computation is fully local — no neural model, no LLM calls.

Modes: audit — analyze only; no rewrite. Use for telemetry/dashboards. annotate — keep output; append verification warnings at end. strict — graduated 4-action policy: supported → PASS (no change) abstain → HEDGE (append "[unverified]") hallucinated → SUPPRESS (remove claim sentence)

Profiles tune the abstain band: rag (default) — strict, for retrieval-augmented generation qa — moderate-strict for QA outputs summarization — tolerant of paraphrase dialogue — broader abstain band fact_check — hardest (FEVER-like setting)

Returns SuppressionResult with:

• rewritten_output: the (possibly modified) response

• n_claims / n_supported / n_abstained / n_hallucinated

• suppressed_count / warned_count

• hallucination_rate: 0..1 (n_hallucinated / n_claims)

• certificates: list of per-claim EICVCertificate

• latency_ms

Accuracy on public datasets is documented in benchmarks/results/. False-positive and false-negative rates are non-zero — a truthful claim can be wrongly suppressed, and a false claim can pass through. Audit-mode is the safe default for compliance- sensitive applications.

Args: context: The grounding evidence the LLM was supposed to use output: The LLM's response text to verify and possibly rewrite profile: Suppression profile (default "rag") mode: "audit" | "annotate" | "strict" (default "strict")

Read a file with automatic resolution optimization.

Instead of choosing between full/map/signatures mode, SRP automatically selects the optimal resolution for each code block based on query relevance and token budget:

• Blocks matching the query → FULL (complete source)

• Related blocks → MEDIUM (signature + docstring)

• Peripheral blocks → LOW (name only)

• Irrelevant blocks → SKIP (omitted)

This saves 40-70% tokens vs full-file reads while preserving all query-relevant detail.

Args: file_path: Path to the file to read query: What you're looking for (improves relevance scoring) budget: Target token budget for the output (default: 1000)

Scan content for prompt injection attacks and security threats.

Detects:

• Direct instruction overrides ("ignore previous instructions")

• Role reassignment attempts ("you are now a...")

• Unicode steganography (zero-width chars, directional overrides)

• Base64-encoded instruction payloads

• Repetition flooding (context window domination)

• XML/tag-based role spoofing

Use this to verify untrusted content before including it in prompts.

Args: content: The text content to scan source: Source identifier for threat location reporting