Octobrain

Octobrain

AI 助手的持久记忆——存储能够跨对话留存的见解、决策和知识。

MCP Registry：mcp-name: io.github.Muvon/octobrain

目录

• 为什么选择 Octobrain？
• 快速开始
• 安装
• 用法
• 功能
• 基准测试
• 配置
• 记忆类型
• MCP 集成
• 存储位置
• 贡献
• 许可证

Octobrain 为你的 AI 助手提供长期记忆。存储代码见解、架构决策、错误修复和知识，然后在未来的会话中通过语义搜索检索。它既可作为 CLI 工具使用，也可作为 MCP 服务，与 Claude Desktop 和其他 AI 工具集成。

为什么选择 Octobrain？

AI 助手每次开始对话时都没有任何上下文。你每次都得解释项目、偏好和决策。Octobrain 打破这一循环：

• 持久记忆 — 见解会跨会话留存，而不只是存在于当前会话中
• 语义搜索 — 按含义查找记忆，而非匹配确切关键词
• 自动关联 — 相关记忆会自动建立联系（Zettelkasten 风格）
• 知识索引 — 摄取文档、文章和文件，供后续检索
• MCP 集成 — 可与 Claude Desktop 和其他兼容 MCP 的工具配合使用

快速开始

# Install from crates.io
cargo install octobrain

# Store your first memory
octobrain memory memorize --title "API Design Pattern" \
  --content "Use REST for CRUD, GraphQL for complex queries" \
  --memory-type architecture --tags "api,design"

# Search memories
octobrain memory remember "how should I design APIs"

# Start MCP server for Claude Desktop integration
octobrain mcp

安装

从 crates.io 安装（推荐）

cargo install octobrain

从源代码安装

# Clone and build
git clone https://github.com/muvon/octobrain.git
cd octobrain
cargo build --release

# Binary location
./target/release/octobrain --help

Docker

docker pull ghcr.io/muvon/octobrain:latest

Homebrew（macOS/Linux）

brew install muvon/tap/octobrain

功能标志

Octobrain 支持多个嵌入提供商：

标志	说明	是否需要 API 密钥
fastembed	通过 FastEmbed 生成本地嵌入	否
huggingface	通过 HuggingFace 生成本地嵌入	否
(default)	同时启用 fastembed + huggingface	否
(no features)	基于 API：Voyage、OpenAI、Google、Jina	是

# Build with local embeddings (default, no API keys needed)
cargo build --release

# Build with API-based embeddings only
cargo build --no-default-features --release

对于基于 API 的嵌入，请设置相应的环境变量：

• VOYAGE_API_KEY 用于 Voyage AI
• OPENAI_API_KEY 用于 OpenAI
• GOOGLE_API_KEY 用于 Google
• JINA_API_KEY 用于 Jina

用法

记忆管理

存储和检索见解、决策和上下文：

所有 memory 子命令都接受全局标志：

• --scope <string> — 覆盖项目范围（默认：根据 Git 远程仓库自动检测）
• --role <string> — 按角色筛选（例如 "developer"、"reviewer"）

# Store a memory
octobrain memory memorize --title "API Design" \
  --content "Use REST for CRUD, GraphQL for complex queries" \
  --memory-type architecture --tags "api,design"

# Search memories (semantic search)
octobrain memory remember "api design patterns"

# Multi-query search for broader coverage
octobrain memory remember "authentication" "security" "jwt"

# Get a memory by ID
octobrain memory get <id>

# Get recent memories
octobrain memory recent --limit 20

# Filter by type
octobrain memory by-type architecture --limit 10

# Filter by tags
octobrain memory by-tags "api,security"

# Find memories related to files
octobrain memory for-files "src/main.rs,src/lib.rs"

# Update a memory
octobrain memory update <id> --title "New Title" --add-tags "new-tag"

# Delete a memory
octobrain memory forget --memory-id <id>

# Get memories relevant to the current Git commit
octobrain memory current-commit

# Show memory statistics
octobrain memory stats

# Clean up old/low-importance memories
octobrain memory cleanup

# Compact tables and refresh indices (run when searches slow down)
octobrain memory maintenance

# ⚠️ Delete ALL memory data
octobrain memory clear-all --yes

记忆整合

关闭一个目标，并将其所有相关记忆整合成一份摘要：

# Consolidate a goal (Achieves-link sources → Consolidated state, importance dampened)
octobrain memory consolidate <goal-id> --summary "Final summary"

# Sleep consolidation: auto-cluster recent similar memories
octobrain memory sleep-consolidate --threshold 0.85 --min-size 3

记忆关系

关联相关记忆，以便检索时获得丰富的上下文：

# Create a relationship between memories
octobrain memory relate <source-id> <target-id> \
  --relationship-type "depends_on" \
  --description "Source requires target to function"

# View relationships for a memory
octobrain memory relationships <memory-id>

# Find related memories through relationships
octobrain memory related <memory-id>

# Auto-link similar memories (Zettelkasten-style)
octobrain memory auto-link <memory-id>

# Explore memory graph
octobrain memory graph <memory-id> --depth 2

知识库

索引和搜索网页内容、文档和文件：

