diff --git a/README.md b/README.md
index 29fe38f..3cc366c 100644
--- a/README.md
+++ b/README.md
@@ -26,16 +26,263 @@ Memory Gateway 是一个通用记忆网关，用于给 AI agent / harness 提供
 docs/generic-memory-gateway-design.md
 ```
 
-## 架构
+## 总体架构
+
+```mermaid
+flowchart LR
+  Agent[AI Agents / Hermes / OpenClaw / Nanobot] -->|HTTP / MCP / Plugin Tools / Skill Scripts| Gateway[Memory Gateway]
+  Gateway --> Auth[Auth + ACL + Namespace Router]
+  Gateway --> SQLite[(SQLite Metadata Store)]
+  Gateway --> OV[OpenViking Context Layer]
+  Gateway --> Ever[EverMemOS Consolidation Service]
+  Gateway --> Obsidian[Obsidian Markdown Vault]
+  Gateway --> LLM[OpenAI-compatible LLM]
+  OV --> OVStore[(OpenViking memory/resource/index)]
+  Ever -->|promote stable memory| SQLite
+  Ever -->|review drafts| Obsidian
+  Obsidian --> Human[Human Review / Manual Editing]
+```
+
+模块职责：
+
+- **Memory Gateway**：统一入口，提供 REST、MCP RPC、Hermes/OpenClaw plugin 所需的 `/v1` API；负责 user context、namespace 展开、visibility/ACL、audit、短期 episode 写入和 session commit 编排。
+- **OpenViking**：context/resource/memory 检索层；Gateway 会把允许访问的 namespace 展开后交给 OpenViking 搜索。
+- **EverMemOS**：长期记忆整理层；从 session episodes 中提取稳定候选，去重、合并、冲突检测，并决定是否 promote 到长期记忆或进入 review。
+- **Obsidian Vault**：人工可维护的 Markdown 前台；保存上传文档、review draft、高价值可审查知识。不要把所有原始对话直接写入 Obsidian。
+- **Hermes skill**：脚本式、显式调用入口，适合人工/agent 明确执行搜索、上传、commit。
+- **Agent plugin**：Hermes/OpenClaw runtime adapter，注册 `memory_gateway` toolset 和 hooks，可在真实对话中自动 search、append episode、可选 commit。
+
+## 全新服务器部署总览
+
+以下步骤假设目标服务器是 Linux，初始没有 Python 环境、OpenViking、EverMemOS、Memory Gateway、Obsidian Vault 或 Hermes Agent。示例路径使用 `/opt`，可按实际环境替换。
+
+推荐目录：
 
 ```text
