一个给提供给Claude 用的长期情绪记忆系统。基于 Russell 效价/唤醒度坐标打标,Obsidian 做存储层,MCP 接入,带遗忘曲线。
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.
Claude has no cross-conversation memory. Everything from a previous chat vanishes once it ends.
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.
核心特点 / Key features:
情感坐标打标 / Emotional tagging: 每条记忆用 Russell 环形情感模型的 valence(效价)和 arousal(唤醒度)两个连续维度标记。不是"开心/难过"这种离散标签。
Each memory is tagged with two continuous dimensions from Russell's circumplex model: valence and arousal. Not discrete labels like "happy/sad".
权重池浮现 / Weight pool surfacing: 记忆不是被动检索的,它们会主动浮现——未解决的、情绪强烈的记忆权重更高,会在对话开头自动推送。
Memories aren't just passively retrieved — they actively surface. Unresolved, emotionally intense memories carry higher weight and get pushed at conversation start.
Obsidian 原生 / Obsidian-native: 每个记忆桶就是一个 Markdown 文件,YAML frontmatter 存元数据。可以直接在 Obsidian 里浏览、编辑、搜索。自动注入 [[双链]]。
Each memory bucket is a Markdown file with YAML frontmatter. Browse, edit, and search directly in Obsidian. Wikilinks are auto-injected.
API 降级 / API degradation: 脱水压缩和自动打标优先用廉价 LLM API(DeepSeek 等),API 不可用时自动降级到本地关键词分析——始终可用。
Dehydration and auto-tagging prefer a cheap LLM API (DeepSeek etc.). When the API is unavailable, it degrades to local keyword analysis — always functional.
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.
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.
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.
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:
迁移平铺文件到域子目录 / Migrate flat files to domain subdirs
reclassify_domains.py
基于关键词重分类 / Reclassify by keywords
reclassify_api.py
用 API 重打标未分类桶 / Re-tag uncategorized buckets via API
test_smoke.py
冒烟测试 / Smoke test
部署 / Deploy
Render
⚠️ 免费层不可用:Render 免费层不支持持久化磁盘,服务重启后记忆数据会丢失,且会在无流量时休眠。必须使用 Starter($7/mo)或以上才能正常使用。
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.
项目根目录已包含 render.yaml,点击按钮后:
(可选)设置 OMBRE_API_KEY:任何 OpenAI 兼容 API 的 key,不填则自动降级为本地关键词提取
render.yaml is included. After clicking the button:
(Optional) OMBRE_API_KEY: any OpenAI-compatible key; omit to fall back to local keyword extraction
(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
Persistent disk auto-mounts at /opt/render/project/src/buckets
MCP URL after deploy: https://<your-service>.onrender.com/mcp
Zeabur
💡 Zeabur 的定价模式:Zeabur 是「买 VPS + 平台托管」,你先购买一台服务器(最低腾讯云新加坡 $2/mo、火山引擎 $3/mo),Volume 直接挂在该服务器上,数据天然持久化,无丢失问题。另需订阅 Zeabur 管理方案(Developer $5/mo),总计约 $7-8/mo 起。
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.
步骤 / Steps:
创建项目 / Create project
打开 zeabur.com → 购买一台服务器 → New Project → Deploy from GitHub
Go to zeabur.com → buy a server → New Project → Deploy from GitHub
Fork this repo first, then select your-username/Ombre-Brain in Zeabur
Zeabur auto-detects the Dockerfile in root and builds via Docker
设置环境变量 / Set environment variables(服务页面 → Variables 标签页)
OMBRE_API_KEY(可选)— LLM API 密钥,不填则自动降级为本地关键词提取
OMBRE_BASE_URL(可选)— API 地址,如 https://api.deepseek.com/v1
⚠️ 不需要手动设置 OMBRE_TRANSPORT 和 OMBRE_BUCKETS_DIR,Dockerfile 里已经设好了默认值。Zeabur 对单阶段 Dockerfile 会自动注入控制台设置的环境变量。
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.
挂载持久存储 / Mount persistent volume(服务页面 → Volumes 标签页)
Volume ID:填 ombre-buckets(或任意名)
挂载路径 / Path:/app/buckets
⚠️ 不挂载的话,每次重新部署记忆数据会丢失
⚠️ Without this, memory data is lost on every redeploy
配置端口 / Configure port(服务页面 → Networking 标签页)
Port Name:web(或任意名)
Port:8000
Port Type:HTTP
然后点 Generate Domain 生成一个 xxx.zeabur.app 域名
Then click Generate Domain to get a xxx.zeabur.app domain
验证 / Verify
访问 https://<你的域名>.zeabur.app/health,应返回 JSON
Visit https://<your-domain>.zeabur.app/health — should return JSON
最终 MCP 地址 / MCP URL:https://<你的域名>.zeabur.app/mcp
常见问题 / Troubleshooting:
现象 Symptom
原因 Cause
解决 Fix
域名无法访问 / Domain unreachable
没配端口 / Port not configured
Networking 标签页加 port 8000 (HTTP)
域名无法访问 / Domain unreachable
OMBRE_TRANSPORT 未设置,服务以 stdio 模式启动,不监听任何端口 / Service started in stdio mode — no port is listened
使用 Cloudflare Tunnel 或 ngrok 连接 / Connecting via Cloudflare Tunnel or ngrok
ℹ️ 自 v1.1 起,server.py 在 HTTP 模式下已自动添加 CORS 中间件,无需额外配置。
Since v1.1, server.py automatically enables CORS middleware in HTTP mode — no extra config needed.
使用隧道连接时,确保以下条件满足:
When connecting via tunnel, ensure:
服务器必须运行在 HTTP 模式 / Server must use HTTP transport
OMBRE_TRANSPORT=streamable-http python server.py
或 Docker:
docker-compose up -d
在 Claude.ai 网页版添加 MCP 服务器 / Adding to Claude.ai web
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.
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich Ombre Brain?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt Ombre Brain einen API-Schlüssel?
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.