Crate rustbrain_core 

rustbrain-core

Project-scoped knowledge graph engine for software repositories: Markdown notes, optional Rust AST symbols, ranked full-text search, and graph-aware AI agent context.

This is the primary library crate for embedding rustbrain in tools, agents, and CLIs. Humans edit plain Markdown (Obsidian-compatible WikiLinks and YAML frontmatter); rustbrain-core derives a SQLite graph + FTS index and an optional CSR graph.mmap cache.

Quick start

use rustbrain_core::{Brain, ContextOptions, QueryOptions, Result};

fn main() -> Result<()> {
    // Creates `<cwd>/.brain/db.sqlite` if missing
    let mut brain = Brain::open_or_create(".")?;

    // Walk Markdown / Rust / Canvas, update FTS, resolve links, bake graph.mmap
    let stats = brain.sync()?;
    let _ = stats.markdown_files;

    // Ranked search: BM25 + tag/alias/title boosts
    let hits = brain.query_ranked("raft consensus", &QueryOptions::default())?;
    for hit in hits.iter().take(3) {
        println!("{:.2} {}", hit.score, hit.node.title);
    }

    // Agent context: seeds + CSR neighbors, packed under a token budget
    let ctx = brain.context_for_prompt_with(
        "explain log compaction",
        &ContextOptions {
            max_tokens: 1024,
            hop_depth: 1,
            ..ContextOptions::default()
        },
    )?;
    print!("{}", ctx.to_xml());
    Ok(())
}

Crates.io layout

Only two packages are published:

Package	Role
rustbrain-core (this crate)	Library for apps and agents
rustbrain	CLI binary (cargo install rustbrain)

AST and Obsidian parsing live inside this crate behind feature flags (ast, obsidian) — not as separate published crates.

On-disk layout

Under <workspace>/.brain/:

Path	Role
db.sqlite	Source of truth (nodes, edges, FTS5, aliases, symbols)
graph.mmap	CSR adjacency + node-id table for fast neighborhood walks
workspace.json	Workspace marker

Feature flags

Feature	Default	Purpose
ast	yes	Tree-sitter Rust symbol extraction
obsidian	yes	WikiLinks, frontmatter, Canvas
mmap	yes	Compile and read .brain/graph.mmap
watch	no	Debounced filesystem watcher
jshift	no	In-place JSON field mutation helpers
full	no	Enables every optional feature

Error handling

Fallible APIs return Result<T> aliasing BrainError. Match on variants at library boundaries; the CLI may wrap errors in anyhow.

Non-goals (v0.1)

• Neural embeddings / ANN indexes (product path uses vector_dim = 0)
• Multi-user servers or cloud sync
• Full Obsidian vault write-back (ingest only)

Re-exports

pub use brain::Brain;

pub use context::ContextOptions;

pub use error::BrainError;

pub use error::Result;

pub use exporter::BrainExporter;

pub use exporter::BrainImporter;

pub use exporter::PortableBrainBundle;

pub use exporter::BUNDLE_VERSION;

pub use indexer::WorkspaceIndexer;

pub use mmap::CsrCompiler;

pub use mmap::CsrMmapGraph;

pub use mmap::MMAP_VERSION;

pub use query::QueryOptions;

pub use query::RankedHit;

pub use registry::GlobalRankedHit;

pub use registry::GlobalRegistry;

pub use storage::Database;

pub use storage::SCHEMA_VERSION;

pub use symbols::extract_symbol_refs;

pub use symbols::symbol_node_id;

pub use symbols::SymbolRef;

pub use types::xml_escape;

pub use types::ContextBundle;

pub use types::ContextNode;

pub use types::ContextRole;

pub use types::Edge;

pub use types::Node;

pub use types::NodeType;

pub use types::SyncStats;

pub use watch::WatchConfig;

pub use ast::compute_symbol_hash;

pub use ast::AstError;

pub use ast::CodeAstParser;

pub use ast::SymbolAnchor;

pub use obsidian::extract_wikilinks;

pub use obsidian::parse_frontmatter;

pub use obsidian::CanvasEdge;

pub use obsidian::CanvasNode;

pub use obsidian::Frontmatter;

pub use obsidian::ObsidianCanvas;

pub use obsidian::WikiLink;

pub use mutator::extract_json_field_slice;

pub use mutator::update_json_field_inplace;

pub use watch::watch_workspace;

Modules

ast

Tree-sitter Rust symbol extraction and BLAKE3 hashing.

brain

Primary library façade: Brain.

context

Graph-aware AI context assembly with token budgeting.

error

Typed errors for the rustbrain library boundary.

exporter

Portable .brainbundle export and import (schema v1).

fts

FTS5 query helpers: escaping and safe MATCH construction.

id

Stable node ID scheme based on repository-relative path slugs.

indexer

Workspace walker: Markdown notes, optional Canvas, optional Rust AST.

mmap

CSR graph mmap cache (format v1).

mutator

Optional jshift-backed in-place JSON field mutation helpers.

obsidian

Obsidian-compatible WikiLink, frontmatter, and Canvas parsing.

query

Ranked hybrid query: FTS5 BM25 + tag / alias / title boosts.

registry

Global developer registry of rustbrain workspaces (XDG-aware).

storage

SQLite master store for rustbrain.

symbols

Symbol reference parsing and stable symbol node IDs.

types

Domain types for the rustbrain knowledge graph.

watch

Debounced filesystem watcher for live re-indexing.