-Agent / Harness / CLI
-  -> Memory Gateway REST / MCP
-  -> OpenViking memory / resource
-  -> Obsidian markdown vault
-  -> OpenAI-compatible LLM summary
+/opt/
+├── OpenViking/                  # OpenViking 项目和 venv
+└── memory-gateway/              # 本项目
+    ├── .venv/
+    ├── config.yaml              # 本机配置，包含密钥，不提交
+    ├── data/
+    │   └── memory_gateway.sqlite3
+    └── obsidian-vault/
+        ├── 01_Knowledge/Uploaded/
+        └── Reviews/Queue/
 ```
 
+### 1. 安装系统依赖
+
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+  git curl rsync build-essential \
+  python3 python3-venv python3-pip
+```
+
+可选安装 `uv`，后续 Python 环境会更快：
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+如果服务器不能访问公网，请用内部镜像源安装 Python 依赖，并把 OpenViking、Hermes 和本项目代码放到内网 Git/制品库。
+
+### 2. 安装 OpenViking
+
+OpenViking 不在本仓库内，需要按 OpenViking 项目的官方安装方式部署。最终目标是服务器上可以运行：
+
+```bash
+openviking-server --host 127.0.0.1 --port 1933
+```
+
+一种常见安装形态：
+
+```bash
+cd /opt
+git clone https://github.com/volcengine/OpenViking.git
+cd /opt/OpenViking
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install -e .
+```
+
+启动：
+
+```bash
+source /opt/OpenViking/.venv/bin/activate
+openviking-server --host 127.0.0.1 --port 1933
+```
+
+健康检查：
+
+```bash
+curl http://127.0.0.1:1933/health
+```
+
+说明：OpenViking 建议先只绑定 `127.0.0.1`，由 Memory Gateway 统一对外暴露 API。
+
+### 3. 安装 Memory Gateway
+
+```bash
+cd /opt
+git clone https://gitea.bwgdi.com/tomtan/memory-gateway.git memory-gateway
+cd /opt/memory-gateway
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install -e ".[dev]"
+```
+
+创建目录和配置：
+
+```bash
+mkdir -p /opt/memory-gateway/data
+mkdir -p /opt/memory-gateway/obsidian-vault/01_Knowledge/Uploaded
+mkdir -p /opt/memory-gateway/obsidian-vault/Reviews/Queue
+cp config.example.yaml config.yaml
+```
+
+修改 `config.yaml`：
+
+```yaml
+server:
+  host: "0.0.0.0"
+  port: 1934
+  api_key: "<CHANGE_ME_LONG_RANDOM_KEY>"
+
+openviking:
+  url: "http://127.0.0.1:1933"
+  api_key: "<OPENVIKING_KEY_IF_REQUIRED>"
+
+evermemos:
+  enabled: true
+  url: "http://127.0.0.1:1995"
+  fallback_to_local: true
+
+obsidian:
+  vault_path: "/opt/memory-gateway/obsidian-vault"
+  knowledge_dir: "01_Knowledge/Uploaded"
+  review_dir: "Reviews/Queue"
+
+storage:
+  backend: "sqlite"
+  sqlite_path: "/opt/memory-gateway/data/memory_gateway.sqlite3"
+```
+
+`config.yaml` 被 `.gitignore` 忽略，不应提交。
+
+### 4. 安装/启动 EverMemOS
+
+本项目内置一个 POC 级 EverMemOS-compatible 服务，适合单机验证：
+
+```bash
+cd /opt/memory-gateway
+source .venv/bin/activate
+python -m memory_gateway.evermemos_service \
+  --config /opt/memory-gateway/config.yaml \
+  --host 127.0.0.1 \
+  --port 1995
+```
+
+健康检查：
+
+```bash
+curl http://127.0.0.1:1995/health
+```
+
+如果已有独立 EverMemOS 服务，把 `config.yaml` 中的 `evermemos.url`、`api_key`、`consolidate_path` 改为远程服务即可。Memory Gateway 会在 `/v1/sessions/{session_id}/commit` 时调用它。
+
+### 5. 启动 Memory Gateway
+
+```bash
+cd /opt/memory-gateway
+source .venv/bin/activate
+python -m memory_gateway.server --config /opt/memory-gateway/config.yaml
+```
+
+健康检查：
+
+```bash
+curl -H "X-API-Key: <CHANGE_ME_LONG_RANDOM_KEY>" http://127.0.0.1:1934/health
+curl -H "X-API-Key: <CHANGE_ME_LONG_RANDOM_KEY>" http://127.0.0.1:1934/v1/evermemos/health
+```
+
+生产建议用 systemd/supervisor 管理 OpenViking、EverMemOS 和 Memory Gateway 三个进程，并通过 Nginx/Caddy/内网负载均衡做 TLS 和访问控制。
+
+### 6. Obsidian Vault
+
+服务器端不要求安装 Obsidian 桌面应用。这里的 Obsidian Vault 本质是 Markdown 目录：
+
+```text
+/opt/memory-gateway/obsidian-vault/
+├── 01_Knowledge/Uploaded/      # /api/knowledge/upload 转换后的 Markdown
+└── Reviews/Queue/              # EverMemOS 高价值/冲突候选 review draft
+```
+
+如果需要人工维护，可以：
+
+- 用 Obsidian 桌面端通过 SSH/Syncthing/Git 同步这个 vault。
+- 或直接在服务器上编辑 Markdown。
+- 高价值、冲突、低置信度的长期记忆候选优先进 `Reviews/Queue/`，不要直接污染长期记忆。
+
+### 7. 安装 Hermes Agent、Skill 和 Plugin
+
+Hermes Agent 不在本仓库内。先按 Hermes 官方方式安装，确认命令可用：
+
+```bash
+hermes --version
+hermes chat --help
+```
+
+安装 Memory Gateway skill：
+
+```bash
+mkdir -p ~/.hermes/skills/memory-gateway
+rsync -a --delete \
+  /opt/memory-gateway/integrations/hermes/memory-gateway/ \
+  ~/.hermes/skills/memory-gateway/
+```
+
+skill 的特点：
+
+- 通过脚本显式调用 Gateway API。
+- 适合手动或 agent policy 主动执行：搜索、上传、append episode、commit session。
+- skill 本身不会自动记忆每轮对话。
+
+安装 Memory Gateway agent plugin：
+
+```bash
+mkdir -p ~/.hermes/plugins
+ln -s /opt/memory-gateway/plugins/memory-gateway-agent \
+  ~/.hermes/plugins/memory-gateway-agent
+hermes plugins enable memory-gateway-agent
+hermes plugins list
+hermes tools list
+```
+
+plugin 环境变量：
+
+```bash
+export MEMORY_GATEWAY_URL=http://127.0.0.1:1934
+export MEMORY_GATEWAY_API_KEY=<CHANGE_ME_LONG_RANDOM_KEY>
+export MEMORY_GATEWAY_DEFAULT_USER_ID=user_demo
+export MEMORY_GATEWAY_DEFAULT_AGENT_ID=agent_hermes
+export MEMORY_GATEWAY_DEFAULT_WORKSPACE_ID=workspace_demo
+export MEMORY_GATEWAY_AUTO_SEARCH=true
+export MEMORY_GATEWAY_AUTO_APPEND_EPISODE=true
+export MEMORY_GATEWAY_AUTO_COMMIT_SESSION=false
+```
+
+plugin 的特点：
+
+- 向 Hermes 注册 `memory_gateway` toolset。
+- 注册 hooks：`on_session_start`、`pre_llm_call`、`post_llm_call`、`on_session_end`。
+- `pre_llm_call` 自动检索相关记忆。
+- `post_llm_call` 只写摘要型 candidate episode。
+- `on_session_end` 默认不 commit；只有 `MEMORY_GATEWAY_AUTO_COMMIT_SESSION=true` 才提交 session。
+
 ## 目录结构
 
 ```text
@@ -49,78 +296,218 @@ memory-gateway/
 │   └── types.py
 ├── integrations/hermes/
 │   └── memory-gateway/              # 通用 Hermes skill
+├── plugins/
+│   └── memory-gateway-agent/         # Hermes/OpenClaw agent plugin adapter
 ├── obsidian-vault/
 │   ├── 01_Knowledge/Uploaded/       # 上传文档转成的 Markdown
+│   ├── Reviews/Queue/               # EverMemOS review draft
 │   └── 05_Templates/                # 通用知识模板
+├── data/                            # SQLite metadata store，生产建议保留备份
+│   └── memory_gateway.sqlite3
+├── docs/
+│   └── generic-memory-gateway-design.md
 ├── tests/
 ├── config.example.yaml
 └── pyproject.toml
 ```
 
