easy-memory

v0.5.8

Published

3 days ago

MCP persistent memory service — let AI assistants remember across sessions. Powered by Qdrant vector search + official embeddings (via OpenAI-compatible relay or Gemini Vertex AI) with Ollama fallback and hybrid retrieval (vector + BM25).

Downloads

1,301

Easy Memory

让 AI 跨会话、跨项目持久化记忆。 基于 Qdrant 向量数据库 + 官方向量模型（支持经 OpenAI-compatible relay 接入）/ Ollama 的 MCP 记忆服务。

Easy Memory 提供双 Shell 架构：

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

快速开始

前置条件

| 依赖 | 版本 | 说明 | | ------- | ---- | ------------------------------------------ | | Node.js | ≥ 20 | 运行 MCP Server | | Docker | ≥ 24 | 运行 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

默认远端方案：官方 OpenAI 向量模型（经第三方 relay 接入）

如果你需要更高质量的向量或本地资源不足，项目默认推荐启用 官方 OpenAI 向量模型，但通过兼容 relay 服务接入：

准备支持 /v1/embeddings 的兼容服务与 API Key
使用 .env.example 中的 OPENAI_EMBEDDING_* 配置项
设置环境变量：

EMBEDDING_PROVIDER=openai-auto
OPENAI_EMBEDDING_API_KEY=sk-...
OPENAI_EMBEDDING_BASE_URL=https://api.vectorengine.ai/v1
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

openai-auto 模式下，远端官方 OpenAI 向量模型（经 relay 接入）优先，Ollama 自动兜底。
easy-memory 会自动发送 dimensions=1024，确保与当前 Qdrant dense vector collection 保持一致。

兼容：配置 Google 官方 Gemini 远端 Embedding

如果你更偏好 Google 官方 Vertex AI，也仍然可以继续使用 Gemini Embedding：

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

EMBEDDING_PROVIDER=auto
GEMINI_API_KEY=AIzaSy...
GEMINI_PROJECT_ID=my-gcp-project
GEMINI_REGION=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   # 默认即本地 Ollama；如需远端 relay，再改成 EMBEDDING_PROVIDER=openai-auto 并填写 OPENAI_EMBEDDING_API_KEY
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 根键速查（避免“工具列表为空”）

| 客户端 | MCP 配置根键 | | ------------------------ | ------------ | | VS Code (GitHub Copilot) | servers | | Claude Desktop / Cursor | mcpServers |

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 秒排障（远端优先）

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

未带 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 作为包管理器",
    "source": "manual",
    "fact_type": "decision",
    "tags": ["tooling", "pnpm"]
  }'

请求字段：

| 字段 | 类型 | 必填 | 说明 | | ------------ | ---------- | ---- | -------------------------------------------------------------------------------- | | content | string | ✅ | 记忆内容 | | project | string | ❌ | 项目标识（默认 default） | | source | string | ❌ | 来源：conversation / file_watch / manual | | fact_type | string | ❌ | 类型：verified_fact / decision / hypothesis / discussion / observation | | tags | string[] | ❌ | 标签列表 | | confidence | number | ❌ | 置信度 0-1（默认 0.7） |

`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}'

请求字段：

| 字段 | 类型 | 必填 | 说明 | | ------------------ | ---------- | ---- | ---------------------------------------------------------------- | | query | string | ✅ | 搜索查询 | | project | string | ❌ | 项目标识 | | limit | number | ❌ | 返回数量 1-20（默认 5） | | threshold | number | ❌ | 相似度阈值 0-1（默认 0.55） | | include_outdated | boolean | ❌ | 是否包含已归档记忆 | | cross_model | boolean | ❌ | 是否允许跨模型搜索（默认关闭，排查 fallback / 迁移时可显式开启） | | tags | string[] | ❌ | 按标签过滤 |

`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 暴露 8 个 MCP Tools。

其中：

easy_memory_* 是 preferred discoverability alias，优先推荐给支持工具枚举的 AI / MCP 客户端使用
memory_* 继续保留，作为向后兼容名称

| Tool | 说明 | | -------------------- | ----------------------------------- | | easy_memory_save | 保存记忆到向量库（preferred） | | easy_memory_search | 语义检索相关记忆（preferred） | | easy_memory_forget | 归档/标记过时/删除记忆（preferred） | | easy_memory_status | 系统健康状态（preferred） | | memory_save | 保存记忆到向量库（兼容名） | | memory_search | 语义检索相关记忆（兼容名） | | memory_forget | 归档/标记过时/删除记忆（兼容名） | | memory_status | 系统健康状态（兼容名） |

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.5.8

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

VPS 生产部署

前置条件

| 需求 | 说明 | | ------ | ----------------------------------- | | VPS | 2C/4G+ 内存（Ollama bge-m3 需 ~2G） | | 域名 | A 记录解析到 VPS IP | | Docker | Docker ≥ 24 + Docker Compose v2 | | 端口 | 80/443 对外开放（反向代理用） |

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>

| 功能 | 方法 | 路径 | | ------------ | ----------- | ------------------------------- | | 创建 Key | POST | /api/admin/keys | | 列出全部 Key | GET | /api/admin/keys | | 查看 Key | GET | /api/admin/keys/:id | | 更新 Key | PATCH | /api/admin/keys/:id | | 吊销 Key | DELETE | /api/admin/keys/:id | | 轮换 Key | POST | /api/admin/keys/:id/rotate | | 封禁 IP | POST | /api/admin/bans | | 列出 IP 封禁 | GET | /api/admin/bans | | 解封 IP | DELETE | /api/admin/bans/:ip | | 系统总览 | GET | /api/admin/analytics/overview | | 用户用量 | GET | /api/admin/analytics/users | | 搜索命中率 | GET | /api/admin/analytics/hit-rate | | 审计日志 | GET | /api/admin/audit/logs | | 导出日志 | GET | /api/admin/audit/export | | 运行时配置 | GET/PATCH | /api/admin/config |