# Index a URL
octobrain knowledge index https://docs.rs/tokio/latest/tokio/

# Index a local file (.txt, .md, .pdf, .docx, .html)
octobrain knowledge index ./docs/architecture.md

# Search knowledge base
octobrain knowledge search "how to handle async tasks"

# Search within a specific source (auto-indexes if outdated)
octobrain knowledge search "spawn blocking" --source https://docs.rs/tokio/

# Read full content of a URL or local file
octobrain knowledge read https://docs.rs/tokio/latest/tokio/

# Search indexed content by regex pattern
octobrain knowledge match "spawn_blocking|block_in_place"

# Store raw text content
octobrain knowledge store "meeting-notes" --content "Discussion points..."

# List indexed sources
octobrain knowledge list --limit 20

# Show statistics
octobrain knowledge stats

# Delete a source
octobrain knowledge delete https://example.com/docs

# Delete stored content by key
octobrain knowledge delete-stored "meeting-notes"

知识包

导入并同步与项目关联的 Git 知识包：

# Import a remote git repo as a knowledge box
octobrain box import https://github.com/org/docs-repo.git

# Import at global scope (visible in every project)
octobrain box import https://github.com/org/docs-repo.git --global

# Pull and re-index all subscribed boxes + local .box/ directories
octobrain box sync

# List subscribed boxes
octobrain box list

# Remove a box
octobrain box remove github.com/org/docs-repo

MCP 服务

作为 MCP 服务运行，以便与 Claude Desktop 和其他 AI 工具集成：

# Start with stdio transport (for Claude Desktop)
octobrain mcp

# Start with HTTP transport (for web-based tools)
octobrain mcp --bind 0.0.0.0:12345

可用的 MCP 工具：

工具	描述
memorize	存储带有元数据的记忆；可选的 related_to 用于建立内联关联
remember	使用筛选条件进行语义搜索；返回 1 跳图邻居
forget	删除记忆（需要确认）
knowledge	统一工具：通过 command 字段执行 search、store、delete、read、match
参见 MCP 集成，了解 Claude Desktop 的设置方法。

功能

• 语义搜索 — 使用向量嵌入按含义查找记忆，而非精确匹配关键词
• 混合搜索 — 结合 BM25 全文搜索与向量相似度，获得更好的结果
• 重排序支持 — 可插拔的交叉编码器重排序阶段（取决于提供方）
• 自动链接 — 自动关联语义相似的记忆（Zettelkasten 风格）
• 时间衰减 — 使用艾宾浩斯遗忘曲线管理重要性
• 知识索引 — 导入 URL、PDF、文档以供检索
• 项目范围限定 — 按 Git 项目隔离记忆，或在项目间共享
• 角色筛选 — 按角色（开发者、审阅者等）标记记忆
• 查询扩展（HyDE-lite） — 伪相关反馈可使长尾查询的召回率提升 10–30%
• MCP 协议 — 完全符合 MCP 2026-07-28 标准，支持 AI 工具集成

基准测试

octobrain 知识系统在标准 BEIR 数据集上的检索质量 — nDCG@10，完全本地运行，不使用 LLM 评判器，使用测试框架的默认嵌入模型 bge-small-en-v1.5（384 维，33M 参数）。每个语料库段落都通过 octobrain 的实际检索流程建立索引，并根据官方 qrels 评分（指标可复现 pytrec_eval 的结果）。

数据集	octobrain 向量	octobrain 混合	BM25¹	bge-small-en-v1.5²
SciFact（5.2K 篇文档，300 个查询）	0.722	0.742	0.665	0.713
NFCorpus（3.6K 篇文档，323 个查询）	0.341	0.363	0.325	0.343

• 向量 = 仅使用稠密检索；可复现该嵌入模型公开的 BEIR 数值（验证测试框架）。
• 混合 = BM25 + 向量通过倒数排名融合（k=60）进行融合 — octobrain 的默认模式。相比单独使用嵌入，nDCG@10 提高 +2，且在两个数据集上均优于经典 BM25。

¹ 来自 BEIR 论文的标准 BM25（Anserini/Lucene，k1=0.9 b=0.4）。 ² 来自 bge-small-en-v1.5 模型卡（MTEB）。

范围：此处衡量的是排序层（嵌入 + BM25 融合 + 重排序）。BEIR 段落已预先分块，因此这里不会测试 octobrain 的分块策略。

⚠️ 重排序器状态： 交叉编码器重排序器目前在 fastembed 模型下不起作用（结果与仅使用混合检索完全相同）。调查完成前，上述数据不包含重排序结果。详情请参见 benches/README.md。

复现（下载数据集、构建发布版二进制文件并完全离线运行）：

cd benches && bash scripts/run_retrieval.sh

配置

配置存储在 ~/.local/share/octobrain/config.toml 中。首次运行时写入的模板会定义所有选项并设置合理的默认值，但配置加载采用严格模式 — 手动删除字段会导致启动失败，而不会回退到默认值。

使用 OCTOBRAIN_CONFIG_PATH=/path/to/config.toml 覆盖配置文件位置。

关键设置