-## 环境
+## 用户隔离、存储与长短期记忆
 
-使用当前虚拟环境：
+### 访问上下文
 
-```bash
-cd /home/tom/memory-gateway
-source /home/tom/OpenViking/.venv/bin/activate
+v1 API 的所有核心读写都应该带上访问上下文：
+
+```json
+{
+  "user_id": "user_demo",
+  "agent_id": "agent_hermes",
+  "workspace_id": "workspace_demo",
+  "session_id": "session_001"
+}
 ```
 
-本地配置文件：
+Gateway 根据这些字段做 namespace 展开和 ACL 判断。不同用户必须使用不同 `user_id`，不同 agent 使用不同 `agent_id`，不同项目或团队空间使用不同 `workspace_id`。
+
+### Namespace 设计
+
+默认可见 namespace 形态：
 
 ```text
-/home/tom/memory-gateway/config.yaml
+user/{user_id}/profile
+user/{user_id}/preferences
+user/{user_id}/long_term
+agent/{agent_id}/memory
+workspace/{workspace_id}/shared
+session/{session_id}/episodic
+global/public
 ```
 
-关键配置：
+隔离规则：
+
+- `private`：默认私有，只允许同一 `user_id` 在 ACL 允许范围内访问。
+- `agent-only`：只允许指定 agent 或 agent namespace 使用。
+- `workspace-shared`：允许 workspace 成员/允许的 agent 使用。
+- `global`：公共知识，谨慎使用，不存放个人信息。
+- `session/{session_id}/episodic`：短期 session 记忆，默认只在当前 session 上下文中使用。
+
+### 用户记忆存储位置
+
+| 数据 | 存储位置 | 说明 |
+| --- | --- | --- |
+| users/profiles/memories/episodes/audit metadata | SQLite `storage.sqlite_path` | Gateway v1 的主 metadata store，负责隔离、ACL、audit、短期 episode 和长期 memory 记录 |
+| 可检索 context/resource/memory | OpenViking | Gateway 按允许 namespace 查询 OpenViking，适合跨 agent 的 context 检索 |
+| 上传文档 Markdown | Obsidian `01_Knowledge/Uploaded/` | 由 `/api/knowledge/upload` 写入，适合人工审查和维护 |
+| 高价值/冲突 review draft | Obsidian `Reviews/Queue/` | EverMemOS 发现高价值或冲突候选时写入，不直接污染长期记忆 |
+| Hermes plugin trace | `plugins/memory-gateway-agent/.tmp/hook_trace.log` | 默认关闭，只存 hook 名称、短 session id、Gateway action 和状态 |
+
+### 什么时候写短期记忆
+
+短期记忆写入 `episodes`，通常来自：
+
+- Hermes plugin `post_llm_call` 判断用户明确要求“remember/记住”或出现稳定偏好、长期约束、项目事实。
+- agent 或 skill 显式调用 `memory_append_episode`。
+- 任务执行过程中的关键结论、可复用 workflow、架构决策。
+
+短期记忆不应该包含：
+
+- 完整原始对话。
+- password、token、API key、cookie、private key。
+- 一次性验证码、大段日志、低价值临时内容。
+- 模型 chain-of-thought。
+
+### 什么时候提升为长期记忆
+
+长期记忆写入 `memories`，通常发生在：
+
+1. Agent/skill/plugin 先写 `session/{session_id}/episodic` episode。
+2. 调用 `/v1/sessions/{session_id}/commit` 或 MCP/tool `memory_commit_session`。
+3. Gateway 把 session episodes、可见长期记忆和访问上下文发给 EverMemOS。
+4. EverMemOS 做提取、去重、合并、冲突检测、重要性判断。
+5. 稳定且超过阈值的候选 promote 到 `user/{user_id}/long_term` 或目标 namespace。
+6. 高价值、冲突或需要人工确认的候选进入 Obsidian `Reviews/Queue/`。
+
+Hermes plugin 默认：
+
+- `MEMORY_GATEWAY_AUTO_SEARCH=true`：对话前自动检索。
+- `MEMORY_GATEWAY_AUTO_APPEND_EPISODE=true`：对话后按 policy 写 candidate episode。
+- `MEMORY_GATEWAY_AUTO_COMMIT_SESSION=false`：默认不自动提升长期记忆。
+
+因此，POC 推荐流程是“先短期、后 commit、再长期”，不要把所有 session 内容直接 upsert 成长期记忆。
+
+### 如何再次查询和调用用户记忆
+
+HTTP 查询：
+
+```bash
+curl -X POST http://127.0.0.1:1934/v1/memory/search \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: <CHANGE_ME_LONG_RANDOM_KEY>" \
+  -d '{
+    "user_id": "user_demo",
+    "agent_id": "agent_hermes",
+    "workspace_id": "workspace_demo",
+    "session_id": "session_001",
+    "query": "用户输出偏好和项目约束",
+    "limit": 5
+  }'
+```
+
+Hermes skill 查询：
+
+```bash
+python ~/.hermes/skills/memory-gateway/scripts/memory_search.py \
+  --user-id user_demo \
+  --agent-id agent_hermes \
+  --workspace-id workspace_demo \
+  --session-id session_001 \
+  --query "用户输出偏好和项目约束" \
+  --limit 5
+```
+
+Hermes plugin 查询：
+
+- 用户正常对话时，`pre_llm_call` 会自动调用 `memory_search`。
+- Agent 也可以显式调用 `memory_search` tool。
+
+## 远程调用与安全
+
+Memory Gateway API 可以远程调用。生产/远程部署时建议：
+
+1. `server.host` 设置为 `0.0.0.0`。
+2. `server.api_key` 设置为长随机值。
+3. 防火墙只开放可信来源，或通过 VPN/内网访问。
+4. 使用 Nginx/Caddy/负载均衡终止 TLS。
+5. 远程客户端一律带 `X-API-Key`。
+
+远程调用示例：
+
+```bash
+export MEMORY_GATEWAY_URL=https://memory.example.com
+export MEMORY_GATEWAY_API_KEY=<CHANGE_ME_LONG_RANDOM_KEY>
+
+curl -X POST "$MEMORY_GATEWAY_URL/v1/memory/search" \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: $MEMORY_GATEWAY_API_KEY" \
+  -d '{
+    "user_id": "user_demo",
+    "agent_id": "remote_agent",
+    "workspace_id": "workspace_demo",
+    "query": "长期偏好",
+    "limit": 5
+  }'
+```
+
+远程 Hermes plugin 配置：
+
+```bash
+export MEMORY_GATEWAY_URL=https://memory.example.com
+export MEMORY_GATEWAY_API_KEY=<CHANGE_ME_LONG_RANDOM_KEY>
+export MEMORY_GATEWAY_DEFAULT_USER_ID=user_demo
+export MEMORY_GATEWAY_DEFAULT_AGENT_ID=agent_hermes_remote
+export MEMORY_GATEWAY_DEFAULT_WORKSPACE_ID=workspace_demo
+```
+
+注意：远程 API 不应裸奔在公网。至少启用 API key 和 TLS；涉及个人记忆时建议放在内网或 VPN 后面。
+
+## 本地开发快捷启动
+
+全新服务器请优先按上面的 `/opt` 部署流程执行。本节用于已经 clone 当前仓库后的开发机快速启动，路径都以仓库根目录为准。
+
+```bash
+cd memory-gateway
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install -e ".[dev]"
+mkdir -p data obsidian-vault/01_Knowledge/Uploaded obsidian-vault/Reviews/Queue
+cp config.example.yaml config.yaml
+```
+
+建议把 `config.yaml` 中的本地开发路径改成：
 
 ```yaml
