MCP Memory Vault

mcp内存库

一个基于TypeScript的MCP内存和零信任秘密网关，用于本地和自托管代理系统。

此项目针对Docker优先的本地体验进行了优化：

• Postgres是真理的源泉
• pgvector包含在默认的本地堆栈中
• mem0是可选的和可添加的
• 零信任秘密处理保持不变
• 生成的知识文件在主机上保持可见

Beta状态

推荐当前版本： v0.1.0-beta

这是一个beta项目。本地Docker路径旨在作为快速评估它的默认方式。本文档稍后仍提供高级/本机操作。

它解决了什么

• 持久、可查询的代理内存
• 无秘密检索的零信任秘密使用
• 记忆和秘密行动的可审计性
• 有纪律的检索以减少低上下文错误

核心模型

• Postgres是内存、审计和加密秘密元数据的真实来源。
• mem0仅是加性召回。它不会取代Postgres。
• 内存文件位于 knowledge/ 是生成的工件，而不是主写入路径。
• 秘密明文仅在创建/旋转时被接受，之后永远不会返回。
• 特工通过以下方式使用秘密 secrets.use，而不是通过检索原始秘密值。

推荐的Docker快速入门

先决条件

• 码头工人
• Docker Compose

无主机Postgres、主机pgvector、主机 psql，或者标准路径需要systemd。

1.克隆项目

git clone https://github.com/DeathmannX/mcp-memory-vault.git
cd mcp-memory-vault

2.启动本地堆栈

docker compose up --build

默认情况下，这会做什么：

• 用pgvector启动Postgres
• 运行专用的bootstrap/init服务
• 自动应用所需的迁移
• 种子明确标记了用于烟雾验证的演示/开发数据
• 启动MCP应用程序 http://127.0.0.1:8080

您不需要创建 .env 默认Docker路径。 .env.example 仅适用于覆盖和高级/本机设置。

3.确认它有效

docker compose exec -T app curl -fsS http://127.0.0.1:8080/health

预期结果：

{
  "ok": true
}

4.运行烟雾测试

docker compose exec -T app bash /app/scripts/smoke-test.sh

预期结果：

[1/6] Wait for /health
[2/6] memory.write_event
[3/6] memory.query with task_type
[4/6] memory.get_timeline
[5/6] memory.materialize_files
[6/6] secrets.use dry-run
Smoke test passed

5.可选：登录 /admin 本地

在正在运行的应用程序容器中创建一个本地dev-admin令牌：

ADMIN_TOKEN="$(docker compose exec -T app npm run --silent mint:token -- demo-project user_admin)"
printf '%s\n' "$ADMIN_TOKEN"

然后：

1. 打开 http://127.0.0.1:8080/admin
2. 将令牌粘贴到登录字段中
3. 启动本地管理会话

此令牌流仅限于本地/dev，用于首次评估管理UI。

本地URL

• MCP服务器： http://127.0.0.1:8080
• 管理用户界面： http://127.0.0.1:8080/admin
• Postgres：默认情况下位于Docker Compose网络内部

代理/API调用的授权标头：

Authorization: Bearer 

要在正在运行的Docker应用程序上创建本地开发令牌：

docker compose exec -T app npm run --silent mint:token -- demo-project orchestrator

要为浏览器UI生成本地管理员令牌，请执行以下操作：

docker compose exec -T app npm run --silent mint:token -- demo-project user_admin

重置堆栈

清除重置：

docker compose down -v
docker compose up --build

助手命令：

npm run docker:up
npm run docker:down
npm run docker:reset
npm run docker:smoke

这些npm脚本是可选的便利包装器。规范的首次路径仍然是直接使用Docker/Compose命令。

可选mem0配置文件

默认堆栈有意具有弹性 不 需要mem0。

违约：

docker compose up --build

带有mem0的可选堆栈：

MEM0_ENABLED=true docker compose --profile mem0 up --build

为什么mem0是可选的：

• 首次本地成功不应依赖于额外的嵌入/API设置
• Postgres仍然具有权威性
• mem0仅为加性召回

如果启用mem0，请在中设置所需的任何可选提供程序/API变量 .env 在开始配置文件之前。

生成的知识文件

物化文件在主机上的以下位置可见：

knowledge/projects/

此目录绑定挂载到应用程序容器中，因此本地用户可以在以下操作后直接检查生成的文件 memory.materialize_files 或者烟雾流动。

Docker服务模型

默认服务：

• postgres

- 本地Postgres+pgvector

• bootstrap

- 等待数据库准备就绪 - 确保 vector 扩展可用 - 应用迁移 - seeds demo/dev以幂等方式引导数据

• app

- MCP服务器 - 取决于成功的引导

可选服务：

• mem0

- 仅通过配置文件启用

MCP呼叫示例

memory.write_event

TOKEN="$(docker compose exec -T app npm run --silent mint:token -- demo-project orchestrator)"

curl -X POST 'http://127.0.0.1:8080/tools/memory.write_event' \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "project_id": "demo-project",
    "sphere": "project",
    "domain": "project.overview",
    "kind": "summary",
    "retention": "review",
    "audience": "shared",
    "sensitivity": "internal",
    "type": "note",
    "content": "Demo project memory entry for release documentation.",
    "tags": ["docs", "release"],
    "parents": []
  }'

memory.query 随着 task_type

curl -X POST 'http://127.0.0.1:8080/tools/memory.query' \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "project_id": "demo-project",
    "task_type": "project_implementation",
    "query_text": "release process",
    "domains": ["project.overview"],
    "top_k": 5
  }'

high_risk_destructive 怎么翻译

curl -X POST 'http://127.0.0.1:8080/tools/memory.query' \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "project_id": "demo-project",
    "task_type": "high_risk_destructive",
    "query_text": "delete production data",
    "top_k": 5
  }'

管理用户界面

路线：

http://127.0.0.1:8080/admin

目的：

• 秘密管理
• 内存控制台
• 审计控制台

管理UI保持零信任：

• 无明文秘密检索
• 基于会话的管理UI
• 状态更改管理操作的CSRF保护
• 管理员/审核员角色分离

备份与恢复

操作备份/还原脚本仍然可用：

npm run backup:db
npm run restore:db -- ./backups/postgres-YYYYMMDDTHHMMSSZ.dump
npm run verify:restore

这些是运营工作流程，不是标准的首次本地入职流程的一部分。

文档地图

• docs/architecture.md
• docs/memory-policy.md
• docs/memory-oarchstration.md
• docs/retrieve-profiles.md
• docs/agent-memory-contract.md
• docs/review-workflow.md
• docs/agent-boottrap.md

高级/本地设置

本地主机设置、systemd部署、恢复演练和更深入的操作说明仍然受到支持，但有意不再是主要的入职途径。保留它们用于：

• 操作员工作流程
• 调试
• 非Docker部署

已知限制

• 这是一个测试版候选，而不是声称完全生产成熟。
• 超出类别级别的高风险收窄仍由呼叫者控制。
• 护栏目前专注于查询选择，而不是每个下游行动计划步骤。
• mem0仍然是加法和尽力而为；它不是必需的，也不是权威的。
• 评审和推广质量仍然取决于运营商或编排者的判断。

许可证

此存储库已准备好在Apache-2.0许可证下公开发布。看 许可证.

维护人员/相关项目

与StreamPing一起维护：

• https://streamping.me
• https://streamping.me/app