tomtan/memory-gateway
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
tomtan
2026-06-02 11:47:11 +08:00
parent 1b5fee9866
commit 9820834175
4 changed files with 254 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
README.md
View File

@ -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

10
config.example.yaml
View File

@ -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"

77
everos.env.example Normal file
View File

@ -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

44
openviking.ov.conf.example Normal file
View File

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