Skip to content

FAQ

Jump to bottom
Sven Andreas edited this page Apr 9, 2026 · 1 revision

FAQ

General

What is the .brain file?

A single binary file containing your entire knowledge base. It includes nodes, edges, properties, indexes, and metadata. Copy it to back up, move it to migrate, delete it to start fresh. No external database needed.

What are sidecar files?

Files stored alongside the .brain file: .brain.props (properties), .brain.types (type registry), .brain.vectors (embeddings), .brain.cooccur (co-occurrence), .brain.wal (write-ahead log), .brain.config (configuration), .brain.sources (data sources), .brain.docs.N + .brain.docs.idx (document store), .brain.assessments, .brain.secrets, .brain.rules.

Do I need an LLM?

For basic graph operations (store, relate, query, search), no. For advanced features (debate, chat, gap-closing, fact extraction, seed enrichment), yes. Any OpenAI-compatible endpoint works. We recommend Gemma 4 via Ollama.

Do I need an embedding model?

For BM25 full-text search, no. For semantic similarity search (/similar, /ask), yes. Configure via API or onboarding wizard.

Setup

How do I set up authentication?

On first run, call POST /auth/setup with username and password. Then POST /auth/login to get a bearer token. See Configuration.

SearXNG returns 403 Forbidden

SearXNG blocks JSON API access by default. Add json to the search.formats list in settings.yml. See Configuration.

Ollama model is slow

Check your model's context window with ollama show <model>. Larger context = more VRAM = slower on small GPUs. Try a smaller model (14B instead of 27B) or reduce the context window.

How do I configure engram without the web UI?

Use API calls. See Configuration > API-Based Setup.

Performance

localhost is slow on Windows

Use 127.0.0.1 instead of localhost. Windows may resolve localhost to IPv6 first, causing ~210ms delay.

How fast is engram?

Core operations (store, query, search) complete in ~1-2ms in release builds. Debate rounds and ingest depend on your LLM speed.

GPU

What GPU features are available?

  • wgpu (all platforms): GPU compute for similarity search. Auto-detected at runtime.
  • DirectML (Windows): GPU acceleration for GLiNER2 NER/RE via ONNX Runtime.
  • CUDA (Linux): GPU acceleration for GLiNER2 NER/RE via ONNX Runtime.
  • CoreML (macOS): GPU acceleration for GLiNER2 NER/RE via ONNX Runtime.

Release binaries include platform-appropriate GPU support. CPU fallback is automatic.

How do I build from source with GPU?

# Windows
cargo build --release --features all,directml

# Linux
cargo build --release --features all,cuda

# macOS
cargo build --release --features all,coreml

Data

How do I back up my data?

Copy the .brain file and all sidecar files (.brain.*).

Can multiple instances share a .brain file?

Not directly. Use the knowledge mesh for peer-to-peer sync between instances.

How do I reset?

Delete the .brain file and all sidecars. Or call POST /admin/reset (destructive).

Clone this wiki locally