更新文档，添加本地服务安装说明和配置示例

README.md

@@ -59,25 +59,112 @@ OpenViking 内部调用遵循：
 
 OpenViking session 由请求里的 `session_id` 创建和提交。`/memory-system/search` 的 OpenViking 分支固定调用 OpenViking `/api/v1/search/search`，`target_uri` 可选，默认是 `viking://user/memories`，并默认传 `level: 2`、`score_threshold: 0.8`。
 
-## 安装
+## 本地三服务安装
+
+Memory Gateway 需要先连上两个后端服务。默认本地端口约定：
+
+| 服务 | 默认地址 | 作用 |
+|---|---|---|
+| OpenViking | `http://127.0.0.1:1933` | session、archive、long-term memory、resources、semantic search |
+| EverOS EverCore | `http://127.0.0.1:1995` | profile、episodic memory、recall |
+| Memory Gateway | `http://127.0.0.1:1934` | 对业务方暴露统一 `/memory-system` API |
+
+### 安装 OpenViking
+
+OpenViking 可以直接用 `pip install` 安装，不需要 clone 源码。Memory Gateway 只依赖它暴露 HTTP API 和一个服务端 root key：
 
 ```bash
-cd /home/tom/memory-gateway
+python -m venv /Users/tom/.venvs/openviking
+source /Users/tom/.venvs/openviking/bin/activate
+pip install -U pip
+pip install openviking --upgrade --force-reinstall
+```
+
+如果本机已经有 OpenViking 源码或已安装的 `openviking-server`，可以跳过安装，直接确认 `openviking-server --help` 可用。
+
+### 安装 EverOS / EverCore
+
+Memory Gateway 使用 EverOS 里的 EverCore HTTP 服务。按 [EverOS / EverCore Quick Start](https://github.com/EverMind-AI/EverOS#evercore)：
+
+```bash
+git clone https://github.com/EverMind-AI/EverOS.git /Users/tom/projects/EverOS
+cd /Users/tom/projects/EverOS/methods/EverCore
+
+# 需要 Docker 和 Python 3.12。
+cp /Users/tom/projects/memory-gateway/everos.env.example .env
+# 编辑 .env，至少填入实际可用的 LLM_API_KEY 和 VECTORIZE_API_KEY。
+
+docker compose up -d
+uv sync
+```
+
+如果 EverOS 已经在本机存在，只需要进入 `methods/EverCore` 并补齐 `.env`。
+
+### 安装 Memory Gateway
+
+```bash
+cd /Users/tom/projects/memory-gateway
 python -m venv .venv
 source .venv/bin/activate
 pip install -U pip
 pip install -e ".[dev]"
 ```
 
-## 配置
+也可以用 `uv`：
-
-复制配置模板：
 
 ```bash
+uv sync --extra dev
+```
+
+## 配置文件
+
+### OpenViking 配置
+
+Memory Gateway 仓库内提供 OpenViking 配置模板：
+
+```bash
+mkdir -p ~/.openviking
+cp /Users/tom/projects/memory-gateway/openviking.ov.conf.example ~/.openviking/ov.conf
+```
+
+然后编辑 `~/.openviking/ov.conf`，至少替换：
+
+| 占位符 | 含义 |
+|---|---|
+| `<OPENVIKING_ROOT_KEY>` | OpenViking root key；必须和 Memory Gateway `config.yaml` 里的 `openviking.api_key` 一致 |
+| `<EMBEDDING_PROVIDER>` / `<EMBEDDING_API_BASE>` / `<EMBEDDING_API_KEY>` / `<EMBEDDING_MODEL>` | OpenViking embedding provider 配置 |
+| `<VLM_PROVIDER>` / `<VLM_API_BASE>` / `<VLM_API_KEY>` / `<VLM_MODEL>` | OpenViking VLM provider 配置 |
+| `<RERANK_PROVIDER>` / `<RERANK_API_BASE>` / `<RERANK_API_KEY>` / `<RERANK_MODEL>` | OpenViking rerank provider 配置 |
+
+配置好后先跑一次：
+
+```bash
+openviking-server doctor
+```
+
+`root_api_key` 只放在 OpenViking 和 Memory Gateway 的服务端配置里。业务调用方不要传 root key。
+
+### EverOS / EverCore 配置
+
+Memory Gateway 仓库内也提供 EverOS / EverCore 的 `.env` 模板。复制到 EverCore 目录：
+
+```bash
+cd /Users/tom/projects/EverOS/methods/EverCore
+cp /Users/tom/projects/memory-gateway/everos.env.example .env
+```
+
+然后编辑 `.env`，至少填入 `LLM_API_KEY`、`LLM_MODEL`、`VECTORIZE_API_KEY`、`EMBEDDING_MODEL` 和 `RERANK_MODEL`。Docker 依赖地址默认使用模板里的本地 compose 端口；如果改过 EverCore 的 compose 配置，需要同步修改 `.env`。
+
+### Memory Gateway 配置
+
+复制 Gateway 配置模板：
+
+```bash
+cd /Users/tom/projects/memory-gateway
 cp config.example.yaml config.yaml
 ```
 
-主要配置：
+然后编辑 `config.yaml`：
 
 ```yaml
 server:
@@ -87,7 +174,7 @@ server:
 
 openviking:
   url: "http://127.0.0.1:1933"
-  api_key: "your-secret-root-key"
+  api_key: "<OPENVIKING_ROOT_KEY>"
   timeout: 30
   verify_ssl: true
 
@@ -99,7 +186,7 @@ everos:
   health_path: "/health"
 
 storage:
-  sqlite_path: "/home/tom/memory-gateway/memory_system_api.sqlite3"
+  sqlite_path: "./memory_system_api.sqlite3"
 ```
 
 环境变量也可以覆盖部分配置：
@@ -117,12 +204,41 @@ storage:
 
 ## 启动
 
-先启动 OpenViking 和 EverOS，再启动 Memory System API：
+按依赖顺序启动三个服务。
+
+终端 1：启动 OpenViking。
 
 ```bash
+source /Users/tom/.venvs/openviking/bin/activate
+openviking-server --config ~/.openviking/ov.conf
+```
+
+如果使用 Docker 方式运行 OpenViking，确认对 Memory Gateway 暴露的是 `1933` 端口，避免和 Memory Gateway 的 `1934` 端口冲突。
+
+终端 2：启动 EverOS / EverCore。
+
+```bash
+cd /Users/tom/projects/EverOS/methods/EverCore
+docker compose up -d
+uv run python src/run.py --port 1995
+```
+
+终端 3：启动 Memory Gateway。
+
+```bash
+cd /Users/tom/projects/memory-gateway
+source .venv/bin/activate
 python -m memory_system_api.server --config config.yaml --host 0.0.0.0 --port 1934
 ```
 
+健康检查：
+
+```bash
+curl -sS http://127.0.0.1:1933/health
+curl -sS http://127.0.0.1:1995/health
+curl -sS http://127.0.0.1:1934/memory-system/health
+```
+
 如果 `server.api_key` 非空，所有请求还要加：
 
 ```bash

config.example.yaml

@@ -1,15 +1,21 @@
+# Copy this file to config.yaml and replace placeholders with local values.
+# Do not commit config.yaml because it may contain backend root keys.
+
 server:
   host: "127.0.0.1"
   port: 1934
+  # Optional key that protects Memory Gateway itself. Leave empty for local dev.
   api_key: ""
 
 openviking:
+  # OpenViking HTTP server. The api_key must match server.root_api_key in ov.conf.
   url: "http://127.0.0.1:1933"
-  api_key: "your-secret-root-key"
+  api_key: "<OPENVIKING_ROOT_KEY>"
   timeout: 30
   verify_ssl: true
 
 everos:
+  # EverOS EverCore HTTP server.
   url: "http://127.0.0.1:1995"
   api_key: ""
   timeout: 180
@@ -17,7 +23,7 @@ everos:
   health_path: "/health"
 
 storage:
-  sqlite_path: "/home/tom/memory-gateway/memory_system_api.sqlite3"
+  sqlite_path: "./memory_system_api.sqlite3"
 
 logging:
   level: "INFO"

everos.env.example

@@ -0,0 +1,77 @@
+# Copy this file to ./EverOS/methods/EverCore/.env.
+# Do not commit the copied .env file because it contains provider keys.
+
+# Required by EverCore for memory extraction.
+LLM_PROVIDER=openai
+LLM_MODEL=<LLM_MODEL_NAME>
+LLM_BASE_URL=<LLM_BASE_URL>
+LLM_API_KEY=<LLM_API_KEY>
+LLM_TEMPERATURE=0.3
+LLM_MAX_TOKENS=1000000
+
+# Required by EverCore for embedding and rerank.
+
+VECTORIZE_PROVIDER=vllm
+VECTORIZE_API_KEY=<EMBEDDING_API_KEY>
+VECTORIZE_BASE_URL=<EMBEDDING_BASE_URL>
+VECTORIZE_MODEL=Qwen3-VL-Embedding-2B
+VECTORIZE_FALLBACK_PROVIDER=none
+VECTORIZE_TIMEOUT=30
+VECTORIZE_MAX_RETRIES=3
+VECTORIZE_BATCH_SIZE=10
+VECTORIZE_MAX_CONCURRENT=5
+VECTORIZE_ENCODING_FORMAT=float
+VECTORIZE_DIMENSIONS=1024
+
+RERANK_PROVIDER=vllm
+RERANK_API_KEY=<RERANK_API_KEY>
+RERANK_BASE_URL=<RERANK_BASE_URL>
+RERANK_MODEL=Qwen3-VL-Reranker-2B
+
+# EverCore API server.
+API_BASE_URL=http://localhost:1995
+LOG_LEVEL=INFO
+ENV=dev
+PYTHONASYNCIODEBUG=1
+MEMORY_LANGUAGE=en
+
+# Docker compose default dependencies.
+
+# ===================
+# Redis Configuration
+# ===================
+
+TENANT_SINGLE_TENANT_ID=t_tom
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_DB=8
+REDIS_SSL=false
+
+# ===================
+# MongoDB Configuration
+# ===================
+
+MONGODB_HOST=localhost
+MONGODB_PORT=27017
+MONGODB_USERNAME=admin
+MONGODB_PASSWORD=memsys123
+MONGODB_DATABASE=memsys
+MONGODB_URI_PARAMS=socketTimeoutMS=15000&authSource=admin
+
+# ===================
+# Elasticsearch Configuration
+# ===================
+
+ES_HOSTS=http://localhost:19200
+ES_USERNAME=
+ES_PASSWORD=
+ES_VERIFY_CERTS=false
+SELF_ES_INDEX_NS=memsys
+
+# ===================
+# Milvus Vector Database Configuration
+# ===================
+
+MILVUS_HOST=localhost
+MILVUS_PORT=19530
+SELF_MILVUS_COLLECTION_NS=memsys

openviking.ov.conf.example

@@ -0,0 +1,44 @@
+{
+  "server": {
+    "host": "0.0.0.0",
+    "port": 1933,
+    "auth_mode": "api_key",
+    "root_api_key": "<OPENVIKING_ROOT_KEY>",
+    "cors_origins": ["*"]
+  },
+  "storage": {
+    "workspace": "/Users/tom/projects/openviking_workspace",
+    "agfs": {
+      "backend": "local"
+    },
+    "vectordb": {
+      "name": "context",
+      "backend": "local"
+    }
+  },
+  "memory": {
+    "version": "v2",
+    "agent_scope_mode": "user+agent"
+  },
+  "embedding": {
+    "dense": {
+      "provider": "<EMBEDDING_PROVIDER>",
+      "api_base": "<EMBEDDING_API_BASE>",
+      "api_key": "<EMBEDDING_API_KEY>",
+      "model": "<EMBEDDING_MODEL>",
+      "dimension": 1024
+    }
+  },
+  "vlm": {
+    "provider": "<VLM_PROVIDER>",
+    "api_base": "<VLM_API_BASE>",
+    "api_key": "<VLM_API_KEY>",
+    "model": "<VLM_MODEL>"
+  },
+  "rerank": {
+    "provider": "<RERANK_PROVIDER>",
+    "api_base": "<RERANK_API_BASE>",
+    "api_key": "<RERANK_API_KEY>",
+    "model": "<RERANK_MODEL>"
+  }
+}