Skip to content
trtyrPublic

About

Personal knowledge-management backend — memory distillation, wiki & code graph + React UI

Topics

Resources

Stars

8 stars

Watchers

0 watching

Forks

Latest commit

 

History

785 Commits

Folders and files

Repository files navigation

🧠 Engram

把 AI 的记忆,做成可蒸馏、可检索、可审计、可遗忘的资产

单用户 AI 长期记忆平台 · Rust 单二进制 · 十二域 MCP 渐进式发现 · Wiki 单库 · 全程可溯源

Rust React PostgreSQL MCP License

en·gram(/ˈenɡræm/)n. 神经科学中的「记忆痕迹」——记忆在脑中留下的物理印记。

AI 的记忆,不该随会话蒸发。


💥 它解决什么问题

大模型的记忆活在一个会话里:关掉窗口,用户是谁、项目推进到哪、上次踩过什么坑——全部清零。 给模型塞一个「记事本」解决不了问题,因为记忆的质量取决于记忆的治理:

  • 塞进去的东西可信吗?——每一层都要能回放它从哪来、怎么来的
  • 记错了怎么办?——纠错走取代链,而不是覆盖
  • 不想让它记的,真忘得掉吗?——遗忘是一等公民,不是 UPDATE 语句

Engram 是一个「平台即工具」:平台对外暴露 MCP 与 HTTP API,AI(或人)拿着密钥操纵; 人通过 Web 控制台治理浏览。核心理念一句话——

信任源于可溯源 🔍

🖼️ 界面一览

概览——记忆管线(会话 → 原子 → 画像活文档)与全城资产态势一目了然:

概览仪表盘

用户记忆 画像 · 版本 diff
用户记忆:八类原子瓦片 + 置信量表 画像活文档:版本史与行级 diff
工单 待办
工单:必须绑定项目,列表 + 详情面板 待办:微软 To Do 式清单
项目 · 文档库 项目详情
项目外层:repo 式卡片选项目 项目内层:左树右文的文档阅读
凭据 学习驾驶舱
凭据:密钥库式台账,十一类分类 + 项目绑定 学习:连击热力图 + 领域工作台

代码图谱(注册索引 + 调用图)与 MCP 工具面(三级开关):

代码图谱 MCP 工具面
代码图谱页:注册索引与符号查询 MCP 工具面:十二域工具开关与渐进式发现

截图为演示数据(虚构人物与项目)。

🗂️ 十二域资产

域 记什么 形态
💬 Chat Memory 用户的事实、偏好、决策、事件 L0→L1 蒸馏 + 画像活文档,六动词入口,全程可溯源
🕸️ Wiki 世界的知识:文档 + LLM 增量互链 文档/URL 摄取 → [[wikilink]] 知识网 + 图谱 + lint 死链分级
🧬 CodeGraph 代码库结构索引 本地路径/git 注册 → 异步索引 → 结构化查询 + 调用子图 / 文件依赖全图
🧩 项目记忆 一件事的文档存放地 外层 repo 式卡片选项目,内层左树右文读文档;多主机位置 + 架构图制品(修订史可回滚)
🔐 凭据 API Key / Token 等机密 值 AES-GCM 加密落库、按名取用留审计痕、十一类封闭分类 + 可选项目绑定、到期治理(过期红/临期黄)、台账永不回显值
✅ 待办 行动项(todo) 轻量清单:勾选即完成;截止时间 + 逾期/今日过滤(AI 写入,前端只治理)
🎫 工单 结构化问题跟踪(ticket) 必须绑定已有项目 + severity P0-P3 + 症状/复现/验收/解决四段 + 状态机 + 活动时间线(状态流转自动留痕 + 评论)
🗄️ 资产台账 我拥有的、可被操作的对象(主机 / 云实例 / 域名 / 账号) 类型 + 名称 + 别名[] + 结构化字段 + Markdown 运行手册(修订史可回滚);项目只引用不拥有
⭕ 圈子 实体坐标系读写视图 人物/项目/主题/群组/地点——建实体、类型化关系、全景图(与 memory 同底座)
📚 学习 学习路线图跟踪 track → 知识点三态机 + 简化间隔复习(Leitner 阶梯)+ wiki 挂链;驾驶舱连击/热力图/领域工作台
🚦 日志 系统时间线 请求/错误/后台执行全量留痕,按域/级别/任务过滤——排障不靠猜
🚦 任务面(jobs) 异步任务的运行状态(蒸馏 / 摄取 / 索引 / 迁移) PG 队列:pending / running / dead 可见可恢复,进程重启不丢

🛡️ 治理,不是摆设

能力 一句话
🔒 敏感标记 医疗/感情/财务对话一个开关,检索/打包/导出默认排除
⚖️ 编辑分权 AI 只写会话;改写语义内容是用户专属,改动留痕钉住
👤 账号与会话 管理员账号 + 会话列表吊销
🧹 一等清空 deep purge 两阶段(arm 冷却 → token 执行),agent 级彻底清场
🧾 数据主权 全系统一键导出/导入 + 远程拉取迁移(A→B);密钥 AES-GCM 加密落库
🚦 任务队列 一切长操作走 PG 队列(蒸馏/摄取/索引),pending/running/dead 可见可恢复