部分	选项	默认值	描述
[embedding]	model	fastembed:Qdrant/all-MiniLM-L6-v2-onnx	嵌入模型（provider:model 格式）。默认使用本地 fastembed 模型，无需 API 密钥，可在 CPU 上运行。
[search]	similarity_threshold	0.3	最低相关性（0.0-1.0）
[search.hybrid]	enabled	true	启用 BM25 + 向量融合
[search.reranker]	enabled	true	启用交叉编码器重排序
[search.hyde]	enabled	true	伪相关性反馈查询扩展
[memory]	max_memories	10000	存储记忆的上限
[memory]	auto_linking_enabled	true	自动关联相似记忆
[knowledge]	chunk_size	1200	每个分块的字符数
[embedding]	batch_size	32	每批嵌入的文本数
[embedding]	timeout_secs	30	嵌入调用超时时间（0 = 无超时）
[search]	max_results	50	任意搜索结果数的硬性上限
[search.reranker]	model	fastembed:jina-reranker-v2-base-multilingual	交叉编码器模型
[search.reranker]	top_k_candidates	50	重排序前检索的候选项数
[search.hyde]	top_k	3	用于计算质心的邻居数
[search.hyde]	alpha	0.5	原始查询嵌入的混合权重
[memory]	max_search_results	50	未指定限制时的默认页大小
[memory]	sleep_consolidation_enabled	true	管理器初始化时启用惰性睡眠整合
[memory]	sleep_consolidation_interval_hours	24	睡眠整合执行间隔（小时）
[knowledge]	outdating_days	15	搜索时重新索引已索引内容前的天数
[knowledge]	max_results	5	知识搜索返回的结果数

嵌入提供方

[embedding]
# Local models (no API key, runs on CPU, model auto-downloaded on first use)
model = "fastembed:Qdrant/all-MiniLM-L6-v2-onnx"                       # Default: 384-dim quantized, ~125MB resident
model = "fastembed:nomic-ai/nomic-embed-text-v1.5"                      # 768-dim, 8192-ctx, ~550MB weights, highest quality
model = "fastembed:BAAI/bge-small-en-v1.5"                              # 384-dim, ~62 MTEB, fast + good quality
model = "fastembed:sentence-transformers/all-MiniLM-L6-v2-quantized"  # Smallest (~22MB), fastest
model = "fastembed:BAAI/bge-base-en-v1.5"                              # Larger (~440MB), higher quality
model = "fastembed:intfloat/multilingual-e5-small"                     # Multilingual

# Cloud providers (require API keys, generally higher quality)
model = "voyage:voyage-3.5-lite"          # VOYAGE_API_KEY
model = "openai:text-embedding-3-small"   # OPENAI_API_KEY
model = "google:text-embedding-004"       # GOOGLE_API_KEY
model = "jina:jina-embeddings-v3"         # JINA_API_KEY

完整配置

所有可用选项及其文档，请参见 config-templates/default.toml。

记忆类型

按类别整理记忆，便于筛选：

类型	用途
code	代码模式、解决方案、实现
architecture	系统设计、决策、模式
bug_fix	Bug 修复、故障排查、解决方案
feature	功能规格、实现
documentation	文档、说明、知识
user_preference	设置、偏好、工作流
decision	项目决策、权衡
learning	教程、笔记、学习资料
configuration	设置、配置、部署
testing	测试策略、QA 洞见
performance	优化、基准测试
security	漏洞、修复、安全考量
validation	想法/产品验证、假设测试
research	技术/市场研究、分析
workflow	SOP、操作手册、流程说明
requirement	业务需求、规格、约束
design	UI/UX 决策、线框图、系统设计
integration	API 集成、第三方服务
communication	利益相关方动态、团队决策
process	部署流程、运行手册、运维
insight	通用见解、技巧
goal	用于整合工作流的任务/意图锚点

MCP 集成

Claude Desktop 设置

将以下内容添加到 Claude Desktop 配置中（macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "octobrain": {
      "command": "/path/to/octobrain",
      "args": ["mcp"]
    }
  }
}

重启 Claude Desktop。Octobrain 工具即可在对话中使用。

HTTP 传输

用于 Web 集成：

octobrain mcp --bind 0.0.0.0:12345

该服务在 /mcp 提供 MCP 协议通信端点。

存储位置

数据存储在平台专属目录中：

平台	位置
macOS	~/.local/share/octobrain/
Linux	~/.local/share/octobrain/ 或 $XDG_DATA_HOME/octobrain/
Windows	%APPDATA%\octobrain\

项目专属记忆按规范化的 Git 远程 URL 隔离（例如 github.com/org/repo）。

参与贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 运行 cargo fmt --all 格式化代码
4. 运行 cargo clippy 并修复所有警告
5. 运行 cargo test --no-default-features
6. 提交 Pull Request

开发环境设置

# Clone and build
git clone https://github.com/muvon/octobrain.git
cd octobrain
cargo build --no-default-features

# Run tests
cargo test --no-default-features

# Run clippy
cargo clippy --no-default-features

许可证

Apache-2.0 — 详情请参阅 LICENSE。

致谢

由 Muvon Un Limited 开发。