# HeurChain [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/peterjohannmedina/heurchain  
**GitHub Stars:** 15  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/heurchain

## Description
Persistent memory for AI agents. Store and recall facts, project decisions, and session summaries through MCP.

## Claude Desktop Quick Installation
No generated config for this server: it installs through its own setup steps.

The project's own setup steps (from https://github.com/peterjohannmedina/heurchain), copied verbatim. Run them in order; they are not an mcpServers config.

1. Install:

```sh
git clone
```

2. Start the server:

```sh
docker compose up
```

3. Install:

```sh
git clone https://github.com/peterjohannmedina/heurchain.git
```

4. Run:

```sh
cd heurchain
```

5. Configure:

```sh
cp deploy/.env.example deploy/.env      # set ADMIN_USER and a long random ADMIN_PASS
```

6. Start the server:

```sh
docker compose -f deploy/compose.yaml up -d --build
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/heurchain/readme_

