Easy Memory

让 AI 跨会话、跨项目持久化记忆。 基于 Qdrant 向量数据库 + Ollama/Gemini Embedding 的 MCP 记忆服务。

Easy Memory 提供双 Shell 架构：

• MCP Shell — 通过 stdio 与 Claude Desktop / Cursor / VS Code 等 IDE 直接通信
• HTTP Shell — RESTful API，支持远程访问、多客户端共享记忆

目录

• 快速开始
• 客户端配置
• 30 秒排障（远端优先）
• HTTP API
• MCP Tools
• Docker 部署
• 环境变量
• Web UI 管理面板
• 架构文档

快速开始

推荐路径（远端 VPS 优先，约 30 秒）

如果你已有远端 Easy Memory 服务（例如 https://memory.zhiz.chat）和 API Key（em_...），建议优先使用 stdio 远程代理模式：

1. 在客户端 MCP 配置里使用 npx easy-memory@latest + EASY_MEMORY_URL + EASY_MEMORY_TOKEN
2. 执行 Reload Window / 重启客户端
3. 运行 MCP: List Servers（或客户端等效命令）确认 server 已连接

根键速记：VS Code 的 .vscode/mcp.json 用 servers；Claude Desktop / Cursor 常见 mcpServers。

只有在你没有远端服务时，再走下方“本地自托管（Qdrant + Ollama）”路径。

前置条件

💡 远程代理模式无需本地 Qdrant/Ollama
如果你有远端 Easy Memory 服务（如 memory.zhiz.chat），只需设置 EASY_MEMORY_TOKEN 和 EASY_MEMORY_URL 即可。参见 远程代理模式。

基础服务准备（Qdrant + Ollama）

Easy Memory 依赖两个基础服务：Qdrant（向量数据库）和 Ollama（本地 Embedding 模型）。

# 1. 启动 Qdrant 向量数据库
docker run -d --name qdrant \
  -p 6333:6333 \
  -v qdrant_data:/qdrant/storage \
  -e QDRANT__SERVICE__API_KEY=your-api-key \
  qdrant/qdrant:latest

# 验证 Qdrant 运行正常
curl http://localhost:6333/healthz
# 应返回: OK

# 2. 启动 Ollama（本地 AI 模型推理引擎）
docker run -d --name ollama \
  -p 11434:11434 \
  -v ollama_data:/root/.ollama \
  ollama/ollama:latest

# 3. 拉取 bge-m3 Embedding 模型（约 1.2GB，首次需等待）
docker exec ollama ollama pull bge-m3

# 验证 Ollama 运行正常
curl http://localhost:11434/api/tags
# 应返回包含 "bge-m3" 的模型列表

⚠️ 注意事项：

• QDRANT__SERVICE__API_KEY 是 Qdrant 的认证密钥，后续配置中需跟 QDRANT_API_KEY 保持一致
• bge-m3 模型首次加载约需 2GB 内存，低配机器可能较慢
• Ollama 默认监听 0.0.0.0:11434，生产环境建议限制到 127.0.0.1

可选：配置 Google Gemini 远端 Embedding

如果你需要更高质量的向量或本地资源不足，可以启用 Gemini Embedding（Google Cloud Vertex AI）：

1. 前往 Google AI Studio 获取 API Key
2. 在 Google Cloud Console 创建项目并启用 aiplatform.googleapis.com
3. 设置环境变量：

EMBEDDING_PROVIDER=auto    # auto = Gemini 优先，Ollama 自动兜底
GEMINI_API_KEY=AIzaSy...   # Google AI Studio API Key
GEMINI_PROJECT_ID=my-gcp-project  # Google Cloud Project ID
GEMINI_REGION=us-central1  # 可选，默认 us-central1

auto 模式下，Gemini 请求失败（限流/超时）会自动降级到 Ollama，确保服务不中断。

方式一：npx 直接运行（MCP 模式）

# 前提：Qdrant 和 Ollama 已按上方步骤启动

# 通过 npx 启动 MCP Server
npx easy-memory

方式二：Docker Compose 一键部署

