brainjar (Farad Labs)

🧠 脑震器

具有混合搜索的本地第一AI内存——FTS5、词汇模糊、图遍历和向量嵌入

brainjar为AI代理提供了完全由SQLite支持的持久、可搜索的内存。同步您的标记和代码文件，将实体提取到知识图中，并使用多个互补的引擎进行搜索。可作为独立的CLI或作为Claude Code、Cursor和任何MCP兼容工具的MCP服务器。

特性

• 混合搜索 --模糊校正FTS5+图遍历+向量KNN，通过RRF（互易秩融合）合并
• 词汇模糊 --通过SQLite Levenstein词汇表纠正拼写错误（无文件扫描）
• 图检索增强生成 --使用可配置的LLM后端（Gemini、OpenAI、Ollama）提取实体/关系
• 零云依赖 --完全离线运行；所有数据都存在于一个单一的 .db 文件
• MCP服务器 --stdio传输，适用于Claude Code、Cursor、Windsurf和任何MCP客户端
• 多个知识库 --隔离个人记忆、项目文档等。
• .布莱纳里诺 --同步过程中的gitignore风格文件过滤

快速开始

# Install Rust (if you don't have it)
brew install rust        # macOS (Homebrew)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh  # Linux/other

# Install brainjar
cargo install brainjar

# Initialize in your workspace (interactive wizard)
cd my-agent-workspace
brainjar init

# Sync your files
brainjar sync

# Re-embed all chunks (e.g. after changing embedding model/dimensions)
brainjar sync --reembed

# Search (fuzzy + graph + vector by default)
brainjar search "deployment workflow"

# Handles typos out of the box
brainjar search "deploymnt workflw"

搜索模式

旗帜是 可组合的: --graph --vector 运行图形+矢量而不进行文本搜索。无标志=完全默认（模糊+图形+矢量）。

# Default: fuzzy + graph + vector merged via RRF
brainjar search "deployment workflow"

# Typos corrected automatically
brainjar search "knowlege grph"

# Text only (BM25 relevance)
brainjar search --text "entity extraction"

# Graph only (traverses entity relationships)
brainjar search --graph "project entities"

# Raw file scanner (nucleo, returns file:line)
brainjar search --local "brainjar"

# Exact substring
brainjar search --exact "brainjar.toml"

# Limit results
brainjar search --limit 10 "search"

# Smart: LLM extracts 2-5 targeted queries from conversational text
brainjar search --smart "should we use flash lite for auto-recall entity extraction?"
# 🧠 Extracted 3 queries: "auto-recall", "flash lite", "entity extraction"
# Results from all queries, deduplicated and ranked

# Search a specific knowledge base
brainjar search --kb personal "morning routine"

# JSON output (for piping / agent use)
brainjar search "deployment"          # JSON output (default)
brainjar search -H "deployment"       # human-readable output

# Return full chunk content instead of previews
brainjar search --chunks "deployment workflow"

# Aggregate chunk scores to document level
brainjar search --doc-score "deployment workflow"

模糊搜索的工作原理

在...期间 brainjar sync，从所有索引文档内容重建词汇表：

1. 从每个文档中提取所有≥3个字符的标记
2. 复合标识符被拆分： knowledge_graph → knowledge, graph; KnowledgeGraph → knowledge, graph
3. 单词频率被计数并存储在SQLite中

在搜索时（默认模式）：

1. 每个查询词都与词汇表相匹配
2. 如果这个词确实存在→ 保持原样
3. 如果未找到→ Levenshtein距离的最接近匹配（短单词最多2个，长单词最多3个）
4. 通过FTS5+图运行更正的查询
5. 更正如下： ✎ corrected: deploymnt → deployment

智能搜索

对于会话或自然语言查询，请使用 --smart 让LLM在运行搜索之前提取2-5个目标搜索词：

brainjar search --smart "should we use flash lite for auto-recall entity extraction?"
# 🧠 Extracted 3 queries: "auto-recall", "flash lite", "entity extraction"
# Results from all queries, deduplicated and ranked by score

