Skip to content

README.zh-CN.md

Latest commit

 

History

History
218 lines (164 loc) · 11.9 KB

README.zh-CN.md

File metadata and controls

218 lines (164 loc) · 11.9 KB

Dense-Mem

English · 简体中文

Dense-Mem

给 AI Agent 用的自托管长期记忆服务：有证据链、能识别冲突，不会悄悄覆盖事实。

Try Dense-Mem live

先开一个临时隔离团队在线体验，再决定是否自托管。

GitHub stars GitHub issues License: Apache-2.0 Go 1.26 Docker image on GHCR

MCP Streamable HTTP Neo4j 5.26 PostgreSQL 18 OpenAPI 3.0 Visitors

DOI: 10.5281/zenodo.20469578

Dense-Mem 是一层给 MCP 客户端使用的持久记忆服务。它把来源、claims、facts、 验证流程、服务端 embeddings、recall、团队隔离、REST/OpenAPI 和带 token 保护的控制门户放在同一个自托管系统里。宿主 LLM 继续负责对话和判断； Dense-Mem 负责把记忆状态存稳、管住，并返回可以解释给用户的结构化结果。

从部署形态看，Dense-Mem 是一个独立的 HTTP MCP memory server。当前 v1 支持的 MCP 传输是 HTTP MCP，由主 HTTP 进程在 /mcp 暴露。

Dense-Mem 也是这篇研究预印本的一部分： Governed Enterprise AI Memory Beyond RAG: From Vector Retrieval to Permissioned Knowledge Graphs。

在线体验

不用先部署。打开 https://demo-dense-mem.markhuang.ai， 创建一个临时隔离团队，就可以先试 Dense-Mem 的核心流程。

Cartoon architecture illustration: AI clients send evidence into a secure Dense-Mem vault where claims become facts, conflicts become clarification questions, and durable storage sits behind the service.

为什么需要 Dense-Mem？

AI Agent 需要的不是“能搜到一段相似文本”，而是日后仍然说得清、查得到、改得对的记忆。

  • 证据先入库。记忆先以 source fragments 保存，再进入 claims 和 facts 流程。
  • Facts 不是随手写入的文本，而是经过类型化 claims、验证和 promotion gates 后产生。
  • 遇到可比较的冲突时，Dense-Mem 返回 clarifications[]，不会静默覆盖 active facts。
  • 宿主 LLM 负责从对话中抽取候选记忆、向用户追问；Dense-Mem 负责持久状态、gates、审计元数据和 recall。
  • 运维方保留对存储、team/profile 隔离、API keys 和数据出站边界的控制。

60 秒快速开始

下载本地基础 compose 示例和环境变量模板，填好必需的 secrets，然后启动服务：

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
# 填写 POSTGRES_PASSWORD、NEO4J_PASSWORD、CONTROL_PORTAL_TOKEN 和 AI_API_KEY。
${EDITOR:-vi} .env

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

基础 compose 示例会启动 Postgres、带 Neo4j Graph Data Science 插件的 neo4j:5.26-community，以及 Dense-Mem server。默认只暴露本机端口：

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/

首次拉取镜像可能不止 60 秒。基础示例刻意不包含 Redis 和公网 HTTPS；如果需要 这些部署能力，请使用 expert 示例。

服务启动时必须有完整的 embedding 配置：AI_API_URL、AI_API_KEY、 AI_API_EMBEDDING_MODEL 和 AI_API_EMBEDDING_DIMENSIONS。compose 示例已经为 URL、model 和 dimensions 提供 OpenAI 默认值：https://api.openai.com/v1、 text-embedding-3-small、1536。因此最小本地部署只需要补上 AI_API_KEY。 如果切换到其他 embedding provider 或 model，请一起覆盖这些配置。

能力对比

