Easy Memory

Easy Memory

AI の記憶をセッション間、プロジェクト間で永続化します。 Qdrant ベクトルデータベースと公式ベクトルモデル（OpenAI-compatible relay 経由での接続に対応）／Ollama を基盤とする MCP 記憶サービスです。

Easy Memory は、デュアルシェルアーキテクチャを提供します。

• MCP Shell — stdio を介して Claude Desktop ／ Cursor ／ VS Code などの IDE と直接通信します
• HTTP Shell — RESTful API で、リモートアクセスや複数クライアントでの記憶の共有に対応します

---

目次

• クイックスタート
• クライアント設定
• 30 秒でトラブルシューティング（リモート優先）
• HTTP API
• MCP ツール
• 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）」の手順に進んでください。

前提条件

依存関係	バージョン	説明
Node.js	≥ 20	MCP サーバーを実行します
Docker	≥ 24	Qdrant + Ollama を実行します（またはリモートモードを使用して省略できます）

💡 リモートプロキシモードではローカルの Qdrant／Ollama は不要です
リモートの Easy Memory サービス（例：memory.zhiz.chat）をお持ちの場合は、EASY_MEMORY_TOKEN と EASY_MEMORY_URL を設定するだけで利用できます。リモートプロキシモードを参照してください。

基本サービスの準備（Qdrant + Ollama）

Easy Memory は、2 つの基本サービスに依存します。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 サービス経由で接続します。

1. /v1/embeddings に対応した互換サービスと API Key を用意します
2. .env.example の OPENAI_EMBEDDING_* 設定項目を使用します
3. 環境変数を設定します。

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 は、現在の Qdrant dense vector collection と一致するよう、dimensions=1024 を自動で送信します。

互換方式：Google 公式 Gemini リモート Embedding の設定

Google 公式 Vertex AI を利用したい場合も、Gemini Embedding を引き続き使用できます。

1. Google AI Studio にアクセスして API Key を取得します
2. Google Cloud Console でプロジェクトを作成し、aiplatform.googleapis.com を有効にします
3. 環境変数を設定します。

EMBEDDING_PROVIDER=auto
GEMINI_API_KEY=AIzaSy...
GEMINI_PROJECT_ID=my-gcp-project
GEMINI_REGION=us-central1

auto モードでは、Gemini リクエストが失敗した場合（レート制限／タイムアウト）、サービスが中断しないよう Ollama に自動でフォールバックします。

方法 1：npx で直接実行（MCP モード）

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

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

方法 2：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

方法 3：ソースからビルド

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 → Add を編集します。

{
  "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"
      }
    }
  }
}

2 つの環境変数を設定するだけで、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 作为包管理器",
    "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	mcp	実行モード：mcp / http
QDRANT_URL	http://localhost:6333	Qdrant の接続先
QDRANT_API_KEY	easy-memory-dev	Qdrant API Key
EMBEDDING_PROVIDER	ollama	Embedding エンジン：ollama / gemini / openai / auto / openai-auto。セルフホスト可能な環境ではデフォルトでローカルの Ollama を使用します。推奨されるリモート方式を使うには、openai-auto を明示的に設定してください
OLLAMA_BASE_URL	http://localhost:11434	Ollama のアドレス
OLLAMA_MODEL	bge-m3	Ollama のモデル名（1024 次元）
OLLAMA_TIMEOUT_MS	120000	Ollama リクエストのタイムアウト（ms）。モデルの初回読み込みには時間がかかります
OPENAI_EMBEDDING_API_KEY	—	OpenAI 公式ベクトルモデルのリレー用 API Key（openai / openai-auto モードでは必須）
OPENAI_EMBEDDING_BASE_URL	https://api.vectorengine.ai/v1	リレーのベース URL、または完全な /embeddings エンドポイント
OPENAI_EMBEDDING_MODEL	text-embedding-3-small	OpenAI 公式ベクトルモデルのデフォルト名（リクエスト時に dimensions=1024 を自動的に付加）
GEMINI_API_KEY	—	Google Cloud Vertex AI API Key（gemini / auto モードでは必須）
GEMINI_PROJECT_ID	—	Google Cloud Project ID（gemini / auto モードでは必須）
GEMINI_REGION	us-central1	Google Cloud Vertex AI のリージョン
GEMINI_MODEL	gemini-embedding-001	Gemini Embedding モデル
DEFAULT_PROJECT	default	デフォルトのプロジェクト識別子
HTTP_PORT	3080	HTTP Shell のリッスンポート
HTTP_HOST	127.0.0.1	HTTP Shell のリッスンアドレス
HTTP_AUTH_TOKEN	—	HTTP API Bearer Token
TRUST_PROXY	false	リバースプロキシの X-Forwarded-* ヘッダーを信頼する
REQUIRE_TLS	false	HTTPS 以外のリクエストを拒否します（TRUST_PROXY=true が必要）
ADMIN_TOKEN	—	Admin API Token（空欄の場合は管理画面を無効化）
ADMIN_USERNAME	—	Admin ユーザー名 — 初回起動時に管理者アカウントを自動作成
ADMIN_PASSWORD	—	Admin パスワード — ADMIN_USERNAME と併用
DATA_DIR	$HOME	データファイルの保存ディレクトリ（Docker では /data に設定し、Volume をマウント）
RATE_LIMIT_PER_MINUTE	60	全体のレート制限（回／分）
GEMINI_MAX_PER_HOUR	200	Gemini の1時間あたりの最大呼び出し回数
GEMINI_MAX_PER_DAY	2000	Gemini の1日あたりの最大呼び出し回数
EASY_MEMORY_TOKEN	—	リモートプロキシモード：API Key（設定するとリモートプロキシが有効になり、ローカルサービスをスキップ）
EASY_MEMORY_URL	—	リモートプロキシモード：リモート Easy Memory サービスの URL

---

⚠️ 破壊的変更（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             # 单元测试 (940+ 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/OpenAI-compatible 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 管理パネル（React） ├── src/ │ ├── App.tsx # ルーティング＋権限ガード │ ├── api/client.ts # API クライアント（JWT を自動注入） │ ├── contexts/auth.tsx # 認証コンテキスト │ ├── 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 管理者のユーザー名とパスワードでログインします

機能

• ダッシュボード：リアルタイムの概要（リクエスト数／成功率／レイテンシ／システム状態）
• API キー：キー管理（作成／有効化／無効化／削除）
• 禁止設定：IP／キーのブロック管理
• 分析：使用状況の分析（タイムライン／操作の内訳／エラー追跡）
• 監査ログ：監査ログ（ページ分割／絞り込み／エクスポート）
• ユーザー：ユーザー管理（作成／ロール切り替え／有効化・無効化／削除）
• 設定：実行時設定の編集

ロールと権限

権限	Admin	User
ユーザー管理	✅	❌
API キー管理	✅	❌
禁止設定の管理	✅	❌
設定の変更	✅	❌
分析の閲覧	✅	✅
監査ログ	✅	✅
メモリ操作	✅	✅

ビルド

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 — マルチクライアント連携とプロンプトの調整

---

ライセンス

MIT © FlippySun