智能搜索在所有提取的查询中展开，按块ID对结果进行重复数据消除，并返回一个排名列表。需要 [extraction] config（使用与GraphRAG相同的LLM提供程序）。成本：使用Flash Lite每次搜索约0.000025美元。

实体提取（GraphRAG）

brainjar可以使用可配置的LLM从文档中提取实体和关系，构建一个可遍历的知识图，与SQLite中的文档一起存储。

[extraction]
enabled = true
backend = "gemini"          # or "openai" or "ollama"
model = "gemini-3.1-flash-lite-preview"
api_key_env = "GOOGLE_API_KEY"

同步期间，对于每个更改的文档：

• 提取实体（人、概念、工具、项目）
• 识别实体之间的关系
• 图形存储在 _graph.db

图搜索遍历实体关系，以查找与查询相关的文档，即使精确的术语不匹配。

支持的后端

配置

brainjar在以下位置查找配置：

1. --config path/to/brainjar.toml （明确）
2. ./brainjar.toml （当前目录和父目录）
3. ~/.brainjar/brainjar.toml （默认主页）

# brainjar.toml

[providers]
gemini.api_key = "${GEMINI_API_KEY}"
openai.api_key = "${OPENAI_API_KEY}"
# ollama.base_url = "http://localhost:11434"

[knowledge_bases.personal]
watch_paths = ["~/Documents/notes", "~/Documents/journal"]
auto_sync = true

[knowledge_bases.work]
watch_paths = ["~/Code/my-project"]
auto_sync = true

# Optional: entity extraction via LLM
[extraction]
provider = "gemini"
model = "gemini-3.1-flash-lite-preview"
enabled = true

# Optional: vector embeddings (recommended: OpenAI for cost, Gemini for quality)
[embeddings]
provider = "openai"                                # 10x cheaper than Gemini
model = "text-embedding-3-small"                   # 62.3% MTEB, 1536 dims (or 1024 with Matryoshka)
# dimensions = 1024                               # Matryoshka reduction: 67% storage savings

更改模型或尺寸？ 跑 brainjar sync --reembed 以重新生成所有嵌入。 Brainjar还可以自动检测尺寸不匹配，并在需要时重新嵌入。

知识库选项

[knowledge_bases.myproject]
watch_paths = [
  "~/Code/myproject/docs",          # directory
  "~/Code/myproject/README.md",     # single file
  "~/Code/myproject/**/*.md",       # glob
]
auto_sync = true    # included in `brainjar sync` without --kb flag

观看模式

监控知识库的更改和自动同步：

brainjar watch                    # poll every 5 minutes (default)
brainjar watch --interval 60      # poll every 60 seconds
brainjar watch --kb my-notes      # watch specific KB only
brainjar watch --daemon           # run in background
brainjar watch --stop             # stop background watcher

在中配置默认间隔 brainjar.toml:

[watch]
interval = 300    # seconds

⚠️ 主动开发警告： 每个带有更改的同步周期都会触发嵌入API调用。对于正在积极开发的代码库，可以考虑更长的间隔或查看特定的KB来管理成本。

锁定文件可防止并发同步。如果 brainjar sync 在监视器处于活动状态时手动运行，一个将等待另一个完成。

MCP服务器

将brainjar作为MCP服务器运行，以便与Claude Code、Cursor或任何MCP客户端一起使用：

brainjar mcp

克劳德代码/ .mcp.json

{
  "mcpServers": {
    "brainjar": {
      "command": "brainjar",
      "args": ["mcp"]
    }
  }
}

光标/ ~/.cursor/mcp.json

{
  "mcpServers": {
    "brainjar": {
      "command": "brainjar",
      "args": ["mcp"],
      "cwd": "/path/to/your/workspace"
    }
  }
}

可用的MCP工具： search_memory, sync_memory, get_status

成本

brainjar的设计成本最低：

所有搜索都在本地运行—在查询时API调用为零。

.布莱纳里诺

地点a .brainjarignore 配置目录中的文件，以从索引中排除文件。使用gitignore风格的球体图案：