-memory:
-  default_namespace: memory-gateway
-
-llm:
-  base_url: https://oai.bwgdi.com/v1
-  api_key: <local secret, git ignored>
-  model: MiniMaxAI
-
 obsidian:
-  vault_path: /home/tom/memory-gateway/obsidian-vault
-  knowledge_dir: 01_Knowledge/Uploaded
-  review_dir: Reviews/Queue
+  vault_path: "./obsidian-vault"
 
 storage:
   backend: sqlite
-  sqlite_path: /home/tom/memory-gateway/memory_gateway.sqlite3
+  sqlite_path: "./data/memory_gateway.sqlite3"
 ```
 
-`config.yaml` 已被 `.gitignore` 忽略，不会提交密钥。
-
-## 启动
-
-OpenViking 需要先运行在 `127.0.0.1:1933`。
+启动顺序：
 
 ```bash
-source /home/tom/OpenViking/.venv/bin/activate
+# 终端 1：OpenViking，按 OpenViking 项目实际环境启动
 openviking-server --host 127.0.0.1 --port 1933
-```
 
-启动本机 EverMemOS 服务：
-
-```bash
-cd /home/tom/memory-gateway
-source /home/tom/OpenViking/.venv/bin/activate
+# 终端 2：EverMemOS-compatible POC 服务
 python -m memory_gateway.evermemos_service \