git clone https://github.com/FlippySun/easy-memory.git && cd easy-memory
cp .env.example .env   # 编辑配置
docker compose up -d
docker exec ollama ollama pull bge-m3

方式三：从源码构建

git clone https://github.com/FlippySun/easy-memory.git && cd easy-memory
pnpm install
pnpm build

# MCP 模式
node dist/index.js

# HTTP 模式
EASY_MEMORY_MODE=http HTTP_AUTH_TOKEN=your-token node dist/index.js

客户端配置

mcp.json 根键速查（避免“工具列表为空”）

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "easy-memory": {
      "command": "npx",
      "args": ["-y", "easy-memory"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_API_KEY": "your-api-key",
        "OLLAMA_BASE_URL": "http://localhost:11434"
      }
    }
  }
}

Cursor

编辑 Cursor Settings → MCP → 添加：

{
  "mcpServers": {
    "easy-memory": {
      "command": "npx",
      "args": ["-y", "easy-memory"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_API_KEY": "your-api-key",
        "OLLAMA_BASE_URL": "http://localhost:11434"
      }
    }
  }
}

VS Code (GitHub Copilot)

编辑 .vscode/mcp.json：

{
  "servers": {
    "easy-memory": {
      "command": "npx",
      "args": ["-y", "easy-memory"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_API_KEY": "your-api-key",
        "OLLAMA_BASE_URL": "http://localhost:11434"
      }
    }
  }
}

远程代理模式（推荐 — 无需本地 Qdrant/Ollama）

当你有一台运行 Easy Memory HTTP 服务的远程服务器时，本地客户端可通过远程代理模式直接对接远端服务，无需本地安装 Qdrant 或 Ollama。

需要先在远端 Admin 面板创建 API Key（参见 VPS 生产部署 → 用户管理）。

Claude Desktop / Cursor / VS Code — stdio 代理模式：

{
  "mcpServers": {
    "easy-memory": {
      "command": "npx",
      "args": ["-y", "easy-memory@latest"],
      "env": {
        "EASY_MEMORY_TOKEN": "em_your-api-key",
        "EASY_MEMORY_URL": "https://memory.zhiz.chat"
      }
    }
  }
}

仅需设置两个环境变量，npm 包会自动切换为远程代理模式：

• EASY_MEMORY_TOKEN — 远端 API Key（从 Admin 面板获取）
• EASY_MEMORY_URL — 远端服务地址

MCP Streamable HTTP 模式（直连远端，进阶）

⚠️ VS Code 告警说明（重点）

当配置 type: "http" 时，VS Code 可能先尝试 OAuth 流程，并提示： “不支持动态客户端注册（manual client registration）”。

Easy Memory 当前是 Bearer Token 鉴权（Authorization: Bearer ...），不支持 OAuth 动态客户端注册。 这通常不是 VPS 故障，而是客户端接入模式不匹配。

对 VS Code / Cursor，优先使用上面的**远程代理模式（stdio）**更稳妥。

支持 Streamable HTTP 的客户端可以直接连接远端 MCP 端点，无需 stdio 代理：

HTTP 直连（适合明确支持 Bearer Header 的客户端）：

{
  "servers": {
    "easy-memory": {
      "type": "http",
      "url": "https://memory.zhiz.chat/mcp",
      "headers": {
        "Authorization": "Bearer em_your-api-key"
      }
    }
  }
}

VS Code / Cursor 推荐配置（避免 OAuth 告警）

编辑 .vscode/mcp.json：

{
  "servers": {
    "easy-memory": {
      "command": "npx",
      "args": ["-y", "easy-memory@latest"],
      "env": {
        "EASY_MEMORY_URL": "https://memory.zhiz.chat",
        "EASY_MEMORY_TOKEN": "em_your-api-key"
      }
    }
  }
}

这是 stdio 代理模式：VS Code 不会先走 OAuth 注册探测，工具握手更稳定。

配置变更后，请执行 Reload Window，再运行 MCP: List Servers 检查状态。 若工具列表为空，优先检查 EASY_MEMORY_URL / EASY_MEMORY_TOKEN； GET /health 返回 {"status":"ok","mode":"http"}，且用于连通性探针时故意不带 token 访问 /mcp 返回 401，都属于正常保护行为。

