内容
# umg0 — 统一内存网关
适用于 AI 代理的 MCP 首选、本地优先的层次内存。
可以理解为 **“OpenRouter for agent memory”** — 具有 **网关架构准备** 的分层本地内存。
与 **Claude Code、Cursor、Hermes、Cline、Roo Code、VS Code + GitHub Copilot、Zed、Windsurf、ChatGPT（开发者模式）以及任何 MCP 兼容客户端** 配合使用。相同的 stdio MCP 服务器；只需更改配置文件位置。
**品牌 / npm / CLI:** **umg0** · **产品名称：** UMG（统一内存网关）· 营销网站： **[site/](./site/)**
**解决问题：** 代理失忆和重复解释的成本，而无需无限的内存膨胀。
**v0.2 定位：** 多后端路由 **超出范围**。一个优秀的本地存储 + 清洁的 `MemoryStore` 端口。今天的传输是 **stdio MCP** （远程/HTTP 是未来的工作）。
> npm 包名称为 **`@umg0/umg0`** （二进制文件 `umg0`），因为 bare `umg` 被占用，而无作用域的 `umg0` 被阻止，因为它与注册表上的 `umi` 太相似。产品和环境前缀保持 **UMG** （`UMG_DB_PATH` 等）。
## 兼容客户端
| 客户端 | 配置位置（典型） | 示例文件 |
|--------|---------------------------|--------------|
| **Claude Code** | `~/.claude.json` 或项目 `.mcp.json` | [examples/claude-code.mcp.json](./examples/claude-code.mcp.json) |
| **Cursor** | `~/.cursor/mcp.json` | [examples/cursor.mcp.json](./examples/cursor.mcp.json) |
| **Hermes** | Hermes MCP / `mcp_servers` 配置 | [examples/hermes.config.snippet.yaml](./examples/hermes.config.snippet.yaml) |
| **Cline / Roo Code** | Cline / Roo MCP 设置（JSON） | [examples/vscode-cline.mcp.json](./examples/vscode-cline.mcp.json) |
| **VS Code + GitHub Copilot** | VS Code MCP / Copilot MCP 配置 | [examples/vscode-cline.mcp.json](./examples/vscode-cline.mcp.json) |
| **Zed** | Zed 代理 MCP 设置 | 相同的通用 `mcpServers` 形状 |
| **Windsurf** | Windsurf MCP 配置 | 相同的通用形状 |
| **ChatGPT（开发者模式）** | 启用时的 MCP 工具配置 | 相同的 stdio 服务器 |
| **任何 MCP 客户端** | 主机用于 stdio MCP 的配置 | 通用块如下 |
请参阅 [examples/README.md](./examples/README.md) 以获取配置、会话剧本和系统提示。
## 功能（v0.2）
- **MCP 工具：** `retain`、`recall`、`reflect`、`list_memories`、`prune`、`promote_to_skill`（+ `dry_run`）
- **层次结构：** 工作 → 片段 → 语义 → 程序
- **可配置排名**（FTS、重要性、衰减、层级、最近度、实体）
- **增量优先写入**，具有置信度门控取代
- **多轮修剪**、晋升质量门控、7 天指标
- **本地 SQLite**（WAL，默认离线）；可选混合嵌入，位于标志后
## 快速入门
### 1. 要求
- Node.js **20+**
### 2. 安装（推荐）
发布到 npm 后，无需克隆或绝对路径：
```bash
# 烟雾测试
npx -y @umg0/umg0 retain --content "记住：优先使用 TypeScript 严格模式" --tier semantic
npx -y @umg0/umg0 recall --query "TypeScript"
npx -y @umg0/umg0 stats
```
**MCP 配置**（首选 — 粘贴到 Claude Code、Cursor 等）：
```json
{
"mcpServers": {
"umg": {
"command": "npx",
"args": ["-y", "@umg0/umg0", "mcp"],
"env": {
"UMG_LOG_LEVEL": "info"
}
}
}
}
```
**全局安装**（比 npx 冷启动更快）：
```bash
npm install -g @umg0/umg0
```
```json
{
"mcpServers": {
"umg": {
"command": "umg0",
"args": ["mcp"]
}
}
}
```
**从此仓库**（发布前、离线或开发）：
```bash
git clone https://github.com/Hananahsan/umg.git
cd umg
npm install
npm run build
npm install -g . # 在 PATH 上公开 umg0
# 或直接运行：
node dist/index.js mcp
```
客户端示例： [examples/claude-code.mcp.json](./examples/claude-code.mcp.json) · [examples/cursor.mcp.json](./examples/cursor.mcp.json) · [examples/hermes.config.snippet.yaml](./examples/hermes.config.snippet.yaml) · [examples/vscode-cline.mcp.json](./examples/vscode-cline.mcp.json)
在保存配置后重启客户端。
**单一写入者：** 每个 DB 文件一个 MCP 进程。 将每个客户端指向 **相同** 的服务器命令/DB — 不要对一个 SQLite 文件运行多个写入者。
### 3. 可选：数据库路径
未设置时的默认值： `~/.umg/memory.db`（由配置解析）。仅当您需要自定义位置时设置 `UMG_DB_PATH` — 使用 **绝对** 路径（许多 MCP 主机不扩展 `~`）。
```bash
export UMG_DB_PATH="$HOME/.umg/memory.db"
```
### 4. 从源代码回退
仍然支持本地构建：
```json
{
"mcpServers": {
"umg": {
"command": "node",
"args": ["/absolute/path/to/umg/dist/index.js", "mcp"]
}
}
}
```
无需构建的开发：
```bash
npx tsx src/index.ts retain --content "..." --tier semantic
```
## 代理使用模式
在 **会话开始时：** 使用项目 + 任务（+ 实体名称）进行 `recall`。
当您学习到持久的内容时：`retain`（层级 `semantic` 用于首选项/决策）。
在 **会话结束时：** 使用短标记弹 bullet 进行 `reflect`。
定期：`prune`（先使用 `dry_run: true`）。
| 资源 | 用途 |
|----------|-----|
| [examples/session-start.md](./examples/session-start.md) | 会话开启剧本 |
| [examples/session-end.md](./examples/session-end.md) | 会话关闭检查清单 |
| [examples/coding-agent-prompt.md](./examples/coding-agent-prompt.md) | 编码代理系统提示 |
| [examples/agent-system-prompt.md](./examples/agent-system-prompt.md) | 通用代理提示 |
| [examples/workflows/daily-coding.md](./examples/workflows/daily-coding.md) | 全天工具序列 |
| [examples/claude-code-hooks.md](./examples/claude-code-hooks.md) | 可选的 Claude Code 停止钩子 |
## 内存层次结构
| 层级 | 目的 | 默认压力 |
|------|---------|------------------|
| `working` | 当前任务草稿 | 24 小时 TTL，限制 50 |
| `episodic` | 特定交互 | 30 天 TTL，限制 500 |
| `semantic` | 事实、首选项、决策 | 365 天，限制 1000 |
| `procedural` | 技能 / 课程 | 近乎永恒，限制 200 |
## 配置
复制 [config.example.yaml](./config.example.yaml) 到 `~/.umg/config.yaml` 或 `./umg.config.yaml`。
| 环境变量 | 含义 |
|-----|---------|
| `UMG_DB_PATH` | SQLite 文件路径 |
| `UMG_NAMESPACE` | 默认命名空间 |
| `UMG_LOG_LEVEL` | `debug` \| `info` \| `warn` \| `error` |
| `UMG_LLM_ENABLED` | `true` 启用可选 LLM 反射 |
| `UMG_EMBEDDINGS_ENABLED` | `true` 启用可选混合嵌入 |
| `UMG_HARD_ISOLATION` | `true` 强制默认命名空间在召回时 |
## CLI
```bash
umg0 mcp
umg0 retain --content "..." [--tier semantic] [--namespace global]
umg0 recall --query "..." [--limit 8]
umg0 reflect --text "..."
umg0 promote --ids id1,id2 [--dry-run]
umg0 prune [--dry-run] [--aggressive] [--namespace ns]
umg0 stats
umg0 compact [--export-archives]
umg0 version
umg0 help
```
另外： `npx -y @umg0/umg0 <command>` 和 `node dist/index.js <command>`。
## 测试
```bash
npm test
npm run e2e
```
## 营销网站（umg0）
```bash
cd site && npm install && npm run dev
```
## 架构
请参阅 [ARCHITECTURE.md](./ARCHITECTURE.md)。
## 超出范围（当前）
多后端路由（Mem0/Zep）、多租户云、UI 仪表板、图数据库、远程/HTTP MCP 传输、证明/联合。
## 许可证
MIT