-  --config /home/tom/memory-gateway/config.yaml \
+  --config ./config.yaml \
   --host 127.0.0.1 \
   --port 1995
-```
 
-启动 Memory Gateway：
-
-```bash
-cd /home/tom/memory-gateway
-source /home/tom/OpenViking/.venv/bin/activate
-python -m memory_gateway.server --config /home/tom/memory-gateway/config.yaml
+# 终端 3：Memory Gateway
+python -m memory_gateway.server --config ./config.yaml
 ```
 
 健康检查：
@@ -133,6 +520,12 @@ curl http://127.0.0.1:1934/v1/evermemos/health
 
 ## REST 接口
 
+如果 `config.yaml` 设置了 `server.api_key`，以下所有 HTTP 调用都需要加：
+
+```bash
+-H "X-API-Key: <CHANGE_ME_LONG_RANDOM_KEY>"
+```
+
 ### `GET /health`
 
 检查 Gateway 和 OpenViking 状态。
@@ -340,7 +733,7 @@ obsidian-vault/Reviews/Queue/
 通用 Hermes skill：
 
 ```text
-/home/tom/.hermes/skills/memory-gateway/
+~/.hermes/skills/memory-gateway/
 ```
 
 仓库副本：
@@ -352,10 +745,10 @@ integrations/hermes/memory-gateway/
 安装或更新到本机 Hermes skill 目录：
 
 ```bash
