# memory-hub

**Repository Path**: jasonchan0754/memory-hub

## Basic Information

- **Project Name**: memory-hub
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-07
- **Last Updated**: 2026-03-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Memory Hub Standalone 使用说明

这份文档只面向 `memory-hub` 的 standalone 版本。

它的定位很简单：

- `memory-hub` 是一个运行在你本机的独立 MCP 记忆服务
- 你已经安装好的 Cherry Studio 桌面版继续照常使用
- Claude Code、Codex、Gemini CLI 通过 MCP 接入 `memory-hub`
- Cherry Studio 桌面版负责你的本地工作台和可选的本地 API Server

这两者可以同时存在，不冲突，也不要求你替换现有 Cherry Studio。

## 适合你的使用方式

如果你现在已经在本机运行 Cherry Studio 桌面版，推荐这样用：

1. 单独启动 `memory-hub`
2. 把 `memory-hub` 安装到 Claude Code、Codex、Gemini CLI
3. Cherry Studio 继续作为本地工作台使用
4. 如果你还想让外部工具调用 Cherry 自己的 API，再额外开启 Cherry 的 API Server

一句话说清楚：

- `memory-hub` 负责“长期记忆”
- Cherry Studio 负责“本地工作台 / UI / 可选 API”

## 1. 启动 Server

### 方式 A：你是从 standalone 仓库启动

先安装依赖：

```bash
pnpm install
```

启动服务：

```bash
pnpm dev
```

默认监听地址：

```text
http://127.0.0.1:43123/mcp
```

### 方式 B：你仍然在 Cherry monorepo 里启动这个包

```bash
pnpm --filter @cherrystudio/memory-hub dev
```

### 可选环境变量

你可以自定义 host、port、数据目录和空闲回收时间：

```bash
MEMORY_HUB_HOST=127.0.0.1 \
MEMORY_HUB_PORT=43123 \
MEMORY_HUB_DATA_DIR="$HOME/.cherrystudio/memory-hub" \
MEMORY_HUB_IDLE_TTL_MS=300000 \
pnpm dev
```

默认值是：

- `MEMORY_HUB_HOST=127.0.0.1`
- `MEMORY_HUB_PORT=43123`
- `MEMORY_HUB_DATA_DIR=~/.cherrystudio/memory-hub`
- `MEMORY_HUB_IDLE_TTL_MS=300000`

如果你想把 standalone `memory-hub` 直接升级成“Cherry handoff sidecar + 记忆总线”一体化服务，还可以额外配置：

- `MEMORY_HUB_CHERRY_API_BASE_URL`
- `MEMORY_HUB_CHERRY_API_KEY`
- `MEMORY_HUB_CHERRY_MCP_SERVER_ID`

可选：

- `MEMORY_HUB_CHERRY_PROMPT_APPENDIX`
- `MEMORY_HUB_CHERRY_ALLOWED_TOOL_NAMES`

示例：

```bash
MEMORY_HUB_CHERRY_API_BASE_URL=http://127.0.0.1:23333 \
MEMORY_HUB_CHERRY_API_KEY=your-cherry-api-key \
MEMORY_HUB_CHERRY_MCP_SERVER_ID=memory_hub \
pnpm dev
```

### 启动后的联通检查

```bash
curl --noproxy '*' http://127.0.0.1:43123/health
```

正常返回应包含：

```json
{
  "status": "ok"
}
```

## 2. 安装到 Claude Code / Codex / Gemini CLI

下面假设你的 `memory-hub` 正在本机默认地址运行：

```text
http://127.0.0.1:43123/mcp
```

如果你的终端设置了这些代理变量：

- `http_proxy`
- `https_proxy`
- `all_proxy`

那么 `127.0.0.1` 这类本地请求也可能被错误地转发到代理，导致 MCP 显示 `Disconnected`。

下面给出的“单独直连”命令都只影响**当前这一条命令 / 当前这个 CLI 进程**，不会改你的全局代理设置。

### Claude Code

安装命令：

```bash
claude mcp add --transport http -s user memory_hub http://127.0.0.1:43123/mcp
```

查看是否安装成功：

```bash
claude mcp list
```

