What HeurChain does
HeurChain provides persistent memory for AI agents through MCP and plain HTTP with JSON. Agents can write facts, project decisions, and session summaries, then search those records later. The broker supports separate tenant spaces for people, teams, or projects, and each request is authenticated with an API key and tenant ID.
The system is designed for shared use across Claude Code, Codex, Gemini, local models, scripts, and other HTTP or MCP clients. It is the self-hosted edition: the repository includes the broker, deployment files, operational documentation, and the services needed to run the memory store on your own infrastructure.
How it works
A Go broker listens on one port and exposes MCP tools as well as HTTP endpoints. Redis stores memory records, tags, agent identifiers, sessions, timestamps, the BM25 index, and the vault. SQLite holds tenant data, API keys, audit records, and usage counts. An embedding service converts stored text and queries into vectors, while Qdrant stores those vectors for semantic retrieval.
Search uses both keyword and vector indexes. Reciprocal rank fusion combines their candidate rankings, so exact terms and semantic similarity can contribute to the result. Agent, tag, and date filters can narrow recall results, which also include scoring and retrieval-stage information. Repeated embedding queries can use a cache.
Memory access affects an ACT-R-style activation score: access raises the score and elapsed time lowers it. A background worker can move low-activation records to the vault, where they remain retained and exportable but are excluded from normal search. The supplied lifecycle mode starts as a dry run that logs proposed moves instead of applying them.
Setup and configuration
The self-hosted quick start uses Docker Engine with Compose v2. Clone the repository, copy deploy/.env.example to deploy/.env, set an administrator username and a long random password, then start the Compose stack. Pull the default nomic-embed-text model into Ollama before storing memories. Create a tenant through the administrative HTTP endpoint; its API key is shown once and is then used with the tenant ID.
The default deployment publishes ports on 127.0.0.1. Access from other machines requires a TLS reverse proxy. Native Linux installation through systemd is also supported. Configuration is held in deploy/broker.yaml, while secrets are stored in deploy/.env. The embedder can be changed from Ollama to an OpenAI-compatible endpoint such as OpenAI, TEI, vLLM, or LM Studio.
The hosted MCP endpoint is https://api.heurchain.com/mcp/sse. Self-hosted clients connect to the broker's MCP endpoint and send X-HeurChain-API-Key and X-HeurChain-Tenant headers. Streamable HTTP is supported, and legacy SSE is also available.
Tools and capabilities
- Store and recall memories through MCP tools such as
heurchain_store and heurchain_search.
- Start and manage agent sessions with session-oriented tools.
- Inspect or provide memory guidance through tools including
heurchain_manifest.
- Access equivalent operations through HTTP endpoints such as
/store, /search, /query, /session/start, and /memory/manifest.
- Combine BM25 keyword search with dense-vector semantic search.
- Separate data by tenant and track writes in an audit log.
The broker exposes 24 MCP tools in total. Its OpenAPI document at /openapi.json describes the HTTP API, and the root endpoint serves the agent setup guide.
Limitations and notes
Redis, an embedding service, and SQLite are required for normal operation. Qdrant is strongly recommended: without it, writes can succeed with an indexing warning, while search falls back to keyword results. The /store operation returns an error when the embedder is unavailable.
The repository's self-hosted edition is intended to be run on infrastructure you control and does not require accounts, billing, or cloud services. Backups should include the Redis volume, SQLite database, and vault directory. Qdrant data can be rebuilt from Redis by re-embedding records. Building from source requires Go 1.23 or newer, and the broker uses pure-Go SQLite without a C toolchain.