-mkdir -p /home/tom/.hermes/skills/memory-gateway
+mkdir -p ~/.hermes/skills/memory-gateway
 rsync -a --delete \
-  /home/tom/memory-gateway/integrations/hermes/memory-gateway/ \
-  /home/tom/.hermes/skills/memory-gateway/
+  ./integrations/hermes/memory-gateway/ \
+  ~/.hermes/skills/memory-gateway/
 ```
 
 使用方式：
@@ -382,13 +775,13 @@ scripts/search_obsidian.py
 检查 EverMemOS：
 
 ```bash
-python /home/tom/.hermes/skills/memory-gateway/scripts/evermemos_health.py
+python ~/.hermes/skills/memory-gateway/scripts/evermemos_health.py
 ```
 
 检索记忆：
 
 ```bash
-python /home/tom/.hermes/skills/memory-gateway/scripts/retrieve_memory.py \
+python ~/.hermes/skills/memory-gateway/scripts/retrieve_memory.py \
   --query "document upload summary memory gateway" \
   --uri viking://resources \
   --limit 5
@@ -397,7 +790,7 @@ python /home/tom/.hermes/skills/memory-gateway/scripts/retrieve_memory.py \
 总结沉淀：
 
 ```bash
-python /home/tom/.hermes/skills/memory-gateway/scripts/commit_summary.py \
+python ~/.hermes/skills/memory-gateway/scripts/commit_summary.py \
   --title "Reusable conclusion" \
   --namespace memory-gateway \
   --memory-type decision \
@@ -409,7 +802,7 @@ python /home/tom/.hermes/skills/memory-gateway/scripts/commit_summary.py \
 上传知识：
 
 ```bash
-python /home/tom/.hermes/skills/memory-gateway/scripts/upload_knowledge.py \
+python ~/.hermes/skills/memory-gateway/scripts/upload_knowledge.py \
   --file /path/to/document.md \
   --title "Knowledge note" \
   --namespace memory-gateway \
@@ -421,12 +814,12 @@ python /home/tom/.hermes/skills/memory-gateway/scripts/upload_knowledge.py \
 完整长短期记忆测试：
 
 ```bash
-python /home/tom/.hermes/skills/memory-gateway/scripts/memory_create_user.py \
+python ~/.hermes/skills/memory-gateway/scripts/memory_create_user.py \
   --user-id user_tom \
   --display-name "Tom" \
   --preference language=zh-CN
 
-python /home/tom/.hermes/skills/memory-gateway/scripts/memory_append_episode.py \
+python ~/.hermes/skills/memory-gateway/scripts/memory_append_episode.py \
   --user-id user_tom \
   --agent-id agent_hermes \
   --workspace-id ws_memory_gateway \
@@ -434,7 +827,7 @@ python /home/tom/.hermes/skills/memory-gateway/scripts/memory_append_episode.py
   --tag decision \
   --text "结论：本机 EverMemOS 服务负责从 session episode 中整理稳定长期记忆。"
 
-python /home/tom/.hermes/skills/memory-gateway/scripts/memory_append_episode.py \
+python ~/.hermes/skills/memory-gateway/scripts/memory_append_episode.py \
   --user-id user_tom \
   --agent-id agent_hermes \
   --workspace-id ws_memory_gateway \
@@ -443,14 +836,14 @@ python /home/tom/.hermes/skills/memory-gateway/scripts/memory_append_episode.py
   --tag high-value \
   --text "重要：高价值记忆应该进入 Obsidian review queue，避免错误记忆污染长期系统。"
 
-python /home/tom/.hermes/skills/memory-gateway/scripts/memory_commit_session.py \
+python ~/.hermes/skills/memory-gateway/scripts/memory_commit_session.py \
   --user-id user_tom \
   --agent-id agent_hermes \
   --workspace-id ws_memory_gateway \
   --session-id sess_demo \
   --min-importance 0.6
 
-python /home/tom/.hermes/skills/memory-gateway/scripts/memory_search.py \
+python ~/.hermes/skills/memory-gateway/scripts/memory_search.py \
   --user-id user_tom \
   --agent-id agent_hermes \
   --workspace-id ws_memory_gateway \
@@ -478,9 +871,9 @@ plugins/memory-gateway-agent/
 Hermes 本机安装：
 
 ```bash
