MemVault：为 AI Agent 打造的记忆层

想象一下，你每天醒来都忘记昨天发生的一切——朋友的名字、住过的街道、甚至自己的职业。对于普通人来说，这当然是噩梦；但对于大多数 AI 应用来说，这正是真实写照。ChatGPT 每次对话都是从零开始，Claude Code 不会记住上次帮你调试的路径，LangChain Agent 每轮对话后都会"失忆"。

MemVault（项目名 Long-Term-Memory-API）正是为了解决这个痛点而生的。它为 AI Agent 提供长期记忆存储 + 语义检索 + 知识图谱的一站式解决方案，让 AI 真正"记住"每次交互中积累的信息。

背景：为什么 AI Agent 需要记忆？

大语言模型的上下文窗口是有限的。以 GPT-4o 为例，128K token 的窗口看起来很大，但一个中等规模的对话历史可能轻松吃掉 30-50K token。更关键的是，不在上下文里的信息，AI 完全感知不到——这就像让一个人永远只能看到眼前 5 厘米的世界。

解决这个问题有两条路：

• 向量数据库路线（Pinecone、ChromaDB 等）：把文档切成片段，转成向量存储，检索时找相似片段。简单直接，但本质上是"找相似词"，不懂语义关联。
• 知识图谱路线（MemVault）：不仅存向量，还提取实体（人物、地点、概念）和关系（谁认识谁、什么导致什么），构建动态知识图谱。

MemVault 选择了后者，并提供完整的 API 服务化方案。

核心架构：三明治结构

MemVault 的技术架构分为三层：

底层：PostgreSQL + pgvector

数据库层使用 PostgreSQL，通过 pgvector 扩展支持向量存储（用于语义相似度检索），同时 Prisma ORM 提供类型安全的数据库操作。Schema 设计包含 Memory（记忆条目）、Entity（实体节点）、Relationship（关系边）三个核心模型，通过外键关联形成图结构。

中间层：GraphRAG 引擎

项目实现了完整的 GraphRAG（知识图谱增强检索）流程：

• graphExtractionService.ts：从输入文本中提取命名实体和关系三元组
• graphRAGService.ts：基于图结构进行多跳推理检索
• hybridCostGuard.ts：在检索过程中实时监控 token 消耗，防止成本失控

顶层：RESTful API + SDK

Express 路由层暴露了完整的 REST API（memory、session、admin、billing 等路由组），同时提供 TypeScript SDK（@memvault/client / memvault-sdk-jakops88），用户只需几行代码即可集成记忆功能。

核心功能解析

1. Sleep Cycle Engine（睡眠周期引擎）

这是 MemVault 最独特的设计理念——模拟人类睡眠时的记忆整合过程。

用户随时可以写入记忆（memory.add()），数据会被立即存储，但深层的语义处理（实体去重、关系强化、噪声剪枝）在后台异步进行。每 6 小时，Sleep Cycle Engine 会自动唤醒，执行图结构的合并优化。用户完全感知不到这个过程，但系统会越来越"聪明"。

对于开发者来说，这意味着你不需要写任何维护代码，记忆质量会随着时间自然提升。

2. Hybrid Search（混合搜索）

MemVault 并不依赖单一的向量检索。它将 pgvector 语义搜索 和 关键词 BM25 搜索 结合，取两者交集，保证检索结果既有语义相关性，又有关键词精确匹配。代码中通过 strategy: 'hybrid' 参数控制检索策略。

3. Cost Guard（成本守卫）

大模型 API 按 token 计费，而 AI Agent 特别容易陷入"循环调用"陷阱——Agent 不停地调用 API，每次都把所有历史上下文发过去，最终产生天价账单。

MemVault 内置了 CostGuardService，在每次检索时实时监控 token 消耗。当某次请求的 token 开销超过阈值时，会触发熔断，防止无限循环调用。

4. GraphRAG 多跳推理

传统的向量检索只能回答"这个问题的答案在哪里"；GraphRAG 能回答"这个问题通过什么关系链连接到答案"。例如：

• 向量检索：问"谁治疗了头痛病人？" → 找到包含"头痛"和"治疗"的段落
• GraphRAG：问"谁治疗了头痛病人？" → 找到 Doctor 实体 → 找到 Treatment 关系 → 追溯到 Patient 实体，精确回答"Dr. 张三"

部署方式

项目提供了完整的容器化支持，Dockerfile 采用多阶段构建：

• 依赖阶段（deps）：安装 OpenSSL、npm 依赖、Prisma client 生成
• 构建阶段（builder）：TypeScript 编译到 dist/
• 运行阶段（runner）：生产镜像，仅包含运行时必要文件

docker-entrypoint.sh 会在容器启动时自动执行 prisma migrate deploy，确保数据库 Schema 与代码同步。

除了自托管，项目还支持一键部署到 Koyeb（无服务器容器平台），配置文件 koyeb.yaml 已就绪。对于希望快速试用的用户，MemVault 还提供了基于 Vercel 的前端 Demo 和托管 API 服务。

技术栈一览

层级	技术选型
运行时	Node.js 20（TypeScript 编译）
Web 框架	Express.js
ORM	Prisma + PostgreSQL
向量引擎	pgvector（PostgreSQL 扩展）
嵌入模型	OpenAI text-embedding-3-small（默认）/ Ollama
支付集成	Stripe（订阅 + 免费试用）
邮件服务	Resend（API Key 邮件递送）
部署	Docker（多阶段构建）、Koyeb

争议与局限

1. 无 License 文件导致许可不明确

README 标注了 MIT License，但 GitHub API 查询显示 license 字段为空，仓库根目录也不存在 LICENSE 文件。这对于希望商用该项目代码的开发者来说是个隐患——建议在部署前确认 LICENSE 文件存在。

2. 仅有 TypeScript/Node.js 版本

项目未提供 Python SDK。对于 Python 生态的 AI Agent（如 CrewAI、AutoGen、LangChain Agents），集成需要自己包装 HTTP 请求，缺乏官方的类型安全保障。

3. PostgreSQL 强依赖

pgvector 的性能高度依赖数据库配置（向量维度、索引类型、内存大小）。生产环境需要认真调优，不是"跑起来就行"的方案。

4. 前端 Demo 未完整实现

根据项目文档，前端 Demo（memvault-demo） Landing 页面、登录流程、Pricing 页面和 Auth 中间件均未实现，当前是一个"半成品"前端，实际付费转化路径存在断点。

行业意义

随着 AI Agent 从"聊天机器人"向"自动化执行者"演进，记忆能力变得不可或缺。MemVault 代表了一类新兴基础设施——Memory-as-a-Service（记忆即服务）。它的 GraphRAG + Sleep Cycle 设计，在技术上有一定创新性；它的 API-first 架构，降低了 AI Agent 开发者集成记忆能力的门槛。

该项目目前 stars 数较低（72），但功能完整度相当高，对于正在构建多轮对话 Agent、需要长期上下文管理的开发者来说，是一个值得关注的技术方案。