远程 HTTP 模式

如果部署了 HTTP Shell，客户端可通过 HTTP API 接入 — 无需本地 Qdrant/Ollama。详见 HTTP API 部分。

30 秒排障（远端优先）

1. 先看配置键名：VS Code 用 servers，Claude/Cursor 常见 mcpServers
2. 强制生效配置：执行 Reload Window / 重启客户端
3. 看 MCP 连接状态：运行 MCP: List Servers
4. 看服务健康：GET /health 返回 {"status":"ok","mode":"http"}
5. 看鉴权语义：

• 未带 token 访问 /mcp 返回 401 = 正常保护
• type: "http" 出现 OAuth 动态注册提示 = 模式不匹配，切回 stdio 远程代理

HTTP API

所有 /api/* 端点需要 Bearer Token 认证：

Authorization: Bearer <HTTP_AUTH_TOKEN>

GET /health

健康检查（无需认证）。

curl http://localhost:3080/health
# {"status":"ok","mode":"http"}

POST /api/save

保存一条记忆。

curl -X POST http://localhost:3080/api/save \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "项目使用 pnpm 作为包管理器",
    "metadata": {
      "category": "convention",
      "tags": ["tooling", "pnpm"]
    }
  }'

请求字段：

POST /api/search

语义搜索记忆（混合检索：向量 + BM25）。

curl -X POST http://localhost:3080/api/search \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"query": "包管理器", "limit": 5}'

请求字段：

POST /api/forget

归档/删除记忆。

curl -X POST http://localhost:3080/api/forget \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "uuid-of-memory",
    "action": "archive",
    "reason": "信息已过时"
  }'

action 说明：

• archive — 软删除（标记为归档，搜索时默认不返回）
• outdated — 标记为过时
• delete — 从向量库中彻底删除

GET /api/status

系统状态检查。

curl -H "Authorization: Bearer your-token" http://localhost:3080/api/status

MCP Tools

Easy Memory 暴露 4 个 MCP Tools：

Docker 部署

开发环境

cp .env.example .env
docker compose up -d
docker exec ollama ollama pull bge-m3

生产环境

cp .env.example .env
# 编辑 .env: 设置强密码 QDRANT_API_KEY, HTTP_AUTH_TOKEN

docker compose -f docker-compose.prod.yml up -d
docker exec ollama ollama pull bge-m3

# 验证
curl http://your-server:3080/health

预构建镜像

docker pull thj8632/easy-memory:latest
# 或指定版本
docker pull thj8632/easy-memory:0.2.1

支持平台：linux/amd64, linux/arm64

VPS 生产部署

前置条件

1. 部署服务

# 克隆代码
git clone https://github.com/FlippySun/easy-memory.git
cd easy-memory

# 配置环境变量
cp .env.example .env
vim .env
# 必须设置:
#   QDRANT_API_KEY=<强随机密钥>
#   HTTP_AUTH_TOKEN=<Master Token — 管理员自用>
#   ADMIN_TOKEN=<Admin Token — 管理后台>

# 启动
docker compose -f docker-compose.prod.yml up -d

# 验证
curl http://localhost:3080/health
# {"status":"ok","mode":"http"}

2. 反向代理 (HTTPS)

Caddy（推荐 — 自动 HTTPS）

cp deploy/Caddyfile.example /etc/caddy/Caddyfile
# 编辑: 替换 memory.example.com 为实际域名
sudo systemctl reload caddy

Nginx（手动证书）

cp deploy/nginx.conf.example /etc/nginx/conf.d/easy-memory.conf
# 编辑: 替换域名, 配置 SSL 证书
sudo certbot --nginx -d memory.example.com
sudo nginx -s reload

3. 三层认证架构

ADMIN_TOKEN（管理员）
  └─ 管理后台 /api/admin/*
  └─ 创建/吊销 Managed API Key
  └─ 查看 Analytics / Audit 数据

HTTP_AUTH_TOKEN（Master Token）
  └─ 访问 /api/* HTTP API（save/search/forget/status）
  └─ 无 per-key rate limit 限制
  └─ 不用于 /mcp 握手

Managed API Key（分发给普通用户）
  └─ Admin 通过 POST /api/admin/keys 创建
  └─ 可设置 rate limit、project 隔离
  └─ 可随时吊销/轮转

4. 用户管理

管理员为用户创建 Token

curl -X POST https://memory.example.com/api/admin/keys \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user-alice",
    "scopes": ["memory_save", "memory_search", "memory_forget", "memory_status"],
    "rate_limit": 30,
    "project": "alice-project"
  }'
# 返回: { "id": "...", "key": "em_abc123...", "name": "user-alice" }
# ⚠️ key 仅此一次返回，请安全保存并发给用户

用户配置远程 MCP（推荐：stdio 代理模式）

VS Code / Cursor — 编辑 .vscode/mcp.json：

{
  "servers": {
    "easy-memory": {
      "command": "npx",
      "args": ["-y", "easy-memory@latest"],
      "env": {
        "EASY_MEMORY_URL": "https://memory.example.com",
        "EASY_MEMORY_TOKEN": "em_abc123..."
      }
    }
  }
}

可选：Streamable HTTP 直连（进阶）

{
  "servers": {
    "easy-memory": {
      "type": "http",
      "url": "https://memory.example.com/mcp",
      "headers": {
        "Authorization": "Bearer em_abc123..."
      }
    }
  }
}

⚠️ 若 VS Code 弹出“动态客户端注册”相关 OAuth 提示，请切回上方 stdio 代理模式。

JetBrains IDE — 添加 MCP Server：

{
  "mcpServers": {
    "easy-memory": {
      "url": "https://memory.example.com/mcp",
      "headers": { "Authorization": "Bearer em_abc123..." }
    }
  }
}

Note: Claude Desktop 不原生支持 HTTP 远端连接，需使用远程代理模式（npx + EASY_MEMORY_TOKEN）。参见 远程代理模式。

5. Admin API

所有 Admin API 需要 ADMIN_TOKEN 认证：

Authorization: Bearer <ADMIN_TOKEN>

环境变量

⚠️ Breaking Changes (v0.2.0)

Vertex AI 迁移：GEMINI_PROJECT_ID 新增必填

从 v0.2.0 起，Gemini Embedding 已从 Generative Language API (generativelanguage.googleapis.com) 迁移至 Vertex AI (aiplatform.googleapis.com)。

影响范围： 使用 EMBEDDING_PROVIDER=gemini 或 EMBEDDING_PROVIDER=auto 的所有部署。

必须操作：

1. 新增环境变量 GEMINI_PROJECT_ID（Google Cloud 项目 ID）
2. 可选设置 GEMINI_REGION（默认 us-central1）
3. 确保 GEMINI_API_KEY 有 Vertex AI 权限

# .env 变更示例
EMBEDDING_PROVIDER=gemini          # 或 auto
GEMINI_API_KEY=your-api-key        # 无变化
GEMINI_PROJECT_ID=my-gcp-project   # ⬅️ 新增必填
GEMINI_REGION=us-central1          # 可选，默认 us-central1

纯 Ollama 用户不受影响（EMBEDDING_PROVIDER=ollama 为默认值）。

开发

pnpm install          # 安装依赖
pnpm build            # TypeScript 编译
pnpm typecheck        # 类型检查
pnpm test             # 单元测试 (850+ tests)
pnpm build:web        # 构建 Web UI 前端
pnpm build:all        # 构建后端 + 前端
pnpm dev:web          # 前端开发模式 (HMR)
pnpm test:e2e         # E2E 测试 (需要 Qdrant + Ollama)

项目结构

src/
├── index.ts              # 入口 — 双模式路由
├── container.ts          # 依赖注入容器
├── api/                  # HTTP Shell (Hono)
│   ├── server.ts         # HTTP 路由 + 审计中间件 + SPA 静态文件
│   ├── admin-routes.ts   # Admin API (Key/Ban/Analytics/Audit/Config)
│   ├── auth-routes.ts    # Auth API (Login/Register/Users)
│   ├── admin-auth.ts     # Admin Token 鉴权
│   ├── schemas.ts
│   └── middlewares.ts    # 双层鉴权 (Master + API Key)
├── mcp/                  # MCP Shell (stdio)
│   ├── server.ts         # 本地 MCP Server (stdio + Streamable HTTP)
│   └── remote-server.ts  # 远程代理 MCP Server (EASY_MEMORY_TOKEN)
├── services/             # 核心服务
│   ├── qdrant.ts         # Qdrant 向量数据库
│   ├── embedding.ts      # Embedding 编排 (多引擎 fallback)
│   ├── embedding-providers.ts  # Ollama/Gemini Provider
│   ├── bm25.ts           # BM25 稀疏向量 (混合检索)
│   ├── analytics.ts      # SQLite 用量分析聚合
│   ├── audit.ts          # JSONL 审计日志 (缓冲写入)
│   ├── api-key-manager.ts # API Key 管理 (SHA-256 哈希)
│   ├── ban-manager.ts    # IP/Key 封禁
│   ├── runtime-config.ts # 运行时配置管理
│   └── auth.ts           # 用户认证 (scrypt + JWT)
├── tools/                # MCP Tool 处理器
│   ├── save.ts
│   ├── search.ts
│   ├── forget.ts
│   └── status.ts
├── transport/            # 安全 stdio 传输
│   └── SafeStdioTransport.ts
├── types/                # Schema & 类型
│   ├── schema.ts         # MCP 数据契约
│   ├── admin-schema.ts   # Admin API Schema
│   ├── audit-schema.ts   # 审计日志 Schema
│   └── auth-schema.ts    # Auth/RBAC Schema
└── utils/                # 工具
    ├── hash.ts           # SHA-256 去重
    ├── logger.ts         # stderr JSON 日志
    ├── paths.ts          # 数据文件路径管理 (DATA_DIR)
    ├── sanitize.ts       # 内容脱敏
    ├── rate-limiter.ts   # 速率限制 (全局 + Per-Key)
    ├── ip.ts             # 代理感知 IP 提取
    └── shutdown.ts       # 优雅关闭

web/ # Web UI Admin Panel (React) ├── src/ │ ├── App.tsx # 路由 + 权限守卫 │ ├── api/client.ts # API 客户端 (JWT 自动注入) │ ├── contexts/auth.tsx # Auth 上下文 │ ├── components/ # UI 组件 (Button/Card/Modal/Table...) │ └── pages/ # 页面 (Login/Dashboard/ApiKeys/Bans/ │ # Analytics/AuditLogs/Users/Settings) └── vite.config.ts # Vite 构建配置

---

## Web UI 管理面板

访问 `http://your-server:3080/` 打开 Web UI 管理面板。

### 首次设置

1. 设置环境变量创建管理员账户：
   ```bash
   ADMIN_USERNAME=your-admin-name
   ADMIN_PASSWORD=your-secure-password
   ADMIN_TOKEN=your-admin-token

2. 启动服务后通过浏览器打开 Web UI 3 使用管理员账号密码登录

功能

• Dashboard: 实时概览（请求量/成功率/延迟/系统状态）
• API Keys: 密钥管理（创建/启用/禁用/删除）
• Bans: IP/Key 封禁管理
• Analytics: 用量分析（时间线/操作分布/错误追踪）
• Audit Logs: 审计日志（分页/筛选/导出）
• Users: 用户管理（创建/角色切换/启用禁用/删除）
• Settings: 运行时配置编辑

角色权限

构建

pnpm build:web    # 构建前端到 dist/web/
pnpm build:all    # 构建后端 + 前端
pnpm dev:web      # 前端开发模式 (HMR + API 代理)

架构文档

• FEASIBILITY-ANALYSIS.md — 架构决策记录 (ADR)
• AUDIT-LOGGING-WHITEPAPER.md — 后处理架构白皮书（鉴权·审计·管控）
• CORE_SCHEMA.md — 数据契约与绝对红线
• INTEGRATION_GUIDE.md — 多端接入与 Prompt 调教

License

MIT © FlippySun