Sahil-SS9
Toolaria
Rescue oversized tool results before they flood context with a SHA256-addressed blob store and per-session indexes.
Repository last updated Jun 24, 2026
Overview
Toolaria is a Hermes Agent plugin that prevents large tool outputs from overwhelming the context window. When an MCP or web tool returns a result exceeding a configurable threshold, Toolaria stores the full output in a SHA256-addressed blob store and provides the model with a compact excerpt and a fetch handle. The model can then retrieve specific slices via semantic search, structural outlines, or pass-by-reference.
It works as a zero-config, on-by-default interceptor that composes with any context engine. The plugin intercepts oversized results from tools like web_extract, web_search, and browser tools, storing them as addressable blobs. The model receives a preview and can use the rescuer_fetch tool to retrieve data by range, grep, outline, or semantic search.
Toolaria also supports pass-by-reference: the model can pass a token like tla:<id> as an argument to another tool, and Toolaria expands it to the full content before that tool executes, keeping large payloads out of the context window entirely. This is especially useful for tool-to-tool data transfer without re-reading the content.
Highlights
- Stores oversized tool results in a SHA256-addressed blob store
- Provides compact excerpt with fetch handle to the model
- Supports structural outlines and semantic search over blobs
- Enables pass-by-reference for tool-to-tool data transfer
- On by default, zero-config, composes with any context engine
Features
Blob Store with SHA256 Addressing
Large tool outputs are stored as blobs keyed by their SHA256 hash, ensuring content-addressable retrieval and deduplication.
Structural Outlines
The model can request a structural map of a blob, such as JSON schema with numeric column stats, HTML heading hierarchy, or log error clusters, to navigate by structure.
Semantic and Lexical Search
Search over blob content using semantic retrieval (with sentence-transformers) or fallback BM25 lexical ranking, returning relevant chunks with line numbers.
Pass-by-Reference Expansion
The model can pass a token like tla:<id> as a tool argument; Toolaria expands it to the full blob content before the tool runs, keeping data out of context.
Configurable Rescue Thresholds
All settings are in config.yaml, including max result size, excerpt size, fetch caps, TTL, store size limits, and tool exclusion lists.
Graceful Degradation for Swept Blobs
After TTL or size eviction, fetch returns re-run guidance instead of a bare error, and handles degrade gracefully.
Requirements
- Python 3.x
- Hermes Agent installed
- pip install -r requirements.txt (includes regex package)
How it's built
Toolaria is a Python plugin for the Hermes Agent ecosystem. It hooks into the tool result transformation pipeline, intercepting results that exceed max_result_chars (default 12000). The blob store is file-based, located at ~/.hermes/toolaria by default, with per-session indexes for access control. Blobs are stored as files named by their SHA256 hash, with sidecar files for outlines, chunks, and vectors.
The plugin exposes a single tool, rescuer_fetch, with modes: outline, search, stat, range, grep, and full. Grep uses the regex package for safe mid-search timeout; without it, falls back to literal substring search. Semantic search requires sentence-transformers (lazy-loaded), with a BM25 fallback. Pass-by-reference expansion is handled via a tool_request middleware that expands tla:<id> tokens before tool execution, with size caps and exec/exfil sink denial by default.
The repository layout includes blobstore.py, chunking.py, excerpt.py, index.py, passref.py, semantic.py, and plugin.yaml. Tests are in tests/ covering excerpt, index, passref, semantic, and plugin integration. Configuration is in config.yaml with all keys having defaults.
Source
This summary was written for Neura Market from the project's own repository. Install commands, identifiers and licence details are reproduced unchanged. The Sahil-SS9/Toolaria repository is the authoritative source and the place to file issues or contribute.
Category: Memory & Knowledge · Licensed under MIT