如果你只想加到当前项目，把 `-s user` 改成：

```bash
-s project
```

如果你不想改全局代理，但希望 Claude Code 这个进程单独直连本机 `memory-hub`，推荐这样启动：

```bash
NO_PROXY=127.0.0.1,localhost \
no_proxy=127.0.0.1,localhost \
claude
```

检查 MCP 连通性时也建议带上同样的前缀：

```bash
NO_PROXY=127.0.0.1,localhost \
no_proxy=127.0.0.1,localhost \
claude mcp list
```

如果你的环境里 Claude 仍然把 `localhost` 请求走代理，再用这条“强制直连”命令：

```bash
env -u ALL_PROXY -u all_proxy -u HTTP_PROXY -u http_proxy -u HTTPS_PROXY -u https_proxy claude
```

### Codex

安装命令：

```bash
codex mcp add memory_hub --url http://127.0.0.1:43123/mcp
```

查看是否安装成功：

```bash
codex mcp list
```

如果你不想改全局代理，但希望 Codex 这个进程单独直连本机 `memory-hub`，推荐这样启动：

```bash
NO_PROXY=127.0.0.1,localhost \
no_proxy=127.0.0.1,localhost \
codex
```

查看 MCP 配置时也建议带上同样的前缀：

```bash
NO_PROXY=127.0.0.1,localhost \
no_proxy=127.0.0.1,localhost \
codex mcp list
```

如果你的环境里 Codex 仍然把本地请求走代理，再用这条“强制直连”命令：

```bash
env -u ALL_PROXY -u all_proxy -u HTTP_PROXY -u http_proxy -u HTTPS_PROXY -u https_proxy codex
```

如果你的 Codex CLI 版本不支持这条命令，手动写配置也可以。

编辑 `~/.codex/config.toml`：

```toml
[mcp_servers.memory_hub]
url = "http://127.0.0.1:43123/mcp"
```

### Gemini CLI

Gemini CLI 现在既支持手动编辑 `settings.json`，也支持直接用命令添加 MCP。

安装命令：

```bash
gemini mcp add --transport http -s user memory_hub http://127.0.0.1:43123/mcp
```

查看是否安装成功：

```bash
gemini mcp list
```

Gemini CLI 在当前版本下，单靠 `NO_PROXY=127.0.0.1,localhost` 仍然可能显示 `Disconnected`。

如果你不想改全局代理，但希望 Gemini 这个进程单独直连本机 `memory-hub`，最稳妥的启动方式是：

```bash
env -u ALL_PROXY -u all_proxy -u HTTP_PROXY -u http_proxy -u HTTPS_PROXY -u https_proxy gemini
```

检查 MCP 状态时也建议带上同样的前缀：

```bash
env -u ALL_PROXY -u all_proxy -u HTTP_PROXY -u http_proxy -u HTTPS_PROXY -u https_proxy gemini mcp list
```

如果你更想手动配置，编辑：

```text
~/.gemini/settings.json
```

写入：

```json
{
  "mcpServers": {
    "memory_hub": {
      "httpUrl": "http://127.0.0.1:43123/mcp"
    }
  }
}
```

如果你需要为 HTTP MCP 传 header，Gemini CLI 也支持：

```json
{
  "mcpServers": {
    "memory_hub": {
      "httpUrl": "http://127.0.0.1:43123/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}
```

### 代理环境下的推荐启动命令

如果你的终端长期挂着代理，而你又希望 Claude Code、Codex、Gemini 这三个 CLI 在启动时单独直连本机 `memory-hub`，直接用下面这些命令即可。

Claude Code：

```bash
NO_PROXY=127.0.0.1,localhost \
no_proxy=127.0.0.1,localhost \
claude
```

Claude Code 连通性检查：

```bash
NO_PROXY=127.0.0.1,localhost \
no_proxy=127.0.0.1,localhost \
claude mcp list
```

Codex：

```bash
NO_PROXY=127.0.0.1,localhost \
no_proxy=127.0.0.1,localhost \
codex
```

Codex 连通性检查：

```bash
NO_PROXY=127.0.0.1,localhost \
no_proxy=127.0.0.1,localhost \
codex mcp list
```

Gemini：

