Engraphy

Engraphy

一款 MCP 服务，为 AI Agent 提供以人类思维为模型的联想记忆。

快速入门 · 文档 · 工具参考 · 设计集 · 贡献指南

这个名字源自 engraphy，这是记忆科学中的一个古老术语，指形成 engram（记忆痕迹）的过程，也就是记忆在大脑中留下的印迹。Engraphy 为 Agent 实现了这一过程：每条新记忆写入前，都会先与已有知识进行比对，合并重复表述，关联真正的新事实，绝不会悄无声息地覆盖内容。任何内容都不会被删除，因此历史始终可以追溯。

Engraphy 可自托管。它将 Agent 学到的内容存储为 Postgres + pgvector 上的类型化知识图谱：写入时会自动与现有记忆去重，检索会融合语义搜索与词法搜索，用户间隔离由数据库强制保障，而记忆的整体结构则由每个应用以 pack 声明。

它旨在取代参考 MCP 记忆服务的扁平 JSON、单用户、stdio 模型，解决并发、释义、重复内容以及多年累积记忆带来的问题。它遵循 Model Context Protocol，因此任何 MCP 客户端（VS Code 扩展、桌面应用或其他 Agent）都可以通过 HTTP 使用它。

可获取源代码。 采用 Business Source License 1.1 许可：你可以阅读、运行、基于它进行开发，并将其用于自己的产品生产环境。直到变更日期（届时许可将转换为 Apache-2.0），向第三方提供 Engraphy 本身的托管或管理服务均为许可方保留的权利。请参阅许可证。

---

功能

• 有类型的记忆图谱。 记忆由有类型的节点（fact、decision、 person、event 等）组成，并通过有类型的边（involves、references、 supersedes 等）连接。类型、属性架构，以及哪些边可以连接哪些类型的规则， 都在每个空间的 pack 中声明，并由 Postgres 强制执行。
• 可自动去重的写入。 每次写入都会生成嵌入，并与现有记忆进行分级匹配。近乎 逐字的重述会自动合并；真正新颖但相关的事实会作为独立的可搜索节点保留，并通过 边连接（不会被悄然吸收）；难以判断的情况会暂存为待处理的重复检查结果，供调用方 处理。每次写入都会返回一份说明其影响内容的共鸣报告。
• 混合检索。 search 使用倒数排名融合（Reciprocal Rank Fusion），融合向量 分支（对嵌入进行余弦计算）和词法分支（Postgres 全文搜索）；traverse 则遍历 各条边。属性值会并入可搜索内容，因此仅存储在有类型属性中的事实也能被找到。
• 由数据库强制执行的隔离。 多个空间以及同一空间内的多个主体，通过以非超级用户 角色运行的 Postgres 行级安全（Row-Level Security）进行隔离，而不是依赖可能被 遗忘的应用层检查。服务以 NOBYPASSRLS 角色连接。
• 为大模型设计的范围路由。 每个范围都附带其管辖内容的描述；只读的 scope_guide 工具会返回这份路由清单，让 Agent 在写入新记忆前决定它应该放在哪里。
• 运维 CLI 和 MCP 工具接口，涵盖从初始化空间到创建令牌、导入数据、应用 pack 以及验证恢复等所有操作。

工作原理

flowchart LR
    C[MCP client<br/>VS Code · desktop · agent] -->|HTTP + bearer token| S[Engraphy server<br/>FastMCP]
    S --> E[Embedding<br/>nomic-embed-text-v1.5]
    S --> DB[(Postgres 16 + pgvector<br/>nodes · edges · scopes<br/>RLS · schema enforcement)]
    P[Pack<br/>types · edges · briefing] -.declares.-> DB

一次写入会先生成嵌入，再按相似度分级为合并／合并并链接／待处理／新内容，并以 调用方的身份提交。一次读取（search、get、traverse、briefing）会在 RLS 下运行，因此调用方只能看到获授权访问的范围。pack 会为一个空间声明节点类型、 边类型、属性架构和会话启动简报，因此同一引擎可以服务于形态各异的记忆应用。 架构概览详细介绍了完整的写入和读取流程。

快速开始

要求：Docker（带 Compose）。云端配置会启动 Postgres、运行迁移、配置应用角色，并 通过一条命令启动服务。

# 1. Configure secrets (never committed)
cp deploy/.env.example .env   # then edit, or:
printf 'POSTGRES_PASSWORD=%s\nENGRAPHY_APP_ROLE_PASSWORD=%s\n' \
  "$(openssl rand -hex 16)" "$(openssl rand -hex 16)" > .env

# 2. Bring up Postgres + migrate + provision + serve
docker compose up -d          # the embedding model ships baked into the image

# 3. Create a space, apply the starter pack, mint a client token
docker compose --profile admin run --rm admin \
  engraphy-admin space create --id personal --display-name "My Memory" --principal me
docker compose --profile admin run --rm admin \
  engraphy-admin pack apply packs/starter/pack.yaml --space personal
docker compose --profile admin run --rm admin \
  engraphy-admin token create --space personal --principal me \
    --client-name my-editor --role readwrite