能力 Dense-Mem 文件记忆 Vector DB 通用 MCP memory
证据来源 Source fragments 先于 claims 和 facts 保存 通常缺失或只靠约定 保存 chunks，不保存事实演变 取决于实现
Fact 变更 通过验证门和 promotion 规则控制 手工改文本 相似度更新容易掩盖历史 往往由工具自行处理
冲突处理 可比较冲突会返回 clarification tasks 调用方自己发现 向量相似不代表语义矛盾 通常交给调用方
Recall 返回 facts、claims、fragments、contradictions 和 clarifications 文本搜索 向量相似检索 取决于实现
Agent 边界 宿主 LLM 做判断；Dense-Mem 做存储和约束 边界模糊 只负责检索 常常边界模糊
运维 Teams、profiles、API keys、审计元数据、REST、OpenAPI、MCP 很少 数据库运维 取决于实现

单节点部署可以不使用 Redis；多实例部署需要 Redis。

文档

README 只是产品概览。完整用户文档在 Dense-Mem wiki：

目标 Wiki 页面
本地跑起来 Quick Start
日常使用记忆功能 Using Dense-Mem
配置 providers、Redis 和 Traefik Configuration
理解系统架构 Architecture
查看 API 和运维细节 Technical Reference

职责边界

范围 Dense-Mem 负责 宿主 LLM 负责
写入记忆 Evidence fragments、类型化 claims、verification、gates、promotion 从聊天文本中抽取候选记忆
Embeddings 通过配置的 provider 生成 fragment embeddings 和 recall-query embeddings 正常写入和 recall 不需要自己传 vectors
Retrieval Facts、validated claims、fragments、contradictions、clarification tasks 决定对话中要问什么、引用什么
Truth changes 可比较冲突检测，以及用户确认后的 supersession 向用户确认哪条不确定记忆为准
Operations Teams、named profiles、API keys、审计元数据、control portal 客户端 MCP 配置

Dense-Mem 不是 agent brain、planner，也不是外部真相裁判。它负责存储记忆、 执行明确的 gates，并返回结构化结果。

记忆工作流

Tool 用途
remember 常规聊天记忆写入：保存证据、创建类型化 claims、验证，在 gates 通过时 promotion，并返回结构化结果。
import_memories 导入整理过的历史对话。默认只记录证据和 validated claims，不自动 promotion。
recall_memory 为已认证团队检索 facts、validated claims、fragments 和 clarifications[]。
reflect_memories 查看 active facts、candidate/disputed claims、contradictions、stale memories 和 clarification needs。
confirm_memory 应用用户对 clarification task 的回答：接受 claim 并 supersede 可比较的 active facts，或保留/拒绝它。

高级调用方仍然可以使用低层工具：save_memory、post_claim、verify_claim、 promote_claim、搜索工具、graph query tools、community tools 和 retraction tools。

记忆在系统里的主路径如下：

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

可比较冲突不会被静默解决。Dense-Mem 返回 clarifications[]，宿主 LLM 再向用户确认哪条记忆正确。用户回答后，宿主调用 confirm_memory。

数据出站

Dense-Mem 会把 fragment text 和 recall queries 发给配置的 embedding provider。Claim verification 可能会把 candidate claims 和 supporting evidence 发给配置的 verifier provider。自托管 providers 可以把这些流量留在你的边界内； 托管 providers 则不在你的自有边界内。provider 设置和数据出站细节见 wiki： Configuration 和 Technical Reference。

Embedding Model 一致性

Dense-Mem 负责正常写入和 recall 的 embeddings。启动时它会检查已存储的 embedding model 和 dimension，避免不同模型或维度的 vectors 被混在一起。 模型轮换需要重新 embedding 或重建 vector indexes；具体步骤放在 wiki 的 Configuration。

Tool Discoverability

Dense-Mem 用同一个 registry 支撑三种 discoverability surface：

Surface Path Purpose
Tool catalog GET /api/v1/tools 运行时 tool discovery
Runtime OpenAPI GET /api/v1/openapi.json Agents、codegen、integrations
MCP Streamable HTTP POST /mcp, GET /mcp 主 HTTP 服务上的 MCP clients

完整 route list 和 client examples 在 wiki： Technical Reference 和 Quick Start。

设计说明

License

Apache-2.0