-mkdir -p /home/tom/.hermes/plugins
-ln -s /home/tom/memory-gateway/plugins/memory-gateway-agent \
-  /home/tom/.hermes/plugins/memory-gateway-agent
+mkdir -p ~/.hermes/plugins
+ln -s "$(pwd)/plugins/memory-gateway-agent" \
+  ~/.hermes/plugins/memory-gateway-agent
 hermes plugins enable memory-gateway-agent
 hermes plugins list
 hermes tools list
@@ -489,7 +882,7 @@ hermes tools list
 如果软链接已存在，先确认它指向当前仓库：
 
 ```bash
-ls -l /home/tom/.hermes/plugins/memory-gateway-agent
+ls -l ~/.hermes/plugins/memory-gateway-agent
 ```
 
 运行配置：
@@ -516,25 +909,25 @@ Hermes plugin 已验证：
 真实 Hermes chat 验证：
 
 ```bash
-PYTHONPATH=/home/tom/memory-gateway/plugins/memory-gateway-agent \
-python /home/tom/memory-gateway/plugins/memory-gateway-agent/scripts/hermes_interactive_session_check.py
+PYTHONPATH="$(pwd)/plugins/memory-gateway-agent" \
+python plugins/memory-gateway-agent/scripts/hermes_interactive_session_check.py
 ```
 
 插件 E2E 验证：
 
 ```bash
-PYTHONPATH=/home/tom/memory-gateway/plugins/memory-gateway-agent \
-python /home/tom/memory-gateway/plugins/memory-gateway-agent/scripts/gateway_e2e_check.py
+PYTHONPATH="$(pwd)/plugins/memory-gateway-agent" \
+python plugins/memory-gateway-agent/scripts/gateway_e2e_check.py
 
-PYTHONPATH=/home/tom/memory-gateway/plugins/memory-gateway-agent \
-python /home/tom/memory-gateway/plugins/memory-gateway-agent/scripts/hermes_hook_probe.py
+PYTHONPATH="$(pwd)/plugins/memory-gateway-agent" \
+python plugins/memory-gateway-agent/scripts/hermes_hook_probe.py
 ```
 
 清理测试数据：
 
 ```bash
-PYTHONPATH=/home/tom/memory-gateway/plugins/memory-gateway-agent \
-python /home/tom/memory-gateway/plugins/memory-gateway-agent/scripts/cleanup_test_memories.py
+PYTHONPATH="$(pwd)/plugins/memory-gateway-agent" \
+python plugins/memory-gateway-agent/scripts/cleanup_test_memories.py
 ```
 
 安全边界：
@@ -556,11 +949,11 @@ plugins/memory-gateway-agent/openclaw.plugin.yaml
 ## 测试
 
 ```bash
-cd /home/tom/memory-gateway
-source /home/tom/OpenViking/.venv/bin/activate
-PYTHONPATH=/home/tom/memory-gateway pytest -q
+cd memory-gateway
+source .venv/bin/activate
+PYTHONPATH="$(pwd)" pytest -q
 
-PYTHONPATH=/home/tom/memory-gateway/plugins/memory-gateway-agent \
+PYTHONPATH="$(pwd)/plugins/memory-gateway-agent" \
   pytest -q plugins/memory-gateway-agent/tests
 ```
 
diff --git a/config.example.yaml b/config.example.yaml
index f7445e6..30405b6 100644
--- a/config.example.yaml
+++ b/config.example.yaml
@@ -1,27 +1,28 @@
-# Memory Gateway 配置示例
-# 复制为 config.yaml 并根据实际情况修改
+# Memory Gateway 配置示例。
+# 复制为 config.yaml 并根据实际服务器路径、端口和密钥修改。
+# 不要提交 config.yaml；它应包含本机/服务器密钥。
 
 # Memory Gateway 服务配置
 server:
-  # 监听地址，0.0.0.0 表示接受所有网卡（局域网可访问）
-  host: "0.0.0.0"
-  # MCP Server 端口
+  # 本机测试可用 127.0.0.1；需要远程调用时使用 0.0.0.0 并配置防火墙/反向代理。
+  host: "127.0.0.1"
+  # REST API、MCP RPC 和 SSE 共用端口。
   port: 1934