🔌 MCP:给 AI 的原生接口

engram-server 内置 MCP 服务端(Streamable HTTP)。工具面采用渐进式发现: 十二个领域各一个入口工具 + 跨域全局检索,共 13 个工具位; 域内操作按需发现(描述自带操作目录,help 一轮取回全部参数手册,坏参数报错附合法清单)。

按密钥 scope 分权——AI 看到的工具面与它实际能调用的完全一致。 控制台可做服务总开关、整域开关、域内单操作三级开关。

Claude Code 三秒接入(宿主直跑默认端口 17654,Docker 为 8080):

claude mcp add --transport http engram http://localhost:17654/mcp \
  --header "Authorization: Bearer amk_你的密钥"

🛡️ 远程部署需放开 Host 白名单:AGENT_MEMORY_MCP_ALLOWED_HOSTS=mem.example.com(默认仅 loopback,防 DNS rebinding)。

🚀 三分钟上手

git clone https://github.com/trtyr/engram && cd engram
python3 scripts/setup.sh       # 体检依赖(缺什么给安装命令)→ 建库 → 生成配置(不构建不启动)
cd web && pnpm install --frozen-lockfile && pnpm run build && cd ..   # 构建前端(产物被 rust-embed 编译期嵌入)
python3 scripts/engramctl.py start   # 构建后端 → 安装 → 后台挂起 → http://localhost:17654
  • 登录密码在 setup.sh 生成时打印一次(也存在 ~/.engram/.env)
  • 运行时家自包含于 ~/.engram/:数据、配置、二进制、管理脚本全在本机,代码仓库只是开发工作区
  • 依赖:macOS + Homebrew(Rust / Node+pnpm / PostgreSQL+pgvector),setup.sh 会逐项体检并给出缺失项的安装命令
  • 常用命令:python3 scripts/engramctl.py stop | status | logs | restart
🐳 Docker(远程部署选项)
git clone https://github.com/trtyr/engram && cd engram/deploy
cp .env.example .env      # 改掉全部 change-me 项(主密钥生成:openssl rand -hex 32)
docker compose up -d --build
# 控制台 → http://localhost:8080

完整部署文档(必填项/反代 HTTPS/升级/备份/排障)见 deploy/README.md。

数据全在宿主:bind mount 到 ~/.engram/(postgres/、app/、backups/),备份这一个目录即可。 已有本地实例?deploy/migrate-from-local.sh 一键迁移。

📖 文档

文档即数据——全部沉淀在 engram 自身的 projects 域(本项目 name=engram), 按「总览 / 架构与实现 / 运维 / 产品 / 规划 / 决策 / 历史」组织,本地仓库不留文档 (仅保留本 README 作为 GitHub 门面)。

  • 控制台:/projects → engram
  • MCP:projects 工具的 list / doc_search / doc_get

🔧 开发者

本地开发
# 后端(需 PostgreSQL + pgvector)
cd server
AGENT_MEMORY_DATABASE_URL=postgres://127.0.0.1:5432/engram \
AGENT_MEMORY_ADMIN_PASSWORD=admin123 \
AGENT_MEMORY_MASTER_KEY=$(python3 -c "print('ab'*32)") \
  cargo run --bin engram-server

# 前端(dev server,Vite 代理到后端)
cd web && pnpm install && pnpm dev
门禁(提交前)
cd server && cargo fmt --check && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace
cd web && pnpm run lint && pnpm exec tsc --noEmit && pnpm test && pnpm run build
数据迁移(A 机 → B 机)
# A 机导出迁移包
curl -H "Authorization: Bearer $ADMIN" http://a-host:8080/migrate/export -o transfer.json
# B 机导入(冲突跳过,合并语义可重复执行)
curl -X POST -H "Authorization: Bearer $ADMIN_B" -H "Content-Type: application/json" \
  --data-binary @transfer.json http://b-host:8080/migrate/import
# 或 B 机一键远程拉取(认证:A 机管理员密码,仅请求期使用不落库)
curl -X POST -H "Authorization: Bearer $ADMIN_B" -H "Content-Type: application/json" \
  -d '{"source_url":"http://a-host:8080","source_admin_password":"…"}' http://b-host:8080/migrate/pull

覆盖记忆 / 项目 / Wiki / 待办 / 工单 / KV / assets 台账等业务数据(credentials 凭据、LLM 供应商配置、API 密钥与管理员会话不随迁——目标侧重配;资产先于项目位置导入,含敏感原子);向量与 codegraph 索引为派生数据不迁移,导入端重建。 控制台「设置 → 数据迁移」有同能力 UI。


Engram —— 记忆,不该蒸发。🧠

MIT License · Built with Rust + React + PostgreSQL

About

Personal knowledge-management backend — memory distillation, wiki & code graph + React UI

Topics

Resources

Stars

8 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages