DOCSEARCHbyAlgolia
Submit Docs

OMNI Semantic Signal Engine

repository·main·Indexed 43 days ago

https://github.com/fajarhide/omni

A context-optimization engine for AI agents that reduces token usage and noise by distilling command outputs and deduplicating content. It features a local SQLite RewindStore for byte-for-byte retrieval, supports multiple host tiers (including OpenClaw and MCP), and ensures data integrity for structured formats like JSON, YAML, CSV, and TSV. Version 0.7.9.

Tokens
78.4K
Snippets
288
Records
442
Agent score
55%

What's inside OMNI

  1. What is OMNI and how does it work

    main

    OMNI is a small program that edits the output read by an AI agent before the agent sees it. It operates by hooking into the agent host's tool execution lifecycle (e.g., using the PostToolUse hook in Claude Code).

    How it sits in the workflow

    OMNI uses two hooks around a tool call:

    1. Pre-hook: Before the command runs, OMNI passes the matching command to itself.
    2. Post-hook: After the tool finishes, OMNI distills the output before the agent reads it. All discarded raw data is archived in a local SQLite database for later retrieval via omni retrieve.

    Core Processing Pipeline

    When a command is executed, OMNI performs these four steps in order (each step can decide to do nothing):

    1. Refuse: If the output is structured data that requires parsing (JSON, YAML, base64, terraform plan, etc.), it is returned untouched to ensure format safety.
    2. Filter: Specialized "distillers" identify and preserve important verdicts (like test successes or build failures) while discarding boilerplate. There are 12 distillers covering build, test, git, cloud, databases, JS/TS tools, etc.
    3. Fold Repeated Lines: Long sequences of nearly identical lines are collapsed into a single line indicating the count.
    4. Fold Seen Lines: Lines previously shown to the agent are replaced with a handle (using the ledger concept) instead of being repeated.

    Key Constraints

    • Not a compressor: It prioritizes actionable output for the agent and verifiable numbers for humans over pure size reduction.
    • Not a summarizer: It does not use LLM inference; it operates within millisecond time budgets using deterministic logic.
    • Safety First: If a distiller cannot confidently parse the input, it must return None so the raw bytes are passed through. OMNI prioritizes accuracy over token savings.

  2. Understand OMNI Filtering Effects in Hermes

    main

    OMNI's filtering and compression impact different types of command outputs differently:

    | Output Type | OMNI Effect | |---|---|\n| npm install, cargo build, docker build | Large (70%+): Filters out progress bars, cache hits, and pure hash layer noise. | | run test | Large: Preserves verdicts and failures; discards ok lines. | | File reading | Zero: No filtering applied; many ledger entries created upon re-reading. | | kubectl -o json, terraform plan | Zero: Structured payloads pass through untouched by design. | | Short commands | Zero/Negative: Overhead of markers may exceed savings. |

  3. Understanding OMNI's performance overhead

    main
    OMNI introduces a measurable latency that grows with your command history rather than the size of the payload. For example, a small command like git status might take ~21ms against a fresh database, but ~61ms against a 205 MB database. Users should budget for this latency in their terminal workflows.

  4. How the Score stage assigns relevance tiers

    main

    The Score stage assigns a relevance tier to every line. This tiering is a pure function of the text, the command that produced it, and the existing session history. This happens before the Distill stage, so if a distiller is behaving unexpectedly, you should first check if the segment's tier has already influenced the outcome.

    tierweightwhat lands here
    Critical1.0errors, failures, the verdict line, anything naming a file and a line number
    Important0.7warnings, counts, state that changed
    Noise0.1progress, timing, decoration, repeated ceremony

  5. Understand OMNI's effect on different command outputs in Hermes

    main

    OMNI's signal engine processes terminal output differently depending on the command type:

    | Output Type | OMNI's Effect | |---|---|\n| npm install, cargo build, docker build | Large outputs (70%+). Progress, cache hits, and layer hashes are treated as ceremony and distilled. | | Test runs | Large outputs. The verdict and failures are preserved; ok lines are stripped. | | File reads | No effect from filters; significant effect from the ledger on re-reads. | | kubectl -o json, terraform plans | No effect. Structured payloads pass through untouched. | | Short commands | No effect, or slightly negative due to marker overhead. |

    Using MCP Tools for Control

    Hermes uses MCP tools to manage this output. By default, Hermes (as a Full-tier host) advertises omni_retrieve and omni_explain_savings. To access the full suite of tools, set the environment variable OMNI_MCP_TOOLS=all.

    • omni_explain_savings: See the actual cost of a recent command.
    • omni_retrieve: Get folded/compressed content back.
    • omni_budget: View session token usage.

  6. Understand OMNI savings metrics and units

    main

    OMNI reports savings in bytes, not tokens.

    Key Concepts:

    • Units: All absolute figures are byte totals. If you are consuming JSON output, use the bytes_saved field (formerly tokens_saved).
    • Engines:
      • folded: Savings from the ledger engine.
      • distilled: Savings from the distiller engine.
      • left alone: Calls that passed through by design (counted as 0 bytes saved).
    • Accuracy Warning: A high percentage reduction does not always mean high quality; verify results with omni diff on actual commands. A low aggregate is often normal because many calls (like structured payloads or failed commands) are passed through untouched for safety.
    • Agent Filtering: When analyzing data, be aware that terminal agent rows represent TTY bytes that never reached a model. omni stats excludes these by default, but they may appear if querying the database directly.

  7. Understand the OMNI processing pipeline

    main

    Every payload processed by OMNI follows a fixed sequence of stages. The pipeline is designed to prioritize correctness and data integrity over compression. If a stage fails to process or understand a payload, it must return the original bytes rather than inventing information.

    The pipeline stages are: Read → Guard → Score → Distill → [Collapse] → Ledger → Route → Persist

    Note that Collapse is a fallback mechanism that only runs if the Distill stage fails to meet the guardrail requirements.

    Read → Guard → Score → Distill → [Collapse] → Ledger → Route → Persist

  8. Understand OMNI benchmark metrics: Available vs Captured

    main

    When reviewing OMNI benchmark tables, distinguish between these two key metrics:

    • available: The theoretical ceiling of savings. This represents the share of data that the ledger could potentially substitute because it has already delivered those lines.
    • captured: The actual share of the available data that OMNI successfully folded/substituted. This is considered the more stable metric that survives changes in workload.

    Example relationship: If available is 15.6% and captured is 10.7%, OMNI has successfully captured a significant portion of the potential savings identified by the ledger.

  9. When OMNI does not apply markers

    main

    OMNI will pass output through verbatim without applying any markers or folding in the following scenarios:

    • The payload is structured data: JSON, YAML, CSV, or TSV.
    • The command failed: Non-zero exit codes pass through as-is.
    • There is no noise to remove: For example, a kubectl get pods table where every row is unique data.
    • The output is too short to justify the overhead of a marker.

  10. How OMNI scoring and relevance levels work

    main

    Every line of input is assigned a relevance level based on its content, the command that generated it, and the current session history. Scoring happens before the Distill stage, meaning the score often determines how a distiller behaves. If a distiller is producing unexpected results, check the segment's score first.

    LevelWeightDescription
    Critical1.0Errors, failures, verdict lines, or anything mentioning filenames and line numbers.
    Important0.7Warnings, counts, or state changes.
    Noise0.1Progress indicators, timestamps, decorations, or repetitive filler.

  11. Multi-agent interaction in a single repository

    main

    OMNI allows multiple agents working in the same repository to share a single history.

    Scope Boundaries

    • Session Scope: Belongs to a single agent (tied to the host's session ID).
    • Project Scope: Locked strictly to the working directory.

    Because Project Scope is directory-based rather than agent-based, two different agents running in the same repository write to and read from the same ledger history. This allows Agent A to pass a handle for a line of text to Agent B, even if Agent B has never seen that specific output before.

  12. Security and Privacy model of the OMNI plugin

    main

    The OMNI plugin follows a privacy-first design with the following security characteristics:

    • Node-Level Sanitization: The plugin strips approximately 25 dangerous environment variables (e.g., LD_PRELOAD, NODE_OPTIONS, BASH_ENV) at the process level before execution. Most other environment variables are passed through.
    • Local-Only Architecture: Terminal output is processed locally and is never sent to external cloud services.
    • Local Persistence: Usage statistics are stored in a local SQLite database at ~/.omni/omni.db.

    Warning: Because most environment variables are passed through, you should run untrusted commands in a restricted environment (like a container or CI runner) if they have access to sensitive secrets.