-  # 可选：API Key 认证，客户端需要提供相同的 Key
+  # 强烈建议生产/远程调用时设置；客户端通过 X-API-Key 传入。
   api_key: ""
 
 # OpenViking 后端配置
 openviking:
-  # OpenViking 服务器地址
-  url: "http://localhost:1933"
-  # OpenViking API Key（如有）
+  # OpenViking 服务器地址。Memory Gateway 通过它检索 context/resource/memory。
+  url: "http://127.0.0.1:1933"
+  # OpenViking API Key。按 OpenViking 实际配置填写。
   api_key: ""
-  # 请求超时时间（秒）
   timeout: 30
 
 # EverMemOS 后台长期记忆整理服务
 evermemos:
   enabled: true
+  # 可以是本机 memory_gateway.evermemos_service，也可以是远程 EverMemOS 服务。
   url: "http://127.0.0.1:1995"
   api_key: ""
   timeout: 30
@@ -33,9 +34,8 @@ evermemos:
 
 # 记忆配置
 memory:
-  # 默认命名空间
+  # 旧 /api/* 接口使用的默认命名空间。v1 API 会按 user/agent/workspace/session 自动展开 namespace。
   default_namespace: "memory-gateway"
-  # 默认搜索返回数量
   search_limit: 10
 
 # 日志配置
@@ -52,13 +52,16 @@ llm:
   timeout: 60
   max_input_chars: 24000
 
-# Obsidian 配置：用于 /api/knowledge/upload 保存 Markdown 笔记
+# Obsidian Vault 配置。
+# 服务端不要求安装 Obsidian 桌面应用；这里本质上是一个 Markdown vault 目录。
 obsidian:
-  vault_path: "/home/tom/memory-gateway/obsidian-vault"
+  vault_path: "/opt/memory-gateway/obsidian-vault"
   knowledge_dir: "01_Knowledge/Uploaded"
   review_dir: "Reviews/Queue"
 
-# v1 metadata storage. Use "memory" only for isolated unit tests.
+# v1 metadata storage。
+# SQLite 保存 users、memories、episodes、profiles、audit，是用户隔离和 ACL 判断的主要 metadata store。
+# Use "memory" only for isolated unit tests.
 storage:
   backend: "sqlite"
-  sqlite_path: "/home/tom/memory-gateway/memory_gateway.sqlite3"
+  sqlite_path: "/opt/memory-gateway/data/memory_gateway.sqlite3"
diff --git a/plugins/memory-gateway-agent/README.md b/plugins/memory-gateway-agent/README.md
index e981d00..24e16cd 100644
--- a/plugins/memory-gateway-agent/README.md
+++ b/plugins/memory-gateway-agent/README.md
@@ -55,7 +55,8 @@ Install locally:
 
 ```bash
 mkdir -p ~/.hermes/plugins
-ln -s /home/tom/memory-gateway/plugins/memory-gateway-agent ~/.hermes/plugins/memory-gateway-agent
+cd /opt/memory-gateway
+ln -s "$(pwd)/plugins/memory-gateway-agent" ~/.hermes/plugins/memory-gateway-agent
 hermes plugins enable memory-gateway-agent
 hermes plugins list
 hermes tools list
@@ -134,7 +135,7 @@ Integration tests use:
 Run cleanup:
 
 ```bash
-cd /home/tom/memory-gateway
+cd /opt/memory-gateway
 PYTHONPATH=plugins/memory-gateway-agent python plugins/memory-gateway-agent/scripts/cleanup_test_memories.py
 ```
 
@@ -143,7 +144,7 @@ The cleanup script refuses non-`test_user_` users. It first tries `DELETE /v1/me
 ## Local Smoke Test
 
 ```bash
-cd /home/tom/memory-gateway
+cd /opt/memory-gateway
 PYTHONPATH=plugins/memory-gateway-agent python plugins/memory-gateway-agent/scripts/health.py
 PYTHONPATH=plugins/memory-gateway-agent python plugins/memory-gateway-agent/scripts/smoke_test.py
 PYTHONPATH=plugins/memory-gateway-agent python plugins/memory-gateway-agent/scripts/hermes_smoke_check.py