Engraphy

AI 智能体的联想记忆，以人类心智为蓝本。

Engraphy 这个名字来自记忆科学中的一个古老术语 engraphy，指在大脑中留下 engram（记忆痕迹）的过程。Engraphy 为智能体所做的正是这件事：在每次写入真正落地前，它都会把新记忆与既有记忆进行比对，合并重复的陈述，将真正意义上的新事实链接起来，并且绝不静默覆盖任何旧内容。不会删除任何东西，因此记忆的历史始终可以回溯。

Engraphy 是自托管的。它把智能体学到的东西以类型化知识图谱的形式存储于 Postgres + pgvector 之上：写入时“自我去重”会自动与既有记忆比对，检索时混合使用语义搜索与词法搜索，多用户之间的隔离由数据库强制保证，而每个应用所定义的记忆的宏观形态，则通过一套 pack 声明。

它的目的是替代旧版 MCP 参考记忆服务器那套扁平 JSON、单用户、stdio 模式，转由一个能够承受并发、复述、重复数据与多年积累的新采样实现。它遵循 Model Context Protocol，因此任何 MCP 客户端（VS Code 扩展、桌面应用、另一个 AI 智能体）都能通过 HTTP 连接到它，并使用它。

源码可用。 在 Business Source License 1.1 下开源：你可以阅读、运行、以它为基础开发，并且在属于你自己的产品中使用。把 Engraphy 本身作为托管服务、或一方托管转给第三方的权利，在到期日（Change Date）之前归 Licensor 所有；到期后它将转为 Apache License 2.0 许可。更多细节见 License。

它能做什么

• 记忆就是类型化知识图谱。 记忆由类型化的节点（fact、decision、person、event、…）构成，再由类型化的边（involves、references、supersedes、…）串接。哪些节点、哪些属性、哪种 node 只能怎么与哪种 node 互相连接，这一类规则由每个空间（space）以 pack 的方式声明，并且由 Postgres 来做硬性强制。

• 写操作自己去重。 每次写入在落库之前，会先对贡文做向量化，然后按相似度分档：合并（merge）之外、merge-link（merge+link）、pending（待判）、new（全新）。几乎逐字重复复述实施例的自动合并成同一个 node；但新的且相关的事实会以独立 node 存在、再加一条边链起来——绝不被无声吸收；举棋不定的那部分会进入 pending duplicate 判定，供调用方决定处理。每次写完成后都会返回一份共振报告（resonance report），告诉你它触碰了哪些内存。

• 混合检索。 search 把 vector 语义检索（embedding 的余弦相似度）和 词法全文检索（Postgres FTS）用 RRF 融合，traverse 则沿 edge 从一个 node 走到邻居。属性值也一并被并入可搜索的空间里，因此就算某个知识只是放在某类型化 attribute 里，也能被你 write 的的自然查询搜索出来。

• 由数据库包的隔离。 同一集群里多个 ups & 一个 space 值内多个不同 principal，全通过非超级用户的 Postgres 行级安全而相互隔开，而不是“应用层 Auth 可给绕过去”的那种隔离。服务端因此以 NOBYPASSRLS role 连接。

• 自为 LLM 设计的 Scope 路由。 每个 scope 都有自己的描述（它会“管”什么）；只读工具 scope_guide 返回这份路由清单，让 AI 智能体明确自己要把新记忆写给哪个 scope，再 commit。

• 其一整个运维面和 MCP 工具屋面：从启动并引导 cluster、发放 token、导入数据、启动包（pack），到验证备份恢复，全部都有覆盖。

Related MCP server: gbrain

工作原理

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

一次 写入 会被做向量压缩、按相似度放入以上四种 band，并在调用者身份下 commit；一次 读取（search、get、traverse、briefing）运行在 hal RLS 下，因此调用者只能看到 scope 中被授予可读的部分。一个 pack 定义了本空间中 node 类型、edge 类型、attribute 的 schema 与 session 开始时的 briefing，因此同一个引擎可以为不同形状的记忆应用服务。完整的写/读路径请见 架构总览。

快速入门

基础设施上需有：Docker（带 Compose）。项目 cloud 配置会一条命令把 Postgres 启动、异步；迁移一一跑完、所有 app role pro赛，再把服务都一起启动好。

# 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          # first boot downloads the ~523 MB embedding model

# 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 的本地启动方式，在 setup guide 里也有。

也可以用脚本一键

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 的 health 状态；因为首次启动时 compose 会一直显示 starting，直到模型 cache 真的 seed 完成——从外部看这跟“崩溃 loop”分不清，真正的活口是返回 200 的本。所以 up.sh 用的是 200 来判断。

两个脚本都支持重复运行：不会覆盖已有的 .env；而现有的空间或已经 apply 过的 pack 会被安静地跳过，并不是当作错误——因此你重跑只会拿到一个新的 token。

所有参数都能调，且带了你基本不用改的默认值：

token 只被打印一次，且永远不会被脚本写盘；服务端只存储 token 的 SHA-256。若不丢，重新跑一次 provision.sh 即可拿新。

如何在客户端上使用

Engraphy 是一个 MCP server，所以对接到客户端上你会直接调用它的各个工具：

「参数、返回值、和每一个工具的例子」都在 工具参考。同时仓库还放了一个官方 VS Code 扩展，在 vscode-extension/ 里。

文档

• docs/ 整个 developer 信息中心：包括架构 、部署、packs、工具参考、运行/部署 和 完整一步步教程。

• design/：设计文档目录——数据分型、检索 + 去重、auth + tenancy、持续跑一个目录操作、pack/flagging 与本体论、以及开发 bake on benchmark。工程背后的"为什么"在 docs 里。

• skills/：这是给读这种的 LLM 智能体的可加载 “技能”：怎么写得更好、怎么检索、scope 和 visibility 如何编排，以及回答问题时的自律性纪律。

环境条件

• PostgreSQL 16，且要装了扩展 pgvector（pgvector/pgvector:pg16 镜像我自带）。

• Python ≥ 3.12。

• 迁移工具 dbmate（已被打进 admin 容器里；但用非 Docker 路径这时，你需要在 PATH 中放一个可执对象）。

• 默认的 embedding 模型为 nomic-ai/nomic-embed-text-v1.5（输出 384 维、保存在约 523 MB，会在第一次启动时得到拉取并缓存。

项目状态

v0.1.0 目前完成的：体系 schemas 与必选约束、引擎核心（去重、混合检索、graph 行走、引擎与 briefing）、带认证和 admin 的 MCP 服务端，以及运维 CLI + 标准库；都通过真 Postgres 的测试套件？CI 一道 Job 也会执行整个发布产物的链端到端的 smoke 测试。benchmark 工具 (bench/ 和 design/09) 用公开的重型长时记忆数据集来对原版引擎做，主要只是帮你在修改时看变化，并不是拿来做广告的 metrics 来源。

许可协议

Engraphy 按 Business Source License 1.1 该协议发布（见 LICENSE）。

• 你可以：读、改、随便分销、自己部署，并且在生产环境把它作为自己应用和 agent 的记忆沉淀层使用。

• 在 Change Date 之前，你不得将 Engraphy 本身作为 it's Hosted 或 managed service 服务提供给第三方。

• Chang 时间点：2026-08-22 + 4 年（也就是 2030-08-22）。从那天起，其会自动变为 Apache License 2.0。

Copyright (c) 2026 Devon Clark.