```bash
env -u ALL_PROXY -u all_proxy -u HTTP_PROXY -u http_proxy -u HTTPS_PROXY -u https_proxy gemini
```

Gemini 连通性检查：

```bash
env -u ALL_PROXY -u all_proxy -u HTTP_PROXY -u http_proxy -u HTTPS_PROXY -u https_proxy gemini mcp list
```

一句话总结：

- Claude Code：优先用 `NO_PROXY`
- Codex：优先用 `NO_PROXY`
- Gemini：优先直接清空当前进程代理变量

如果你想进一步省事，也可以在 `~/.zshrc` 里加几个 alias，但这不是必须的。

## 3. 如何和本地桌面版 Cherry Studio 配合

这部分最容易混淆，先说结论。

### Cherry Bridge 一体化模式

从这版开始，standalone `memory-hub` 可以直接集成 Cherry bridge。开启后，同一个 `memory-hub` server 会同时提供两类能力：

- 原生 memory MCP 工具：`memory_write`、`memory_search`、`workspace_snapshot_save` 等
- Cherry bridge 高层工具：`ensure_cherry_agent`、`get_or_create_cherry_session`、`load_handoff_context`、`save_handoff_snapshot`、`remember_fact`、`remember_resource`、`remember_event`

同时也会开放对应的 HTTP 路由：

- `GET /v1/cherry/status`
- `POST /v1/cherry/agents/ensure`
- `POST /v1/cherry/sessions/ensure`
- `POST /v1/cherry/session-locator`
- `POST /v1/cherry/handoff/context`
- `POST /v1/cherry/handoff/snapshot`
- `POST /v1/cherry/memories/fact`
- `POST /v1/cherry/memories/resource`
- `POST /v1/cherry/memories/event`

这样外部 Claude 只需要连同一个 `memory-hub` MCP server，就能同时拿到“记忆能力”和“Cherry agent 控制能力”。

### 你不需要做的事

你不需要：

- 重装 Cherry Studio
- 用容器跑 Cherry
- 把这个 standalone 服务塞进你当前已经安装的官方桌面版 Cherry

如果你只是想“用起来”，最短路径就是：

- Cherry Studio 桌面版继续正常开着
- `memory-hub` 作为独立本地服务启动
- Claude / Codex / Gemini 直接连接 `memory-hub`

### Cherry 在这套方案里的作用

Cherry Studio 桌面版主要承担两个角色：

1. 你的本地 AI 工作台
2. 可选的本地 API Server

而 `memory-hub` standalone 是第三方本地服务，不依赖 Cherry API key 才能运行。

也就是说：

- `memory-hub` standalone 默认不需要 Cherry API key
- 只有当你还想让外部工具去调用 Cherry 自己的接口时，才需要开启 Cherry 的 API Server

### 如果你要让 Cherry 也开放本地 API

在 Cherry Studio 桌面版里打开：

```text
设置 -> 工具 -> API Server
```

建议这样设置：

- Host: `127.0.0.1`
- Port: `23333`
- 启动 API Server
- 复制 API Key

启动后可以用下面命令检查 Cherry API 是否正常：

```bash
curl --noproxy '*' http://127.0.0.1:23333/health
```

然后把 API key 放到环境变量里：

```bash
export CHERRY_API_KEY='cs-sk-REPLACE_ME'
```

再测试 Cherry 的鉴权接口：

```bash
curl --noproxy '*' -H "Authorization: Bearer $CHERRY_API_KEY" \
  http://127.0.0.1:23333/v1/mcps
```

### 推荐的配合方式

推荐你这样长期使用：

1. Cherry Studio 桌面版常驻，作为本地工作台
2. `memory-hub` standalone 常驻，作为外部长期记忆
3. Claude Code / Codex / Gemini CLI 都连到 `memory-hub`
4. 如果以后你还想调 Cherry 的 agent、模型、MCP，再单独使用 Cherry API Server

### 不要混淆的两套“记忆”

你现在会同时看到两类记忆能力：

1. Cherry 自己的“全局记忆”
2. `memory-hub` standalone 的记忆

它们不是同一套数据。

所以你可以这样理解：

