Brown Octopus

Brown Octopus is a Python library for dynamic capability-context management for tool-using AI agents. It determines which capability definitions should be available to an agent on each interaction. It does not execute tools, manage credentials, or replace the host agent framework.

Install

pip install brown-octopus
brown-octopus setup-models

setup-models explicitly prepares en_core_web_trf and Qwen/Qwen3-Embedding-0.6B in Brown Octopus-managed persistent storage. Normal initialization does not download models.

Quick start

from brown_octopus import Octopus


async def main():
    octopus = Octopus()
    await octopus.initialize()

    result = octopus.retrieve_result(
        "Reply to Tom's email",
        session_id="conversation-123",
    )

    # Final active capability context for the host agent.
    for capability in result.tools:
        print(capability["name"])

Use await octopus.update() when the host deliberately wants to discover capabilities and build an updated index. initialize() loads existing local models and index state; it does not discover or download implicitly.

Build or update an index

The repository includes a runnable example for building the persisted index from an MCP catalog:

brown-octopus setup-models
python examples/setup_index.py

By default it reads data/mcps.json and writes data/indexes/default. Use a different catalog or output directory when needed:

python examples/setup_index.py \
  --catalog path/to/my-mcps.json \
  --index path/to/my-index

The host can perform the same operation in application code:

from brown_octopus import Octopus

octopus = Octopus(
    catalog_path="path/to/my-mcps.json",
    index_path="path/to/my-index",
)
report = await octopus.update()
print(report.tool_count)

An update is not a blind append and it is not an unconditional reset. Brown Octopus compares capabilities by stable capability_id:

new capability       -> added
same ID, new metadata -> changed/replaced
same ID, unchanged    -> retained
missing from an authoritative source snapshot -> removed
temporarily failed source -> previous capabilities preserved

So if you add a new MCP entry to the catalog and run the update, its capabilities are added to the existing universe. If you remove an MCP from an authoritative catalog, its capabilities are removed. A source failure is not treated as deletion.

For a standalone capabilities JSON file, implement a CapabilitySource that reads that file and returns a CapabilityDiscoveryResult; update() uses the source snapshot and does not automatically scan arbitrary files placed beside the index.

Frozen V3 pipeline

user request
    -> deterministic spaCy operational-intent analysis
    -> capability-oriented retrieval text
    -> Qwen dense retrieval
    -> Min-4 + Bounded Max Gap selection
    -> merge and deduplicate
    -> session capability state
    -> final active capability context
    -> host agent

Embedding:        Qwen/Qwen3-Embedding-0.6B
Analyzer:         en_core_web_trf
Representation:   capability name + description
MIN_TOOLS:        4 per intent
MAX_TOOLS:        16 per intent
MIN_GAP_PERCENT:  2.0
TTL:              8 turns
Active cap:       30 capabilities

Brown Octopus is intentionally recall-oriented for its first production version. It prefers a bounded set of plausible capabilities over aggressively pruning and risking a missing required capability. It does not guarantee perfect recall.

Results and sessions

result = octopus.retrieve_result(query, session_id="conversation-123")

result.retrieved_tools  capabilities selected on this turn
result.tools            final active context after TTL/session management
result.tool_ids         IDs in result.tools
result.session_id       session identifier
result.turn             session turn number

Expose result.tools to the agent. Brown Octopus returns definitions and metadata only; the host binds and executes tools.

One engine can serve many isolated conversations. Models, indexes, and retrievers are shared; turn counters, TTL state, and active capabilities are session-specific.

octopus.reset_session("conversation-123")
octopus.delete_session("conversation-123")
snapshot = octopus.get_session("conversation-123")

The default InMemorySessionStore keeps serializable capability state in process. Applications needing persistence can inject a custom store:

octopus = Octopus(session_store=my_store)

Custom stores must make session mutation atomic across workers/processes. Brown Octopus stores capability state, not conversation history.

Building and updating the capability index

Brown Octopus separates model setup, capability discovery/indexing, and normal runtime initialization:

setup-models       prepare runtime models
    -> update()    discover capabilities and build/update the index
    -> initialize() load the existing index for runtime use

Prepare models first:

uv add brown-octopus
uv run brown-octopus setup-models
uv run brown-octopus doctor

The repository includes a runnable index setup example:

python examples/setup_index.py

By default it reads data/mcps.json and writes data/indexes/default. Paths can be changed explicitly:

python examples/setup_index.py \
  --catalog path/to/my-mcps.json \
  --index path/to/my-index

The same operation can be performed in application code:

from brown_octopus import Octopus


async def build_index():
    octopus = Octopus(
        catalog_path="data/mcps.json",
        index_path="data/indexes/default",
    )
    report = await octopus.update()
    print(report.tool_count)

update() synchronizes the configured capability source. It currently rediscovers all configured sources and rebuilds embeddings for the complete resulting universe before atomically publishing the new snapshot. It does not yet provide a separate additive-only or incremental-embedding operation.

Capabilities are compared by stable identity:

new capability       -> added
same ID, new metadata -> changed/replaced
same ID, unchanged    -> retained
missing from an authoritative snapshot -> removed
temporarily failed source -> previous capabilities preserved

Therefore, to add an MCP while preserving the existing universe, add it to the existing catalog and run update() again:

data/mcps.json
├── existing MCP servers
└── new MCP server

Passing a separate file containing only the new MCP makes that file the configured source snapshot; it does not automatically append to the previous catalog. An arbitrary capabilities JSON file is not scanned automatically. For that case, implement a CapabilitySource that reads the file and returns a CapabilityDiscoveryResult.

The default source is MCP-backed, but the abstraction is provider-neutral:

octopus = Octopus(capability_source=my_source)
report = await octopus.update()

Capability identity fields are:

capability_id  stable globally unique capability identity
source_id      discovery provenance
mcp_url        execution endpoint when applicable

The host controls when discovery occurs. Brown Octopus does not run a scheduler or rediscover capabilities during initialize().

Model storage and diagnostics

Override the managed model directory for containers or shared volumes with BROWN_OCTOPUS_MODEL_DIR. Model setup remains explicit:

brown-octopus setup-models
brown-octopus doctor
brown-octopus inspect
brown-octopus inspect --json

doctor checks package, model, and index readiness. inspect reports the active index and frozen configuration without exposing credentials.

Architecture boundary

Brown Octopus owns intent analysis, capability retrieval/selection, index construction, active capability context, session capability state, and explicit capability updates.

The host owns the LLM, conversation history, tool binding/execution, credentials, authentication, authorization, user identity, refresh timing, and session lifecycle policy.

Brown Octopus is harness-agnostic. A LangGraph integration example is available at examples/langgraph_app; LangGraph is not a runtime dependency.

Development

uv sync
brown-octopus setup-models
uv run pytest -m "not external"
uv build

Historical evaluation infrastructure remains under evals/, benchmark data under data/evals/, and research outputs under results/. These are separate from the installable brown_octopus package.

See LICENSE for licensing information.