Gbrain Multi-Agent Search

Search and manage a local gbrain personal knowledge base (full-text search, semantic search, knowledge graph). Use when searching personal notes, emails, doc...

Security Scan

The skill's instructions require an OpenAI-compatible embedding API and local gbrain repos, but the registry metadata does not declare those credentials/paths and the shipped wrapper hardcodes ~/gbrain — these inconsistencies warrant caution.

Purpose & Capability

The declared purpose (search/manage a local gbrain knowledge base) matches the runtime instructions: the skill runs the gbrain CLI to search, query, graph, sync, and embed content. Asking for an embedding API key and local repo paths is coherent with that purpose. However, the skill metadata declares no required env vars or config paths while the SKILL.md clearly instructs the user to set GBRAIN_DIR, BRAIN_DIR, OPENAI_API_KEY, and OPENAI_BASE_URL — this metadata/instruction mismatch is noteworthy.

Instruction Scope

The SKILL.md tells the agent to cd into a local gbrain repo and run 'bun run src/cli.ts' for many operations, and to call embedding endpoints using OPENAI_API_KEY/OPENAI_BASE_URL. The instructions will cause local files (your brain markdown) to be read and potentially uploaded to the embedding API when running embed. There is no instruction-level request to read unrelated system files, but the ability to execute the gbrain CLI means arbitrary code from that repo will run in your environment — the SKILL.md does not instruct the agent to validate the CLI code first. Also the provided wrapper script ignores the GBRAIN_DIR env var and hardcodes ~/gbrain, which conflicts with the documented configuration.

Install Mechanism

No install spec is included; this is instruction-only with a small helper script. Nothing will be downloaded or written by the skill itself — the highest-risk installation patterns are not present.

Credentials

The runtime requires an embedding API key and base URL (OPENAI_API_KEY, OPENAI_BASE_URL) to generate embeddings for local content, which is reasonable for this use case. However, the skill's registry metadata declares no required env vars or primary credential, which is inconsistent and can mislead users about secret requirements. The skill does not request unrelated credentials, but users must be aware that running 'embed' will transmit local content to the configured embedding service.

Persistence & Privilege

always is false and the skill does not request system-wide configuration or modify other skills. There is no elevated persistence requested.

What to consider before installing

This skill will run the gbrain CLI in your local repo and (if you run embedding commands) send your notes to an external embedding API using OPENAI_API_KEY/OPENAI_BASE_URL. Before installing or using it: 1) Verify and vet the gbrain repo code (bun run src/cli.ts executes code from that repo). 2) Note the registry metadata omits the env vars the SKILL.md requires — treat OPENAI_API_KEY and OPENAI_BASE_URL as necessary secrets and configure them intentionally. 3) The provided wrapper script hardcodes ~/gbrain (it ignores GBRAIN_DIR); update it if your repo is elsewhere. 4) If you do not want private notes uploaded to an external embedding service, do not run the embed commands or configure a local/private embedding endpoint. Additional information that would raise confidence to high: the skill metadata explicitly declaring required env vars/primary credential and the wrapper script using GBRAIN_DIR rather than a hardcoded path, or a trusted upstream repository URL for gbrain.

Local knowledge base with full-text search, semantic search, and knowledge graph. Requires gbrain installed and a brain repo initialized.

Prerequisites

• gbrain CLI installed (bun install in gbrain repo)
• A brain repo with synced markdown content
• Embedding API configured (OpenAI-compatible endpoint)

Configuration / 配置

Set these variables or replace inline:

Variable	Description	示例
GBRAIN_DIR	Path to gbrain source repo	~/gbrain
BRAIN_DIR	Path to brain content repo	~/brain
OPENAI_API_KEY	Embedding API key	sk-...
OPENAI_BASE_URL	Embedding API base URL	https://api.openai.com/v1

One-liner setup (add to TOOLS.md)

export GBRAIN_DIR=~/gbrain
export BRAIN_DIR=~/brain
export OPENAI_API_KEY=your-key-here
export OPENAI_BASE_URL=https://api.openai.com/v1
alias gb="cd $GBRAIN_DIR && bun run src/cli.ts"

Search / 搜索

Keyword search (fast, exact match) / 关键词搜索

cd $GBRAIN_DIR && bun run src/cli.ts search "<query>" [--limit N]

Best for: exact names, terms, file references. 适合：精确的人名、术语、文件名搜索。

Semantic search (hybrid, understands meaning) / 语义搜索

cd $GBRAIN_DIR && bun run src/cli.ts query "<question>" [--limit N]

Best for: natural language questions, fuzzy concepts, cross-topic queries. 适合：自然语言提问、模糊概念、跨主题查询。

Examples / 示例:

query "When did I join company X"        / "什么时候加入的公司X"
query "Heart rate trends in 2024"         / "2024年心率趋势"
query "Email about project approval"      / "项目审批相关的邮件"

List pages / 列出页面

cd $GBRAIN_DIR && bun run src/cli.ts list [--type source|person|concept|company|project|deal|media|civic] [--tag T] [-n N]

Read a page / 读取页面

cd $GBRAIN_DIR && bun run src/cli.ts get "<slug>" [--fuzzy]

Use --fuzzy for approximate slug matching. 使用 --fuzzy 进行模糊匹配。

Knowledge Graph / 知识图谱

Create link / 创建关联

cd $GBRAIN_DIR && bun run src/cli.ts link "<from>" "<to>" [--link-type TYPE] [--context "description"]

Traverse graph / 遍历图谱

cd $GBRAIN_DIR && bun run src/cli.ts graph "<slug>" [--depth N]

Common link types / 常用关联类型

works_at, invested_in, related_to, wrote, attended, located_in, managed, friend_of, reported_to, parent_of, spouse_of

Data Management / 数据管理

Import & embed / 导入与嵌入

# Sync markdown files from repo to brain
cd $GBRAIN_DIR && bun run src/cli.ts sync --repo $BRAIN_DIR --no-pull --no-embed --full

# Generate embeddings for new/changed content
cd $GBRAIN_DIR && OPENAI_API_KEY=... OPENAI_BASE_URL=... bun run src/cli.ts embed --stale

Statistics / 统计信息

cd $GBRAIN_DIR && bun run src/cli.ts stats

Health check / 健康检查

cd $GBRAIN_DIR && bun run src/cli.ts doctor

Workflow / 工作流程

Adding new content / 添加新内容

1. Add markdown files to $BRAIN_DIR/sources/<category>/
2. git add && git commit
3. Run sync --full --no-pull --no-embed
4. Run embed --stale

Typical search pattern / 典型搜索模式

1. Start with search for exact matches
2. If no results or need deeper understanding, use query
3. Use get <slug> to read full page content
4. Use graph <slug> to explore related pages

Tips / 提示

• search is faster, query is smarter — use search first / search 更快，query 更智能
• Add --limit 5 for concise results / 加 --limit 5 获取简洁结果
• Use --fuzzy when unsure of exact slug / 不确定 slug 时用 --fuzzy
• For embedding issues with large files (>64 chunks), split into smaller files / 大文件嵌入失败时，拆分为小文件
• Run stats periodically to check brain health / 定期运行 stats 检查知识库状态