Skip to content
Back to search

Ombre-Brain

For Claude.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/p0lar1zzz--ombre-brain/badge.svg)](/listings/p0lar1zzz--ombre-brain)

HTML

<a href="/listings/p0lar1zzz--ombre-brain"><img src="/api/listings/p0lar1zzz--ombre-brain/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

环境要求 / Requirements

- Python 3.11+ - 一个 Obsidian Vault(可选,不用也行,会在项目目录下自建 `buckets/`) An Obsidian vault (optional — without one, it uses a local `buckets/` directory)

步骤 / Steps

git clone https://github.com/P0lar1zzZ/Ombre-Brain.git
cd Ombre-Brain

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install -r requirements.txt

复制配置文件并按需修改 / Copy config and edit as needed:

cp config.example.yaml config.yaml

如果你要用 API 做脱水压缩和自动打标(推荐,效果好很多),设置环境变量: If you want API-powered dehydration and tagging (recommended, much better quality):

export OMBRE_API_KEY="your-api-key"

支持任何 OpenAI 兼容 API。在 `config.yaml` 里改 `base_url` 和 `model` 就行。 Supports any OpenAI-compatible API. Just change `base_url` and `model` in `config.yaml`.

接入 Claude Desktop / Connect to Claude Desktop

在 Claude Desktop 配置文件中添加(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

Add to your Claude Desktop config:

{
  "mcpServers": {
    "ombre-brain": {
      "command": "python",
      "args": ["/path/to/Ombre-Brain/server.py"],
      "env": {
        "OMBRE_API_KEY": "your-api-key"
      }
    }
  }
}

接入 Claude.ai (远程) / Connect to Claude.ai (remote)

需要 HTTP 传输 + 隧道。可以用 Docker: Requires HTTP transport + tunnel. Docker setup:

echo "OMBRE_API_KEY=your-api-key" > .env
docker-compose up -d

`docker-compose.yml` 里配好了 Cloudflare Tunnel。你需要自己在 `~/.cloudflared/` 下放凭证和路由配置。 The `docker-compose.yml` includes Cloudflare Tunnel. You'll need your own credentials under `~/.cloudflared/`.

指向 Obsidian / Point to Obsidian

在 `config.yaml` 里设置 `buckets_dir`: Set `buckets_dir` in `config.yaml`:

buckets_dir: "/path/to/your/Obsidian Vault/Ombre Brain"

不设的话,默认用项目目录下的 `buckets/`。 If not set, defaults to `buckets/` in the project directory.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 339 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Ombre Brain
  2. 一个给提供给Claude 用的长期情绪记忆系统。基于 Russell 效价/唤醒度坐标打标,Obsidian 做存储层,MCP 接入,带遗忘曲线。
  3. A long-term emotional memory system for Claude. Tags memories using Russell's valence/arousal coordinates, stores them as Obsidian-compatible Markdown, connects via MCP, and has a forgetting curve.
  4. [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/P0lar1zzZ/Ombre-Brain)
  5. ---
  6. ## 它是什么 / What is this
  7. Claude 没有跨对话记忆。每次对话结束,之前聊过的所有东西都会消失。
  8. Ombre Brain 给了它一套持久记忆——不是那种冷冰冰的键值存储,而是带情感坐标的、会自然衰减的、像人类记忆一样会遗忘和浮现的系统。
  9. Claude has no cross-conversation memory. Everything from a previous chat vanishes once it ends.
  10. Ombre Brain gives it persistent memory — not cold key-value storage, but a system with emotional coordinates, natural decay, and forgetting/surfacing mechanics that loosely mimic how human memory works.
  11. 核心特点 / Key features:
  12. - **情感坐标打标 / Emotional tagging**: 每条记忆用 Russell 环形情感模型的 valence(效价)和 arousal(唤醒度)两个连续维度标记。不是"开心/难过"这种离散标签。
  13. Each memory is tagged with two continuous dimensions from Russell's circumplex model: valence and arousal. Not discrete labels like "happy/sad".
  14. - **自然遗忘 / Natural forgetting**: 改进版艾宾浩斯遗忘曲线。不活跃的记忆自动衰减归档,高情绪强度的记忆衰减更慢。
  15. Modified Ebbinghaus forgetting curve. Inactive memories naturally decay and archive. High-arousal memories decay slower.
  16. - **权重池浮现 / Weight pool surfacing**: 记忆不是被动检索的,它们会主动浮现——未解决的、情绪强烈的记忆权重更高,会在对话开头自动推送。
  17. Memories aren't just passively retrieved — they actively surface. Unresolved, emotionally intense memories carry higher weight and get pushed at conversation start.
  18. - **Obsidian 原生 / Obsidian-native**: 每个记忆桶就是一个 Markdown 文件,YAML frontmatter 存元数据。可以直接在 Obsidian 里浏览、编辑、搜索。自动注入 `[[双链]]`。
  19. Each memory bucket is a Markdown file with YAML frontmatter. Browse, edit, and search directly in Obsidian. Wikilinks are auto-injected.
  20. - **API 降级 / API degradation**: 脱水压缩和自动打标优先用廉价 LLM API(DeepSeek 等),API 不可用时自动降级到本地关键词分析——始终可用。
  21. Dehydration and auto-tagging prefer a cheap LLM API (DeepSeek etc.). When the API is unavailable, it degrades to local keyword analysis — always functional.
  22. ## 边界说明 / Design boundaries
  23. 官方记忆功能已经在做身份层的事了——你是谁,你有什么偏好,你们的关系是什么。那一层交给它,Ombre Brain不打算造重复的轮子。
  24. Ombre Brain 的边界是时间里发生的事,不是你是谁。它记住的是:你们聊过什么,经历了什么,哪些事情还悬在那里没有解决。两层配合用,才是完整的。
  25. 每次新对话,Claude 从零开始——但它能从 Ombre Brain 里找回跟你有关的一切。不是重建,是接续。
  26. ---
  27. Official memory already handles the identity layer — who you are, what you prefer, what your relationship is. That layer belongs there. Ombre Brain isn't trying to duplicate it.
  28. Ombre Brain's boundary is *what happened in time*, not *who you are*. It holds conversations, experiences, unresolved things. The two layers together are what make it feel complete.
  29. Each new conversation starts fresh — but Claude can reach back through Ombre Brain and find everything that happened between you. Not a rebuild. A continuation.
  30. ## 架构 / Architecture
  31. ```
  32. Claude ←→ MCP Protocol ←→ server.py
  33. │
  34. ┌───────────────┼───────────────┐
  35. │ │ │
  36. bucket_manager dehydrator decay_engine
  37. (CRUD + 搜索) (压缩 + 打标) (遗忘曲线)
  38. │
  39. Obsidian Vault (Markdown files)
  40. ```
  41. 5 个 MCP 工具 / 5 MCP tools:
  42. | 工具 Tool | 作用 Purpose |
  43. |-----------|-------------|
  44. | `breath` | 浮现或检索记忆。无参数=推送未解决记忆;有参数=关键词+情感检索 / Surface or search memories |
  45. | `hold` | 存储单条记忆,自动打标+合并相似桶 / Store a single memory with auto-tagging |
  46. | `grow` | 日记归档,自动拆分长内容为多个记忆桶 / Diary digest, auto-split into multiple buckets |
  47. | `trace` | 修改元数据、标记已解决、删除 / Modify metadata, mark resolved, delete |
  48. | `pulse` | 系统状态 + 所有记忆桶列表 / System status + bucket listing |
  49. ## 安装 / Setup
  50. ### 环境要求 / Requirements
  51. - Python 3.11+
  52. - 一个 Obsidian Vault(可选,不用也行,会在项目目录下自建 `buckets/`)
  53. An Obsidian vault (optional — without one, it uses a local `buckets/` directory)
  54. ### 步骤 / Steps
  55. ```bash
  56. git clone https://github.com/P0lar1zzZ/Ombre-Brain.git
  57. cd Ombre-Brain
  58. python -m venv .venv
  59. source .venv/bin/activate # Windows: .venv\Scripts\activate
  60. pip install -r requirements.txt
  61. ```
  62. 复制配置文件并按需修改 / Copy config and edit as needed:
  63. ```bash
  64. cp config.example.yaml config.yaml
  65. ```
  66. 如果你要用 API 做脱水压缩和自动打标(推荐,效果好很多),设置环境变量:
  67. If you want API-powered dehydration and tagging (recommended, much better quality):
  68. ```bash
  69. export OMBRE_API_KEY="your-api-key"
  70. ```
  71. 支持任何 OpenAI 兼容 API。在 `config.yaml` 里改 `base_url` 和 `model` 就行。
  72. Supports any OpenAI-compatible API. Just change `base_url` and `model` in `config.yaml`.
  73. ### 接入 Claude Desktop / Connect to Claude Desktop
  74. 在 Claude Desktop 配置文件中添加(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
  75. Add to your Claude Desktop config:
  76. ```json
  77. {
  78. "mcpServers": {
  79. "ombre-brain": {
  80. "command": "python",
  81. "args": ["/path/to/Ombre-Brain/server.py"],
  82. "env": {
  83. "OMBRE_API_KEY": "your-api-key"
  84. }
  85. }
  86. }
  87. }
  88. ```
  89. ### 接入 Claude.ai (远程) / Connect to Claude.ai (remote)
  90. 需要 HTTP 传输 + 隧道。可以用 Docker:
  91. Requires HTTP transport + tunnel. Docker setup:
  92. ```bash
  93. echo "OMBRE_API_KEY=your-api-key" > .env
  94. docker-compose up -d
  95. ```
  96. `docker-compose.yml` 里配好了 Cloudflare Tunnel。你需要自己在 `~/.cloudflared/` 下放凭证和路由配置。
  97. The `docker-compose.yml` includes Cloudflare Tunnel. You'll need your own credentials under `~/.cloudflared/`.
  98. ### 指向 Obsidian / Point to Obsidian
  99. 在 `config.yaml` 里设置 `buckets_dir`:
  100. Set `buckets_dir` in `config.yaml`:
  101. ```yaml
  102. buckets_dir: "/path/to/your/Obsidian Vault/Ombre Brain"
  103. ```
  104. 不设的话,默认用项目目录下的 `buckets/`。
  105. If not set, defaults to `buckets/` in the project directory.
  106. ## 配置 / Configuration
  107. 所有参数在 `config.yaml`(从 `config.example.yaml` 复制)。关键的几个:
  108. All parameters in `config.yaml` (copy from `config.example.yaml`). Key ones:
  109. | 参数 Parameter | 说明 Description | 默认 Default |
  110. |---|---|---|
  111. | `transport` | `stdio`(本地)/ `streamable-http`(远程)| `stdio` |
  112. | `buckets_dir` | 记忆桶存储路径 / Bucket storage path | `./buckets/` |
  113. | `dehydration.model` | 脱水用的 LLM 模型 / LLM model for dehydration | `deepseek-chat` |
  114. | `dehydration.base_url` | API 地址 / API endpoint | `https://api.deepseek.com/v1` |
  115. | `decay.lambda` | 衰减速率,越大越快忘 / Decay rate | `0.05` |
  116. | `decay.threshold` | 归档阈值 / Archive threshold | `0.3` |
  117. | `merge_threshold` | 合并相似度阈值 (0-100) / Merge similarity | `75` |
  118. 敏感配置用环境变量:
  119. Sensitive config via env vars:
  120. - `OMBRE_API_KEY` — LLM API 密钥
  121. - `OMBRE_TRANSPORT` — 覆盖传输方式
  122. - `OMBRE_BUCKETS_DIR` — 覆盖存储路径
  123. ## 衰减公式 / Decay Formula
  124. $$final\_score = time\_weight \times base\_score$$
  125. $$base\_score = Importance \times activation\_count^{0.3} \times e^{-\lambda \times days} \times (base + arousal \times boost)$$
  126. 时间系数(乘数,优先级最高)/ Time weight (multiplier, highest priority):
  127. | 距今天数 Days since active | 时间系数 Weight |
  128. |---|---|
  129. | 0–1 天 | 1.0 |
  130. | 第 2 天 | 0.9 |
  131. | 之后每天约降 10% | `max(0.3, 0.9 × e^{-0.2197 × (days-2)})` |
  132. | 7 天后稳定 | ≈ 0.3(不归零)|
  133. - `importance`: 1-10,记忆重要性 / memory importance
  134. - `activation_count`: 被检索的次数,越常被想起衰减越慢 / retrieval count; more recalls = slower decay
  135. - `days`: 距上次激活的天数 / days since last activation
  136. - `arousal`: 唤醒度,越强烈的记忆越难忘 / arousal; intense memories are harder to forget
  137. - 已解决的记忆权重降到 5%,沉底等被关键词唤醒 / resolved memories drop to 5%, sink until keyword-triggered
  138. - `pinned=true` 的桶:不衰减、不合并、importance 锁定 10 / `pinned` buckets: never decay, never merge, importance locked at 10
  139. ## 给 Claude 的使用指南 / Usage Guide for Claude
  140. `CLAUDE_PROMPT.md` 是写给 Claude 看的使用说明。放到你的 system prompt 或 custom instructions 里就行。
  141. `CLAUDE_PROMPT.md` is the usage guide written for Claude. Put it in your system prompt or custom instructions.
  142. ## 工具脚本 / Utility Scripts
  143. | 脚本 Script | 用途 Purpose |
  144. |---|---|
  145. | `write_memory.py` | 手动写入记忆,绕过 MCP / Manually write memories, bypass MCP |
  146. | `migrate_to_domains.py` | 迁移平铺文件到域子目录 / Migrate flat files to domain subdirs |
  147. | `reclassify_domains.py` | 基于关键词重分类 / Reclassify by keywords |
  148. | `reclassify_api.py` | 用 API 重打标未分类桶 / Re-tag uncategorized buckets via API |
  149. | `test_smoke.py` | 冒烟测试 / Smoke test |
  150. ## 部署 / Deploy
  151. ### Render
  152. [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/P0lar1zzZ/Ombre-Brain)
  153. > ⚠️ **免费层不可用**:Render 免费层**不支持持久化磁盘**,服务重启后记忆数据会丢失,且会在无流量时休眠。**必须使用 Starter($7/mo)或以上**才能正常使用。
  154. > **Free tier won't work**: Render free tier has **no persistent disk** — all memory data is lost on restart. It also sleeps on inactivity. **Starter plan ($7/mo) or above is required.**
  155. 项目根目录已包含 `render.yaml`,点击按钮后:
  156. 1. (可选)设置 `OMBRE_API_KEY`:任何 OpenAI 兼容 API 的 key,不填则自动降级为本地关键词提取
  157. 2. (可选)设置 `OMBRE_BASE_URL`:API 地址,支持任意 OpenAI 化地址,如 `https://api.deepseek.com/v1` / `http://123.1.1.1:7689/v1` / `http://your-ollama:11434/v1`
  158. 3. Render 自动挂载持久化磁盘到 `/opt/render/project/src/buckets`
  159. 4. 部署后 MCP URL:`https://<你的服务名>.onrender.com/mcp`
  160. `render.yaml` is included. After clicking the button:
  161. 1. (Optional) `OMBRE_API_KEY`: any OpenAI-compatible key; omit to fall back to local keyword extraction
  162. 2. (Optional) `OMBRE_BASE_URL`: any OpenAI-compatible endpoint, e.g. `https://api.deepseek.com/v1`, `http://123.1.1.1:7689/v1`, `http://your-ollama:11434/v1`
  163. 3. Persistent disk auto-mounts at `/opt/render/project/src/buckets`
  164. 4. MCP URL after deploy: `https://<your-service>.onrender.com/mcp`
  165. ### Zeabur
  166. > 💡 **Zeabur 的定价模式**:Zeabur 是「买 VPS + 平台托管」,你先购买一台服务器(最低腾讯云新加坡 $2/mo、火山引擎 $3/mo),Volume 直接挂在该服务器上,**数据天然持久化,无丢失问题**。另需订阅 Zeabur 管理方案(Developer $5/mo),总计约 $7-8/mo 起。
  167. > **Zeabur pricing model**: You buy a VPS first (cheapest: Tencent Cloud Singapore ~$2/mo, Volcano Engine ~$3/mo), then add Zeabur's Developer plan ($5/mo) for management. Volumes mount directly on your server — **data is always persistent, no cold-start data loss**. Total ~$7-8/mo minimum.
  168. **步骤 / Steps:**
  169. 1. **创建项目 / Create project**
  170. - 打开 [zeabur.com](https://zeabur.com) → 购买一台服务器 → **New Project** → **Deploy from GitHub**
  171. - 先 Fork 本仓库到自己 GitHub 账号,然后在 Zeabur 选择 `你的用户名/Ombre-Brain`
  172. - Zeabur 会自动检测到根目录的 `Dockerfile` 并使用 Docker 方式构建
  173. - Go to [zeabur.com](https://zeabur.com) → buy a server → **New Project** → **Deploy from GitHub**
  174. - Fork this repo first, then select `your-username/Ombre-Brain` in Zeabur
  175. - Zeabur auto-detects the `Dockerfile` in root and builds via Docker
  176. 2. **设置环境变量 / Set environment variables**(服务页面 → **Variables** 标签页)
  177. - `OMBRE_API_KEY`(可选)— LLM API 密钥,不填则自动降级为本地关键词提取
  178. - `OMBRE_BASE_URL`(可选)— API 地址,如 `https://api.deepseek.com/v1`
  179. > ⚠️ **不需要**手动设置 `OMBRE_TRANSPORT` 和 `OMBRE_BUCKETS_DIR`,Dockerfile 里已经设好了默认值。Zeabur 对单阶段 Dockerfile 会自动注入控制台设置的环境变量。
  180. > You do **NOT** need to set `OMBRE_TRANSPORT` or `OMBRE_BUCKETS_DIR` — defaults are baked into the Dockerfile. Zeabur auto-injects dashboard env vars for single-stage Dockerfiles.
  181. 3. **挂载持久存储 / Mount persistent volume**(服务页面 → **Volumes** 标签页)
  182. - Volume ID:填 `ombre-buckets`(或任意名)
  183. - 挂载路径 / Path:**`/app/buckets`**
  184. - ⚠️ 不挂载的话,每次重新部署记忆数据会丢失
  185. - ⚠️ Without this, memory data is lost on every redeploy
  186. 4. **配置端口 / Configure port**(服务页面 → **Networking** 标签页)
  187. - Port Name:`web`(或任意名)
  188. - Port:**`8000`**
  189. - Port Type:**`HTTP`**
  190. - 然后点 **Generate Domain** 生成一个 `xxx.zeabur.app` 域名
  191. - Then click **Generate Domain** to get a `xxx.zeabur.app` domain
  192. 5. **验证 / Verify**
  193. - 访问 `https://<你的域名>.zeabur.app/health`,应返回 JSON
  194. - Visit `https://<your-domain>.zeabur.app/health` — should return JSON
  195. - 最终 MCP 地址 / MCP URL:`https://<你的域名>.zeabur.app/mcp`
  196. **常见问题 / Troubleshooting:**
  197. | 现象 Symptom | 原因 Cause | 解决 Fix |
  198. |---|---|---|
  199. | 域名无法访问 / Domain unreachable | 没配端口 / Port not configured | Networking 标签页加 port 8000 (HTTP) |
  200. | 域名无法访问 / Domain unreachable | `OMBRE_TRANSPORT` 未设置,服务以 stdio 模式启动,不监听任何端口 / Service started in stdio mode — no port is listened | **Variables 标签页确认设置 `OMBRE_TRANSPORT=streamable-http`,然后重新部署** |
  201. | 构建失败 / Build failed | Dockerfile 未被识别 / Dockerfile not detected | 确认仓库根目录有 `Dockerfile`(大小写敏感) |
  202. | 服务启动后立刻退出 | `OMBRE_TRANSPORT` 被覆盖为 `stdio` | 检查 Variables 里有没有多余的 `OMBRE_TRANSPORT=stdio`,删掉即可 |
  203. | 重启后记忆丢失 / Data lost on restart | Volume 未挂载 | Volumes 标签页挂载到 `/app/buckets` |
  204. ### 使用 Cloudflare Tunnel 或 ngrok 连接 / Connecting via Cloudflare Tunnel or ngrok
  205. > ℹ️ 自 v1.1 起,server.py 在 HTTP 模式下已自动添加 CORS 中间件,无需额外配置。
  206. > Since v1.1, server.py automatically enables CORS middleware in HTTP mode — no extra config needed.
  207. 使用隧道连接时,确保以下条件满足:
  208. When connecting via tunnel, ensure:
  209. 1. **服务器必须运行在 HTTP 模式** / Server must use HTTP transport
  210. ```bash
  211. OMBRE_TRANSPORT=streamable-http python server.py
  212. ```
  213. 或 Docker:
  214. ```bash
  215. docker-compose up -d
  216. ```
  217. 2. **在 Claude.ai 网页版添加 MCP 服务器** / Adding to Claude.ai web
  218. - URL 格式 / URL format: `https://<tunnel-subdomain>.trycloudflare.com/mcp`
  219. - 或 ngrok / or ngrok: `https://<xxxx>.ngrok-free.app/mcp`
  220. - 先访问 `/health` 验证连接 / Verify first: `https://<your-tunnel>/health` should return `{"status":"ok",...}`
  221. 3. **已知限制 / Known limitations**
  222. - Cloudflare Tunnel 免费版有空闲超时(约 10 分钟),系统内置保活 ping 可缓解但不能完全消除
  223. - Free Cloudflare Tunnel has idle timeout (~10 min); built-in keepalive pings mitigate but can't fully prevent it
  224. - ngrok 免费版有请求速率限制 / ngrok free tier has rate limits
  225. - 如果连接仍失败,检查隧道是否正在运行、服务是否以 `streamable-http` 模式启动
  226. - If connection still fails, verify the tunnel is running and the server started in `streamable-http` mode
  227. | 现象 Symptom | 原因 Cause | 解决 Fix |
  228. |---|---|---|
  229. | 网页版无法连接隧道 URL / Web can't connect to tunnel URL | 服务以 stdio 模式运行 / Server in stdio mode | 设置 `OMBRE_TRANSPORT=streamable-http` 后重启 |
  230. | 网页版无法连接隧道 URL / Web can't connect to tunnel URL | 旧版 server.py 缺少 CORS 头 / Missing CORS headers | 拉取最新代码,CORS 已内置 / Pull latest — CORS is now built-in |
  231. | `/health` 返回 200 但 MCP 连不上 / `/health` 200 but MCP fails | 路径错误 / Wrong path | MCP URL 末尾必须是 `/mcp` 而非 `/` |
  232. | 隧道连接偶尔断开 / Tunnel disconnects intermittently | Cloudflare Tunnel 空闲超时 / Idle timeout | 保活 ping 已内置,若仍断开可缩短隧道超时配置 |
  233. ---
  234. ### Session Start Hook(自动 breath)
  235. 部署后,如果你使用 Claude Code,可以在项目内激活自动浮现 hook:
  236. `.claude/settings.json` 已配置好 `SessionStart` hook,每次新会话或恢复会话时自动触发 `breath`,把最高权重未解决记忆推入上下文。
  237. **仅在远程 HTTP 模式下有效**(`OMBRE_TRANSPORT=streamable-http`)。本地 stdio 模式下 hook 会安静退出,不影响正常使用。
  238. 可以通过 `OMBRE_HOOK_URL` 环境变量指定服务器地址(默认 `http://localhost:8000`),或者设置 `OMBRE_HOOK_SKIP=1` 临时禁用。
  239. If using Claude Code, `.claude/settings.json` configures a `SessionStart` hook that auto-calls `breath` on each new or resumed session, surfacing your highest-weight unresolved memories as context. Only active in remote HTTP mode. Set `OMBRE_HOOK_SKIP=1` to disable temporarily.
  240. ## License
  241. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.