- Cherry 全局记忆：服务于 Cherry 自己的聊天/助手体系
- `memory-hub`：服务于 Claude Code / Codex / Gemini CLI 这些外部 agent

如果你的目标是“让外部 coding agent 有长期记忆”，那主角应该是 `memory-hub`。

## 4. 记忆文件存储位置

### standalone 默认存储目录

默认目录是：

```text
~/.cherrystudio/memory-hub
```

实际文件名是：

```text
memory-hub.json
```

所以默认完整路径是：

```text
~/.cherrystudio/memory-hub/memory-hub.json
```

### 在不同系统上的典型路径

macOS:

```text
/Users/<你的用户名>/.cherrystudio/memory-hub/memory-hub.json
```

Linux:

```text
/home/<你的用户名>/.cherrystudio/memory-hub/memory-hub.json
```

Windows:

```text
C:\Users\<你的用户名>\.cherrystudio\memory-hub\memory-hub.json
```

### 自定义存储目录

你可以通过环境变量覆盖默认目录：

```bash
export MEMORY_HUB_DATA_DIR="/your/custom/path"
pnpm dev
```

这时实际文件会变成：

```text
/your/custom/path/memory-hub.json
```

### Cherry 内嵌版的存储位置

这份文档主讲 standalone，但为了避免混淆，顺便说明一下：

如果你以后跑的是“改过的 Cherry 开发版内嵌 memory-hub”，默认目录不是上面的 `~/.cherrystudio/memory-hub`，而是：

```text
<Cherry userData>/memory-hub
```

也可以通过下面这个变量覆盖：

```bash
CHERRY_MEMORY_HUB_DATA_DIR=/your/custom/path
```

### 闲时资源占用和文件落盘

`memory-hub` 的数据是持久化到 `memory-hub.json` 的。

默认空闲回收时间是 5 分钟：

```text
300000 ms
```

这意味着：

- 服务进程可以继续在
- 记忆文件不会丢
- 空闲时会尽量降低运行时资源占用

## 5. 常用测试命令

### 写入一条记忆

```bash
curl --noproxy '*' -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "layer": "semantic",
    "namespace": "demo",
    "title": "first-memory",
    "text": "Cherry Studio 是本地工作台，memory-hub 是外部长期记忆服务。",
    "tags": ["demo", "intro"]
  }' \
  http://127.0.0.1:43123/v1/memories
```

### 搜索一条记忆

```bash
curl --noproxy '*' -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "query": "长期记忆 Cherry Studio",
    "namespace": ["demo"]
  }' \
  http://127.0.0.1:43123/v1/search
```

### 查看状态

```bash
curl --noproxy '*' http://127.0.0.1:43123/v1/status
```

### 查看统计

```bash
curl --noproxy '*' http://127.0.0.1:43123/v1/stats
```

### 主动 flush / reload

```bash
curl --noproxy '*' -X POST http://127.0.0.1:43123/v1/control/flush
curl --noproxy '*' -X POST http://127.0.0.1:43123/v1/control/reload
```

## 6. 暴露给外部 Agent 的能力

`memory-hub` 目前提供的 MCP tools：

- `memory_write`
- `memory_search`
- `memory_update`
- `memory_delete`
- `memory_pin`
- `workspace_snapshot_save`
- `workspace_snapshot_get`
- `memory_status`

MCP resources：

- `memory-hub://stats`
- `memory-hub://entries/{id}`
- `memory-hub://layers/{layer}`
- `memory-hub://snapshots/{namespace}`

如果你的 agent 支持 MCP，它就能把这些能力当作工具或资源来使用。

## 7. 安全建议

standalone 默认只监听：

```text
127.0.0.1
```

这是推荐配置。

如果你把它改成：

```text
0.0.0.0
```

就意味着局域网里的其他机器也可能访问到它。由于 standalone 默认没有像 Cherry API Server 那样的认证层，所以除非你清楚自己在做什么，否则不要这么配。

## 8. 官方参考

- Claude Code MCP: `https://docs.anthropic.com/en/docs/claude-code/mcp`
- OpenAI Codex MCP: `https://developers.openai.com/codex/mcp`
- Gemini CLI MCP: `https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md`
- Gemini CLI Configuration: `https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md`