Dense Mem

Dense-Mem gives MCP clients a durable memory layer with provenance, typed claims and facts, verification gates, server-side embeddings, recall, team isolation, REST/OpenAPI, and a token-protected control portal. The host LLM owns conversation and judgment; Dense-Mem owns durable memory state and returns structured outcomes the host can explain to users.

Under the hood, Dense-Mem is a standalone HTTP MCP memory server. HTTP MCP is the v1 supported MCP transport and is served at /mcp from the main HTTP process.

Dense-Mem is part of the research preprint Governed Enterprise AI Memory Beyond RAG: From Vector Retrieval to Permissioned Knowledge Graphs.

Project Intro

Related MCP server: mcp-local-memory

Try the Hosted Demo

Create a temporary isolated team at https://demo-dense-mem.markhuang.ai and test Dense-Mem before self-hosting.

Why Dense-Mem?

AI agents need memory that can be trusted later, not only text that can be retrieved later.

• Evidence is first-class. Memories start as source fragments before they become claims or facts.

• Facts pass through typed claims, verification, and promotion gates.

• Comparable conflicts become clarifications[]; Dense-Mem does not silently overwrite active facts.

• The host LLM stays responsible for extracting candidates and asking the user questions. Dense-Mem stays responsible for durable state, gates, audit metadata, and recall.

• Operators keep control of storage, team/profile isolation, API keys, and data egress boundaries.

60-Second Quickstart

Download the base local-only compose example and env template, set the required secrets, and start Dense-Mem:

mkdir dense-mem-local
cd dense-mem-local

curl -fsSLo docker-compose.yml \
  https://raw.githubusercontent.com/markhuangai/dense-mem/main/examples/docker-compose.base.yml
curl -fsSLo .env.example \
  https://raw.githubusercontent.com/markhuangai/dense-mem/main/examples/.env.example

cp .env.example .env
# Fill in POSTGRES_PASSWORD, NEO4J_PASSWORD, CONTROL_PORTAL_TOKEN, and AI_API_KEY.
${EDITOR:-vi} .env

docker compose up -d
docker compose exec server /app/provision-team --name "primary-memory"

The base compose example provisions Postgres, neo4j:5.26-community with the Neo4j Graph Data Science plugin, and the Dense-Mem server. It exposes only local host ports:

MCP/API:        http://127.0.0.1:8080/mcp
User portal:    http://127.0.0.1:8080/ui
Control portal: http://127.0.0.1:8090/

Cold image pulls can take longer than 60 seconds. Redis and public HTTPS are intentionally omitted from the base example; use the expert example when you need those deployment options.

The server requires a complete embedding configuration at startup: AI_API_URL, AI_API_KEY, AI_API_EMBEDDING_MODEL, and AI_API_EMBEDDING_DIMENSIONS. The compose examples provide OpenAI defaults for the URL, model, and dimensions (https://api.openai.com/v1, text-embedding-3-small, 1536), so the minimal local setup only needs you to fill in AI_API_KEY. Override those values together when using a different embedding provider or model.

Telemetry Overlay

Prometheus telemetry is optional and off by default. To collect usage, performance, verifier token, embedding token, recall, and promotion metrics for the /ui app and control portal dashboards, run the base stack with the telemetry overlay:

curl -fsSLo prometheus.yml \
  https://raw.githubusercontent.com/markhuangai/dense-mem/main/examples/prometheus.yml
curl -fsSLo docker-compose.telemetry.yml \
  https://raw.githubusercontent.com/markhuangai/dense-mem/main/examples/docker-compose.telemetry.yml

export TELEMETRY_SCRAPE_TOKEN="$(openssl rand -hex 32)"
docker compose -f docker-compose.yml -f docker-compose.telemetry.yml up -d

The overlay starts Prometheus on 127.0.0.1:9090, retains 30 days of samples, passes TELEMETRY_SCRAPE_TOKEN to Prometheus as a scrape secret, and points Dense-Mem at http://prometheus:9090 for telemetry queries. It also sets TELEMETRY_PROMETHEUS_JOB=dense-mem so dashboards query only the dense-mem scrape job when Prometheus is shared.

Online recall-quality cards use densemem_recall_feedback_total and densemem_recall_feedback_quality_score. They stay at zero until RECALL_FEEDBACK_ENABLED=true registers the submit_recall_feedback tool and a host LLM submits compact feedback for recall_memory results. Normal production recall traffic still contributes request volume, result count, and latency.

For the disposable demo image, keep the control portal disabled and use the demo telemetry overlay instead:

curl -fsSLo prometheus.demo.yml \
  https://raw.githubusercontent.com/markhuangai/dense-mem/main/examples/prometheus.demo.yml
curl -fsSLo docker-compose.demo.telemetry.yml \
  https://raw.githubusercontent.com/markhuangai/dense-mem/main/examples/docker-compose.demo.telemetry.yml

export TELEMETRY_SCRAPE_TOKEN="$(openssl rand -hex 32)"
docker compose -f docker-compose.yml -f docker-compose.demo.telemetry.yml up -d

The demo overlay scrapes the demo service at demo:8091 on the private Compose network and sets TELEMETRY_PROMETHEUS_JOB=dense-mem-demo. Do not publish that metrics listener publicly.

Compare

Redis is optional for single-node deployments and required for multi-instance deployments.

Documentation

The README is the product overview. The full user documentation lives in the Dense-Mem wiki:

Responsibility Boundary

Dense-Mem is not an agent brain, planner, or external truth arbiter. It stores memory, applies explicit gates, and returns structured outcomes.

Memory Workflow

Low-level tools remain available for advanced callers: save_memory, post_claim, verify_claim, promote_claim, search tools, graph query tools, community tools, and retraction tools.

Memory moves through this path:

source fragment -> typed claim -> verification -> promotion gate -> active fact
                                                   |
                                                   v
                                            clarification task

Comparable conflicts are not resolved silently. Dense-Mem returns clarifications[], and the host LLM asks the user which memory is correct. After the user answers, the host calls confirm_memory.

Data Egress

Dense-Mem forwards fragment text and recall queries to the configured embedding provider. Claim verification can send candidate claims and supporting evidence to the configured verifier provider. Self-hosted providers keep that traffic inside your boundary; hosted providers do not. See the wiki Configuration and Technical Reference for provider settings and egress details.

Embedding Model Consistency

Dense-Mem owns embeddings for normal writes and recall. It checks the stored embedding model and dimension on startup so vectors from incompatible models are not mixed silently. Rotation requires re-embedding or rebuilding vector indexes; the step-by-step process belongs in the wiki Configuration.

Tool Discoverability

Dense-Mem exposes three discoverability surfaces backed by one registry:

The full route list and client examples live in the wiki Technical Reference and Quick Start.

Design Notes

• standalone MCP memory architecture

• knowledge-pipeline contracts

• knowledge-pipeline client contracts

• knowledge-pipeline operability

License

Apache-2.0