Struct Brain 

pub struct Brain { /* private fields */ }

A project-scoped rustbrain instance rooted at workspace/.brain.

Lifecycle

Brain::create / open / open_or_create
        │
        ▼
     sync()  ──► index Markdown + AST + resolve links + bake graph.mmap
        │
        ├─► query / query_ranked
        ├─► context_for_prompt / context_for_prompt_with
        ├─► export / import
        └─► watch  (feature = "watch")

Threading

Brain is not Sync. Open separate instances (or serialize access) for concurrent use. SQLite is opened with WAL and a busy timeout for multi-process friendliness on the same machine.

Implementations

impl Brain

pub fn create(workspace: impl AsRef<Path>) -> Result<Self>

Create a new brain directory and empty database under workspace/.brain.

Creates the workspace directory if it does not exist. Writes a minimal workspace.json marker. Does not index notes — call Self::sync.

Errors

Returns I/O or SQLite errors if the directory or database cannot be created.

pub fn open(workspace: impl AsRef<Path>) -> Result<Self>

Open an existing brain under workspace/.brain.

Errors

Returns BrainError::BrainNotFound if db.sqlite is missing.

pub fn open_or_create(workspace: impl AsRef<Path>) -> Result<Self>

Open an existing brain, or Self::create if none is present.

pub fn workspace(&self) -> &Path

Absolute path to the workspace root (parent of .brain).

pub fn brain_dir(&self) -> &Path

Absolute path to the .brain directory.

pub fn database(&self) -> &Database

Borrow the underlying Database for advanced queries or tooling.

pub fn sync(&mut self) -> Result<SyncStats>

Index Markdown (and optional AST / Canvas) and recompile the CSR mmap cache.

Unchanged files (matching content_hash) are skipped. WikiLinks and symbol:… refs that cannot be resolved are stored as pending links and retried at the end of the run (and on later syncs).

pub fn query(&self, q: &str) -> Result<Vec<Node>>

Ranked search returning only nodes (score order preserved, scores discarded).

Prefer Self::query_ranked when scores or match reasons matter.

pub fn query_ranked( &self, q: &str, opts: &QueryOptions, ) -> Result<Vec<RankedHit>>

Ranked search with scores and human-readable match reasons.

Combines FTS5 BM25 with title, id, tag, and alias boosts. See QueryOptions.

pub fn context_for_prompt( &self, prompt: &str, max_tokens: usize, ) -> Result<ContextBundle>

Build a graph-aware prompt context with a simple token budget.

Equivalent to Self::context_for_prompt_with using default hop depth and packing limits. Token accounting uses a ~4 characters/token heuristic.

pub fn context_for_prompt_with( &self, prompt: &str, opts: &ContextOptions, ) -> Result<ContextBundle>

Context assembly with full control over hops, seed counts, and packing.

When graph.mmap exists and opts.hop_depth > 0, CSR neighbors of seed hits are scored and packed alongside FTS seeds.

pub fn export(&self, out: impl AsRef<Path>, decouple_ast: bool) -> Result<()>

Export nodes/edges to a portable .brainbundle JSON file.

When decouple_ast is true, symbol nodes and file/symbol path fields are stripped so the bundle can move across repositories cleanly.

pub fn import(&mut self, input: impl AsRef<Path>) -> Result<usize>

Import a .brainbundle, upserting nodes and edges.

Recompiles graph.mmap when the mmap feature is enabled.

Returns

Number of nodes upserted from the bundle.

pub fn watch(&self, debounce_ms: u64) -> Result<()>

Block the current thread and watch the workspace for changes.

Requires the watch Cargo feature. Debounces filesystem events for debounce_ms milliseconds, then runs a full sync (content-hash skips unchanged files) and remaps the CSR cache.

pub fn bootstrap( workspace: impl AsRef<Path>, opts: BootstrapOptions, ) -> Result<BootstrapReport>

Deterministic docs/ignore bootstrap for mature repositories.

See crate::bootstrap::bootstrap_workspace. Does not replace a full Self::sync — call sync afterward to index new files.

pub fn doctor(&self) -> Result<DoctorReport>

Health check for this brain (pending links, ratios, schema).

pub fn note_new(&self, opts: &NoteNewOptions) -> Result<NoteCreated>

Create a Markdown note on disk (docs/…) without opening a second DB.

Call Self::sync afterward so FTS/graph pick it up.