Weasley DeepMind

Weasley DeepMind

Weasley DeepMind 是一款可自托管的 AI Agent 记忆服务。它存储小型、类型化的记忆片段，关联相关证据，并通过 MCP 找回合适的上下文，无需在每次提示词中重新加入完整的对话历史。

它是 Weasley Open Source 系列的一部分，采用 Apache-2.0 许可证发布。

为什么选择 DeepMind

• 实用的记忆检索，而非转储对话记录。 关键词、PostgreSQL GIN、图邻居和可选的 pgvector 搜索结果会合并，并在 token 预算内进行排序。
• 结构化记忆。 事实、决策、流程、偏好、事件和错误均保留来源、重要性、链接和生命周期状态。
• 原生支持 MCP。 使用本地 stdio 进程或 /mcp 上的 Streamable HTTP 端点。
• HTTP 安全默认拒绝。 未配置访问密钥时，HTTP 服务会拒绝请求。只有在本地开发时，才能显式禁用身份验证。
• 数据可自托管。 PostgreSQL 是权威数据源。Redis 以及外部嵌入或大模型提供商均为可选项。
• 已做好运维准备。 迁移使用 PostgreSQL advisory lock 串行执行，日志中的密钥会被隐藏，更新会拒绝存在未提交更改的 Git 检出目录。

要求

• Node.js 20.19 或更高版本
• PostgreSQL 15 或更高版本，并安装 pgvector 扩展
• Redis 7（可选，用于缓存和低延迟关键词查询）

从 npm 安装

npm install --global weasley-deepmind

创建一个安装了 pgvector 的 PostgreSQL 数据库，然后配置连接：

export DATABASE_URL='postgresql://postgres:password@localhost:5432/weasley_deepmind'
export WEASLEY_DEEPMIND_ACCESS_KEY='replace-with-a-long-random-secret'

weasley-deepmind migrate
weasley-deepmind serve

HTTP 服务默认监听 http://127.0.0.1:57332。其 MCP 端点为 http://127.0.0.1:57332/mcp。

将其添加到 MCP 客户端

npm 包包含一种以换行符分隔的 stdio 传输方式。通用 MCP 客户端配置如下：

{
  "mcpServers": {
    "weasley-deepmind": {
      "command": "npx",
      "args": ["-y", "weasley-deepmind", "stdio"],
      "env": {
        "DATABASE_URL": "postgresql://postgres:password@localhost:5432/weasley_deepmind",
        "WEASLEY_DEEPMIND_AUTO_MIGRATE": "true"
      }
    }
  }
}

对于已运行的 HTTP 部署，将客户端指向 /mcp，并发送 Authorization: Bearer <WEASLEY_DEEPMIND_ACCESS_KEY>。

在本地运行代码仓库

git clone https://github.com/potatohoney-p/weasley-deepmind.git
cd weasley-deepmind
npm ci
docker compose -f docker-compose.dev.yml up -d
cp .env.example.minimal .env
npm run migrate
npm start

开发用 Compose 文件将 PostgreSQL 暴露在 localhost:35432，将 Redis 暴露在 localhost:36379。启动服务前，请更新 .env 以匹配这些端口。

核心流程

flowchart LR
    Agent["AI agent"] --> MCP["stdio or Streamable HTTP"]
    MCP --> Tools["remember · recall · reflect · context"]
    Tools --> Rank["keyword + graph + vector ranking"]
    Rank --> Postgres["PostgreSQL + pgvector"]
    Rank -. optional cache .-> Redis["Redis"]

主要工具集包括 remember、batch_remember、recall、forget、amend、link、reflect、context、memory_stats、memory_consolidate、graph_explore、fragment_history、reconstruct_history 和 search_traces。工具的可用性可能会受到 API 密钥权限和运行模式的限制。

配置

变量	用途	默认值
DATABASE_URL	PostgreSQL 连接 URL	根据 POSTGRES_* 推导
WEASLEY_DEEPMIND_ACCESS_KEY	HTTP 模式必需的 Bearer 密钥	无；HTTP 默认拒绝请求
WEASLEY_DEEPMIND_AUTH_DISABLED	仅限回环地址的显式身份验证豁免；启动时会拒绝非回环监听地址	false
WEASLEY_DEEPMIND_AUTO_MIGRATE	stdio 启动前运行迁移	false（server.json 建议设为 true）
WEASLEY_DEEPMIND_HOME	CLI 缓存和本地状态目录	~/.weasley/deepmind
WEASLEY_DEEPMIND_HOST	HTTP 监听地址	127.0.0.1
PORT	HTTP 端口	57332
REDIS_ENABLED	启用 Redis 支持的功能	false
EMBEDDING_PROVIDER	openai、gemini、ollama、localai、cloudflare、transformers（需可选安装）或 custom	openai
EMBEDDING_API_KEY	可选的嵌入提供商密钥	无

完整配置表请参阅 .env.example、配置说明 和安装指南。

默认安装会有意排除本地 transformers 嵌入功能，以避免核心 MCP 服务依赖可选的原生镜像。选择 EMBEDDING_PROVIDER=transformers 前，请按照 docs/embedding-local.md 中固定版本的配置步骤操作。

CLI

weasley-deepmind serve       Start the HTTP MCP server
weasley-deepmind stdio       Start the local stdio MCP server
weasley-deepmind migrate     Apply pending database migrations
weasley-deepmind health      Check database, Redis, and embeddings
weasley-deepmind recall      Search memory from the terminal
weasley-deepmind remember    Store a memory fragment
weasley-deepmind update      Preview or apply an update

运行 weasley-deepmind --help，或参阅 CLI 参考 了解所有命令。

安全默认设置

• 除非你使用可信的反向代理并明确设置了来源允许列表，否则请将 HTTP 监听器保持在回环地址上。
• 使用唯一且高熵的 WEASLEY_DEEPMIND_ACCESS_KEY，并且绝不要提交 .env。
• Stdio 模式信任本地 MCP 主机进程；请相应保护主机账户和数据库凭据。
• 请按照 SECURITY.md 中的说明私下报告漏洞。

开发

npm ci
npm test
npm run lint
npm run lint:migrations
npm pack --dry-run

架构和运维详情请参阅 docs/architecture.en.md 和 docs/operations。欢迎通过 CONTRIBUTING.md 参与贡献。

许可证

版权所有 2026 Weasley Open Source。

根据 Apache License 2.0 授权。署名信息请参阅 NOTICE。