服务现在运行在 127.0.0.1:8000（如需对外开放，请在前面配置一个负责终止 TLS 的反向 代理）。使用 bearer token 将任意 MCP 客户端指向该服务。设置指南 也介绍了无需 Docker 的本地方式。

或者让脚本来完成

up.sh 和 provision.sh（Windows 对应版本为 up.ps1 / provision.ps1）会严格按上述步骤执行，并补上复制粘贴式快速入门无法提供的等待逻辑：

./up.sh          # writes .env with random passwords, starts the stack,
                 # then blocks until /healthz returns 200
./provision.sh   # creates the space, applies the starter pack, mints a token,
                 # and prints the client settings to paste in

up.sh 会轮询 /healthz，而不是检查 compose 的健康状态，因为首次启动时，compose 会一直报告 starting，直到模型缓存完成初始化；从外部看，这与崩溃重启循环无法区分。收到 200 才是真正的就绪信号。

这两个脚本都可以安全地重复运行：已有的 .env 不会被覆盖；已有空间或已应用的包会被跳过，而不会被视为错误，因此再次运行仍会生成新令牌。

所有参数都可配置，默认值可直接使用：

	默认值	覆盖方式
空间 ID	default	./provision.sh myspace 或 -Space myspace
主体	me	./provision.sh myspace alice 或 -Principal alice
客户端名称	my-client	第三个位置参数，或 -ClientName
包	/app/packs/starter/pack.yaml	ENGRAPHY_PACK 或 -Pack
主机端口	8000	.env 中的 ENGRAPHY_HOST_PORT，或 -Port
健康检查超时	up 为 1800s，provision 为 600s	ENGRAPHY_WAIT_SECS 或 -WaitSeconds

令牌只会打印一次，脚本绝不会将其写入磁盘；服务端只存储其 SHA-256 值。如果令牌丢失，请重新运行 provision.sh 以生成新令牌。

从客户端使用

Engraphy 是一个 MCP 服务，客户端可以连接并调用工具：

工具	功能
write	按去重规则写入；返回节点，或返回重复项检查结论及共振报告。
search	在单个范围或所有范围中进行语义与词法混合检索。
traverse	从起始节点递归遍历图。
get	按 ID 获取完整节点及边摘要。
briefing	由包声明的会话开始章节（到期承诺、相关笔记等）。
scope_guide	路由清单：所有可写范围及其管理内容。
scope_list / scope_create	列出可读范围 / 创建私有范围。
link · update · supersede · resolve_duplicate	编辑图并处理待定结论。
pending_list · stats · inbox_review	检查待处理写入、使用指标和捕获收件箱。
admin_*	空间管理（成员、令牌、授权、可见性）。

请参阅工具参考，了解各工具的参数、返回值和示例。官方 VS Code 扩展位于 vscode-extension/。

文档

• docs/：开发者文档，包括架构、 设置、包、 工具参考、部署 和端到端教程。
• design/：设计资料集，涵盖数据模型、检索与去重、 身份验证与租户、运维、包/本体系统以及基准测试工具。这里记录了工程设计思路。
• skills/：简明指南，可供大模型 Agent 加载，以便更好地使用 Engraphy（写入与去重、检索、范围与可见性、回答规范）。

要求

• Postgres 16，并安装 pgvector（pgvector/pgvector:pg16 镜像同时包含两者）。
• Python ≥ 3.12。
• 用于迁移的 dbmate（内置于管理容器中；仅在无 Docker 路径下需要位于 PATH 中）。
• 嵌入模型 nomic-ai/nomic-embed-text-v1.5（384 维，运行于 ONNX Runtime，首次启动时下载并缓存）。

项目状态

v0.1.0。模式和执行内核、引擎行为（去重、混合检索、图遍历、简报）、带身份验证和管理功能的 MCP 服务，以及运维 CLI 均已实现，并由实时 PostgreSQL 测试套件和一个端到端测试已发布部署产物的 CI 任务提供覆盖。基准测试工具（bench/、design/09）使用公开的长期记忆数据集测试引擎；它用于衡量变更，而非生成营销数据。 bench/RUN-LOCOMO.md 介绍了如何自行运行 LoCoMo：需要一个兼容 OpenAI 的基础 URL 和密钥，并固定了数据集、实验组、模型和评审模型。

贡献

欢迎提交问题和拉取请求。CONTRIBUTING.md 介绍了如何启动开发数据库、运行测试套件、三个 CI 任务的检查内容，以及项目的代码风格。安全问题请通过私密安全公告提交，而不要公开报告。

许可证

Engraphy 采用 Business Source License 1.1 许可（参见 LICENSE）。

• 你可以阅读、修改、再分发、自托管，并在生产环境中将 Engraphy 用作你自己的应用和 Agent 的记忆层。
• 在变更日期之前，你不得将 Engraphy 本身作为托管或管理服务提供给第三方。
• **变更日期：**2026-08-22 + 4 年（2030-08-22），届时许可证将转换为 Apache License, Version 2.0。

版权所有 (c) 2026 Devon Clark。