HeurChain logo

HeurChain

Persistent agent memory with tenant isolation, hybrid keyword and vector search, sessions, and MCP or HTTP access.

Install HeurChain

Pick your client, then add it in one click or paste the config.

SSE (Remote)
Server URL
https://api.heurchain.com/mcp/sse

Remote servers are added in the app, not the config file: Customize → Connectors → Add custom connector, then paste this URL.

Hosted endpointLive · 3h agoLive Remote EndpointOur automated health check connected to this remote MCP endpoint successfully.Last checked 3h ago · Nov 18, 2026, 13:30 UTC

Clients with native remote MCP support can connect directly to this URL.

Remote endpoint
https://api.heurchain.com/mcp/sse

Overview

HeurChain MCP server gives AI agents a shared, persistent store for facts, decisions, and session summaries. It runs as a self-hosted Go broker backed by Redis, an embedding service, Qdrant, and SQLite, with tenant and API-key headers on every request. Recall combines BM25 keyword results with dense-vector results through reciprocal rank fusion, while session and lifecycle features help agents continue work over time. Reach for HeurChain when multiple agents or clients need shared memory under your infrastructure; a hosted MCP endpoint is available at https://api.heurchain.com/mcp/sse.

Use cases

  • Store project decisions for retrieval across agent sessions
  • Share facts between Claude Code, Codex, and other agents
  • Recall memories with combined keyword and semantic search
  • Separate team or project memory with tenant identifiers
  • Archive low-activity memories in the vault

Key features

  • Persistent facts, decisions, and session summaries
  • BM25 and dense-vector hybrid retrieval
  • Tenant isolation with API-key authentication
  • MCP and JSON-over-HTTP interfaces
  • Session tracking and memory lifecycle handling
  • Self-hosted Docker and systemd deployment

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked

Recent health check succeeded.

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars15Stargazers on the source repository.
Last commitTodayMost recent push to the default branch.
MaintenanceActively maintainedStatus declared by the project or listing owner.

How HeurChain works

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.

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about HeurChain

HeurChain is an MCP server that connects AI agents to a persistent memory broker for storing and recalling facts, decisions, and session summaries. Its main tools include `heurchain_store`, `heurchain_search`, `heurchain_session_start`, and `heurchain_manifest`, with hybrid keyword and vector retrieval.

Install HeurChain by cloning the repository and starting its Docker Compose deployment. Copy `deploy/.env.example` to `deploy/.env`, set `ADMIN_USER` and `ADMIN_PASS`, run the stack with Compose, and pull the `nomic-embed-text` model into Ollama before storing memories.

Connect to `https://api.heurchain.com/mcp/sse` or to the equivalent endpoint of a self-hosted broker using Streamable HTTP and the `X-HeurChain-API-Key` and `X-HeurChain-Tenant` headers. Claude Code can be configured with its HTTP MCP command.

Yes, HeurChain works with Claude Code over MCP. Configure Claude Code with the broker's HTTP MCP endpoint and provide the API-key and tenant headers for the memory space it should use.

Yes, HeurChain can run without Qdrant, but search falls back to keyword-only results. Stores can succeed with an indexing-incomplete warning, while Qdrant is recommended for dense-vector semantic retrieval.

Related MCP servers

Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewHeurChain AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/heurchain?style=directory)](https://allmcps.com/mcp/heurchain)
HTML Embed
<a href="https://allmcps.com/mcp/heurchain"><img src="https://allmcps.com/api/badge/heurchain?style=directory" alt="HeurChain on AllMCPs" /></a>