agentome

Agentome

Coordinate index layer for agent context — Agentome weighs, doesn't retrieve.

Agentome is a framework for treating AI agent context like a biological genome: compress, store, and emit a verdict on what to trust versus what to reread — instead of stuffing raw text into context windows.

This package is a thin identity wrapper around Helix Context, the reference implementation. pip install agentome pulls helix-context and re-exports the full public API.

Install

# Core (server + packet mode, no optional backends)
pip install agentome

# Recommended for daily use — launcher + tray + OTel + MCP + codec
pip install agentome[all]

Both commands install the engine under the hood. If you want the full deps list resolved, see the Full dependency matrix section below.

Quick Start

from agentome import (
    HelixContextManager, load_config,
    ContextItem, ContextPacket, RefreshTarget,
)
from agentome.context_packet import build_context_packet

config = load_config()
manager = HelixContextManager(config)

# Ingest — provenance (source_kind, volatility, last_verified_at)
# auto-populated from the file extension.
manager.ingest(open("src/main.py").read(),
               content_type="code",
               metadata={"path": "/repo/src/main.py"})

# Decoder path — full assembled context for a downstream LLM
window = manager.build_context("How does auth work?")
print(window.expressed_context)
print(window.context_health.resolution_confidence)  # 0.0-1.0

# Index path — agent-safe packet with verdict + refresh plan
packet = build_context_packet("How does auth work?",
                              task_type="edit",
                              genome=manager.genome)
for item in packet.verified:
    print(f"[{item.status}] {item.source_id}  truth={item.live_truth_score:.2f}")
for target in packet.refresh_targets:
    print(f"reread: {target.source_id}  reason={target.reason}")

What is an Agentome?

An Agentome is the complete set of compressed, structured knowledge that an AI agent carries as persistent memory, plus the pathway layer that tells the agent which parts of that memory it should trust versus go re-verify. The weighing is as load-bearing as the storage.

• Genes store compressed knowledge units (code, docs, conversations)
• Promoter tags enable fast retrieval by topic
• Provenance fields (source_kind, volatility_class, last_verified_at) drive task-sensitive freshness labeling
• Coordinate confidence measures whether retrieval landed in the right region, not just whether the words overlap
• Co-activation (harmonic_links) builds associative memory over time
• Replication grows the genome from every conversation

The concept is described in the research paper: The Agentome

Agentome vs Helix Context

Use agentome in application code for the framework framing (from agentome import ...). Use helix-context in infrastructure code that you want to make obvious is wired to the engine. Both imports resolve to the same Python objects.

Full dependency matrix

Core pip install agentome installs:

That's enough to run agentome (alias for helix), the HTTP server, and /context / /context/packet with a SQLite genome.

Optional extras

Every extra mirrors the corresponding helix-context extra. pip install agentome[X] == pip install helix-context[X] in dep resolution.

Non-pip runtime deps

Some features need infrastructure outside the Python dep graph. None of these are required to start the server.

Recommended install profiles

For different use cases, here's what to pull:

# Minimal — just serve /context and /context/packet with SQLite
pip install agentome

# Agent host (Claude Code, Cursor, MCP-aware tool)
pip install agentome[mcp,codec]

# Daily developer — everything you'd realistically use
pip install agentome[all,launcher]

# Observability stack
pip install agentome[all,otel,launcher]

# CI / bench / tests
pip install agentome[all,dev]

Headroom composition (the compression path)

Agentome's default install uses character-level truncation for gene content — works but leaves compression quality on the table. With pip install agentome[codec], the expression pipeline routes through Headroom (Tejas Chopra, chopratejas/headroom) instead:

• Kompress — ModernBERT ONNX-based semantic compression (fast CPU)
• CodeAwareCompressor — language-aware for code content
• LogCompressor / DiffCompressor — contextual compressors for structured text

Headroom is opt-in to keep the core Agentome install small. When installed, Agentome activates it transparently — no code changes. Composition rule: prefer Headroom when it's available, fall back to char truncation when not.

Full Documentation

See the Helix Context README for complete documentation including:

• Two product surfaces (/context decoder path + /context/packet agent-safe index path)
• Weighing layer (freshness × authority × specificity × coord confidence)
• Pipeline lane reference
• Delta-epsilon health monitoring
• Horizontal Gene Transfer (genome export / import)
• Continue IDE integration
• MCP tool surface
• ScoreRift divergence detection bridge

License

Apache 2.0