convez.ai
MCP Server
markhuangai

dense-mem

markhuangai/dense-mem

Ver no GitHub
BomPluginScore · de 0 a 100

Self-hosted AI agent memory server with MCP, evidence provenance, typed claims, conflict detection, embeddings, recall, PostgreSQL, and Neo4j.

Instalação

$npx convez-ai markhuangai/dense-mem

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
40
Forks
6
Acompanhando
1
Saúde
37%
Último commit
há 1 dia
Versão
v2.8.0
Issues abertas
29
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

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.

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.

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

CapabilityDense-MemFile memoryVector DBGeneric MCP memory
Evidence provenanceSource fragments are stored before claims or factsUsually absent or informalStores chunks, not truth historyVaries by implementation
Fact changesVerification gates and promotion rulesManual editsSimilarity updates can obscure historyOften tool-specific
Conflict handlingComparable conflicts return clarification tasksCaller must noticeSimilar vectors do not mean contradictionUsually caller-managed
RecallFacts, claims, fragments, contradictions, and clarificationsText searchVector similarityVaries
Agent boundaryHost LLM judges; Dense-Mem stores and enforcesBlurredRetrieval onlyOften blurred
OperationsTeams, profiles, API keys, audit metadata, REST, OpenAPI, MCPMinimalDatabase operationsVaries

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:

GoalWiki page
Run Dense-Mem locallyQuick Start
Use memory day to dayUsing Dense-Mem
Configure providers, Redis, and TraefikConfiguration
Understand the system designArchitecture
Review API and operations detailsTechnical Reference

Responsibility Boundary

AreaDense-Mem ownsHost LLM owns
Memory writesEvidence fragments, typed claims, verification, gates, promotionExtracting candidate memories from chat text
EmbeddingsFragment embeddings and recall-query embeddings through the configured providerNo vectors for normal writes or recall
RetrievalFacts, validated claims, fragments, contradictions, clarification tasksChoosing what to ask or cite in the conversation
Truth changesComparable-conflict detection, confirmation-driven supersessionAsking the user which uncertain memory is correct
OperationsTeams, named profiles, API keys, audit metadata, control portalClient-side MCP configuration

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

Memory Workflow

ToolPurpose
rememberNormal chat-session memory insertion. Saves evidence, creates typed claims, verifies, promotes when gates pass, and returns structured outcomes.
import_memoriesIngests summarized historical conversations. By default it records evidence and validated claims without auto-promotion.
recall_memoryRetrieves facts, validated claims, fragments, and clarifications[] for the authenticated team.
trace_memoryExpands one fact or claim into bounded evidence, promotion lineage, contradictions, and supersession links.
assemble_contextBuilds a bounded prompt-ready context block plus structured facts, claims, fragments, and clarifications.
reflect_memoriesReviews active facts, candidate or disputed claims, contradictions, stale memories, and clarification needs.
confirm_memoryApplies the user's answer to a clarification task, either accepting a claim and superseding comparable active facts or keeping/rejecting it.

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:

SurfacePathPurpose
Tool catalogGET /api/v1/toolsRuntime tool discovery
Runtime OpenAPIGET /api/v1/openapi.jsonAgents, codegen, integrations
MCP Streamable HTTPPOST /mcp, GET /mcpMCP clients over the main HTTP service

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

Design Notes

License

Apache-2.0

Ver o original no GitHub

Bom para

Relacionados