# .brainjarignore
*.log
*.tmp
secrets/
node_modules/
**/generated/**

文件也按扩展名过滤。默认情况下，只有这些类型被索引： md txt rs toml yaml yml json py js ts tsx jsx sh css html xml csv sql tf hcl conf ini cfg env

默认排除目录： .git .venv node_modules __pycache__ target .brainjar dist build .next .nuxt .idea .vscode

建筑

brainjar.toml
     │
     ▼
brainjar sync
     │
     ├─ Parse & hash files
     ├─ Upsert into documents table (SQLite WAL)
     ├─ FTS5 virtual table auto-updated via triggers
     ├─ Build vocabulary table (Levenshtein fuzzy)
     └─ Extract entities → knowledge graph (optional LLM)

brainjar search "query"
     │
     ├─ FTS5 BM25 search → ranked results
     ├─ Graph traversal from matching entities
     └─ RRF merge → top-N results

brainjar search "qurey"
     │
     ├─ Correct query via vocabulary (Levenshtein)  ← new
     ├─ FTS5 with corrected terms
     ├─ Graph with original + corrected terms
     └─ RRF merge + show corrections

数据库布局

所有数据都存在于 ~/.brainjar/.db:

图形数据存在 ~/.brainjar/_graph.db （石墨烯）。

命令

brainjar sync [kb_name] [--force] [--dry-run] [-H]
brainjar search  [--kb ] [--limit N] [--text] [--graph] [--vector] [--local] [--smart] [--chunks] [--doc-score] [-H]
brainjar status [kb_name] [-H]
brainjar init
brainjar mcp

检索

# Fetch full content of a chunk by ID
brainjar retrieve 

# Chunk content + surrounding raw lines from source file
brainjar retrieve  --lines-before 10 --lines-after 20

# Chunk content + neighboring chunks
brainjar retrieve  --chunks-before 1 --chunks-after 1

为什么是brainjar？

为什么不仅仅是矢量？

向量搜索在语义相似性方面非常有用，但在代理记忆方面存在真正的缺点：

• 需要嵌入模型（API成本或本地GPU）
• 大规模构建和查询速度慢
• 无法可靠地进行精确或接近精确的匹配
• 黑盒——很难调试为什么结果排名在哪里

brainjar的FTS5+图+模糊方法为您提供：

• 精确的精度 当你知道这个词的时候
• 语义广度 通过实体图遍历
• 伤寒耐受性 通过词汇校正
• 零查询时间成本 --所有运行在SQLite中

为什么本地优先？

• 你的记忆不会离开你的机器（或你控制的红外线）
• 无API延迟-搜索时间为33ms，而不是500ms
• 离线工作
• 你拥有数据——一个 .db 文件，永久便携
• 云知识库服务的账单不足为奇

发展

git clone https://github.com/Farad-Labs/brainjar
cd brainjar
cargo build
cargo test                              # unit + integration tests
cargo test --features golden-corpus     # includes golden corpus (needs API keys)
cargo clippy
cargo install --path .

金语料库QA

PR至 main 使用以下命令运行完整的黄金语料库测试套件 Gemini和OpenAI 供应商。结果作为GitHub Actions工件上传(golden-corpus-summary.md).

• 双子座： gemini-embedding-2-preview （3072变暗）
• OpenAI： text-embedding-3-large （1024昏暗）
• 通过阈值： 两个供应商的16/16测试

路线图

• \[x\] brainjar retrieve --使用行/块上下文获取完整块内容
• \[x\] 分块——将文档分割成重叠的块，以便更好地回忆
• \[x\] --chunks 搜索标记--返回完整块内容而不是预览
• \[x\] --doc-score 搜索标记——将块分数聚合到文档级别
• \[x\] 观看模式： brainjar watch （基于轮询的文件监视器）
• \[x\] 智能搜索——将会话查询分解为目标搜索词
• \[x\] OpenAI嵌入支持（文本嵌入-3小/大）
• \[x\] 可组合搜索模式（--text、--graph、--vector、--local、--smart）
• \[\]MCP工具： correct_query （将模糊校正暴露给代理）
• \[\]用于浏览知识图的Web UI