环境变量

.env.example 是当前仓库对外公开的权威配置模板。
新增配置项会优先落在 .env.example，再同步到本表和部署示例。

| 变量 | --------------------------- | EASY_MEMORY_MODE | QDRANT_URL | QDRANT_API_KEY | EMBEDDING_PROVIDER | OLLAMA_BASE_URL | OLLAMA_MODEL | OLLAMA_TIMEOUT_MS | OPENAI_EMBEDDING_API_KEY | OPENAI_EMBEDDING_BASE_URL | OPENAI_EMBEDDING_MODEL | GEMINI_API_KEY | GEMINI_PROJECT_ID | GEMINI_REGION | GEMINI_MODEL | DEFAULT_PROJECT | HTTP_PORT | HTTP_HOST | HTTP_AUTH_TOKEN | TRUST_PROXY | REQUIRE_TLS | ADMIN_TOKEN | ADMIN_USERNAME | ADMIN_PASSWORD | DATA_DIR | RATE_LIMIT_PER_MINUTE | GEMINI_MAX_PER_HOUR | GEMINI_MAX_PER_DAY | EASY_MEMORY_TOKEN | EASY_MEMORY_URL | 默认值 | 说明 | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | mcp | 运行模式：mcp / http | | http://localhost:6333 | Qdrant 连接地址 | | easy-memory-dev | Qdrant API Key | | ollama | Embedding 引擎：ollama / gemini / openai / auto / openai-auto；自托管默认走本地 Ollama，如需推荐远端方案请显式设置 openai-auto | | http://localhost:11434 | Ollama 地址 | | bge-m3 | Ollama 模型名（1024 维） | | 120000 | Ollama 请求超时（ms），首次加载模型需较长时间 | | — | 官方 OpenAI 向量模型 relay 的 API Key（openai/openai-auto 模式必填） | | https://api.vectorengine.ai/v1 | relay base URL 或完整 /embeddings 端点 | | text-embedding-3-small | 默认官方向量模型名（请求时自动带 dimensions=1024） | | — | Google Cloud Vertex AI API Key（gemini/auto 模式必填） | | — | Google Cloud Project ID（gemini/auto 模式必填） | | us-central1 | Google Cloud Vertex AI 区域 | | gemini-embedding-001 | Gemini Embedding 模型 | | default | 默认项目标识 | | 3080 | HTTP Shell 监听端口 | | 127.0.0.1 | HTTP Shell 监听地址 | | — | HTTP API Bearer Token | | false | 信任反向代理 X-Forwarded-* 头 | | false | 拒绝非 HTTPS 请求（需 TRUST_PROXY=true） | | — | Admin API Token（留空则禁用管理后台） | | — | Admin 用户名 — 首次启动时自动创建管理员账户 | | — | Admin 密码 — 与 ADMIN_USERNAME 配合使用 | | $HOME | 数据文件存储目录（Docker 中设为 /data 并挂载 Volume） | | 60 | 全局速率限制（次/分钟） | | 200 | Gemini 每小时最大调用数 | | 2000 | Gemini 每日最大调用数 | | — | 远程代理模式：API Key（设置后启用远程代理，跳过本地服务） | | — | 远程代理模式：远端 Easy Memory 服务 URL |

⚠️ 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 的所有部署。

必须操作：

新增环境变量 GEMINI_PROJECT_ID（Google Cloud 项目 ID）
可选设置 GEMINI_REGION（默认 us-central1）
确保 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 verify:local     # 本地提交前快速校验 (typecheck + test)
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

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

功能

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

角色权限

| 权限 | Admin | User | | ------------ | :---: | :--: | | 用户管理 | ✅ | ❌ | | API Key 管理 | ✅ | ❌ | | Ban 管理 | ✅ | ❌ | | 配置修改 | ✅ | ❌ | | 分析查看 | ✅ | ✅ | | 审计日志 | ✅ | ✅ | | 记忆操作 | ✅ | ✅ |

构建

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 调教

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Easy Memory

目录

快速开始

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

前置条件

基础服务准备（Qdrant + Ollama）

默认远端方案：官方 OpenAI 向量模型（经第三方 relay 接入）

兼容：配置 Google 官方 Gemini 远端 Embedding

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

方式二：Docker Compose 一键部署

方式三：从源码构建

客户端配置

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

Claude Desktop

Cursor

VS Code (GitHub Copilot)

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

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

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

远程 HTTP 模式

30 秒排障（远端优先）

HTTP API

GET /health

POST /api/save

POST /api/search

POST /api/forget

GET /api/status

MCP Tools

Docker 部署

开发环境

生产环境

预构建镜像

VPS 生产部署

前置条件

1. 部署服务

2. 反向代理 (HTTPS)

Caddy（推荐 — 自动 HTTPS）

Nginx（手动证书）

3. 三层认证架构

4. 用户管理

管理员为用户创建 Token

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

可选：Streamable HTTP 直连（进阶）

5. Admin API

环境变量

⚠️ Breaking Changes (v0.2.0)

Vertex AI 迁移：GEMINI_PROJECT_ID 新增必填

开发

项目结构

功能

角色权限

构建

架构文档

License

`GET /health`

`POST /api/save`

`POST /api/search`

`POST /api/forget`

`GET /api/status`

Vertex AI 迁移：`GEMINI_PROJECT_ID` 新增必填