your glass-box company brain

Search hands you raw pages. Vitrus hands you the answer + its sources + what it doesn't know — all in portable Markdown files you own.

Live demo · Quickstart · Docs · Architecture · Cloud · Roadmap

---

✨ What you can do

One brain — read by humans and agents. It cites every claim, and admits what it doesn't know.

• 🧠 Ask your company in plain language → a sourced answer plus an honest list of what isn't documented (see it).
• 🔌 Make any API agent-native. Import an OpenAPI spec, retrieve the right endpoint for a task, and verify the call before it runs — no hallucinated endpoints or arguments. vitrus api import|search|verify|call.
• 🎓 Onboard a new hire (or agent) on day one. A sourced, pedagogically-ordered learning path with who to ask and what's still undocumented, plus quizzes graded against the brain. vitrus onboard|quiz.
• 🔎 Trust the ranking. --explain prints every score factor; graph-signal ranking promotes results that are connected to, or corroborated across, other sources.
• ⚡ Capture without friction. One-command notes, ingest from any REST endpoint, or drop files in a watched inbox folder. vitrus capture · vitrus ingest rest|inbox.
• 📥 Bring the notes you already have. Import an Obsidian vault, a Notion export, or your ChatGPT/Claude history — or migrate from GBrain — straight into the same glass-box brain. vitrus import-obsidian|notion|chat|gbrain.
• 🤖 30 MCP tools so Claude, Cursor and your own agents share the exact same trusted, permission-aware memory.

New since the last release — see What's new below.

---

What this looks like

$ vitrus think "how was the payment outage resolved"

The payment service returned 503s due to a gateway rate-limit breach.
Resolved by raising the limit from 500 to 1000 rps [1], per the
rate-limit decision [2].

Sources:
  [1] durable/runbooks/rate-limit
  [2] durable/decisions/d-007

⚠ What your brain doesn't know (1):
  · "durable/companies/acme" is referenced but undocumented (missing)

Confidence: 82% · oldest source: 12 days

That gap box is the point of the project. Every answer ships with its sources and an honest, deterministic list of what your knowledge base hasn't documented. There is no LLM in the gap detector, so it can't hallucinate a gap into existence — or out of it. A claim with no source is shown as a gap, never papered over.

What's new (2026-07)

• Answers — and alerts — in Slack. A /vitrus <question> command replies with the glass-box answer right in a channel, and a proactive digest posts what needs attention (the vitrus watch radar — stale knowledge, unresolved incidents, aging gaps) on a schedule, before you ask. Fail-closed so private channels never leak; deterministic, no LLM. (Vitrus Cloud — see below.)
• Bring your existing notes. vitrus import-obsidian (vault + [[wikilinks]] → typed edges), vitrus import-notion (Notion markdown export), vitrus import-chat (ChatGPT/Claude conversations.json), vitrus import-gbrain (migrate from GBrain) — all map into the same glass-box brain.
• 8 one-token connectors. Stripe · HubSpot · Salesforce · Asana · Microsoft Teams · Dropbox · Figma · Zoom — preset REST connectors: pick one, paste a token, it syncs. No bespoke code (built on the generic REST engine).
• Self-maintaining dream loop. Nightly vitrus dream now also runs citation-fix (suggest a sourced match for every uncited node) and a contradiction digest (open contradictions + which side is newer); vitrus brief prints a deterministic morning briefing (attention + gaps + conflicts + fixable-uncited).
• Schema packs. vitrus schema lint checks your taxonomy deterministically (unknown node/edge types, edge from→to violations against the vitrus-base pack); vitrus schema explain <type> documents any type and the edges it participates in. (MCP schema_lint / schema_explain_type.)
• Agent-native API hub. Import an OpenAPI spec (vitrus api import <spec>), retrieve the right endpoint for a task (vitrus api search), and verify a call deterministically before running it (vitrus api verify → valid / missing_args / wrong_type / unknown_args / unknown_endpoint / deprecated) — the anti-hallucination gate. vitrus api call verifies, then executes. Also vitrus ingest rest --config <c.json> to pull any REST response into the brain. Visual API-integration drawer in the dashboard.
• Day-one onboarding. vitrus onboard "<role>" builds a sourced, pedagogically-ordered learning path from the brain (who to ask + what's not documented yet); vitrus quiz "<topic>" generates recall questions graded deterministically by verify.
• --explain ranking attribution. vitrus search "<q>" --explain prints each hit's score factors: vector/bm25/entity ranks + tier/cosine and the new graph-adjacency / cross-source boosts.
• Graph-signal ranking. A deterministic, ACL-safe re-scoring after hybrid search: results connected to other top hits, or corroborated across sources, rise.
• Native Voyage + ZeroEntropy embedders (Matryoshka-fit to the frozen vector(1536) schema — no migration).
• MCP surface 13 → 30 tools (entities, graph_query, get_node, chunks, attention, conflicts, api_search/api_verify/api_call, onboarding_path, quiz, schema_lint/schema_explain_type, briefing, …; content tools are ACL fail-closed).
• One-command capture. vitrus capture "<note>" (arg/file/stdin) + a watched inbox folder (vitrus ingest inbox <dir>) for mobile capture.
• 12 prebuilt skills. vitrus skills list|install — a validated SKILL.md library that teaches agents how to use Vitrus.

Three design rules hold everywhere:

• Glass-box. Every answer is known / unknown (gap) / sourced.
• Ownable. The source of truth is Markdown + a typed-edge sidecar in git. The index is disposable and rebuildable; delete it and your knowledge loses nothing.
• Agent-native. The same brain serves humans (CLI, dashboard) and agents (MCP, Agent Skills) from one permission-aware memory.

Install

Pick your entry point:

# 1) Zero-setup local brain (PGLite, no database server)
bunx @vitrus/core init --pglite     # creates ./.vitrus
vitrus import ./brain               # ingest markdown (embeds + self-linking graph)
vitrus think "how was the outage resolved"

# 2) Wire it into Claude Code / Cursor / OpenClaw / Hermes as MCP — two commands
git clone https://github.com/ahmetvural79/Vitrus && cd Vitrus/packages/core && bun install && bun link
claude mcp add vitrus -- bunx @vitrus/mcp

# 3) Team scale: same engine on Postgres + pgvector
bun add pg
VITRUS_PG_URL=postgres://user@host/db vitrus import ./brain

vitrus doctor prints backend, providers and health (it never leaks secrets).

Two ways to query your brain

vitrus search "rate limit"     # hybrid retrieval: vector + BM25 + entity → RRF-fused hits
vitrus think  "what is the payment rate limit and why"   # synthesized answer + sources + gap box + confidence

search gives you ranked nodes; think gives you the answer with provenance. Both respect ACLs and both are honest about what isn't there.

And two that most tools don't have:

vitrus watch    # proactive: stale knowledge, unresolved incidents, aging gaps — what needs attention
vitrus verify "the rate limit for payments is 500 rps"
# → STALE — supported by decisions/d-007, but superseded during the outage (now 1000 rps)

verify returns one of four deterministic verdicts — grounded · stale · contradicted · unsupported — with supporting sources and conflicts. No LLM judge; it's hybrid search + gap analysis over your own record. Also available programmatically (@vitrus/core/verify) and as an MCP tool, so agents can fact-check themselves before acting.

How to get data in

Markdown is canonical — anything that becomes Markdown becomes knowledge:

vitrus import ./brain                   # a folder of .md files (+ optional .edges.json sidecars)
vitrus import-obsidian ./vault          # an Obsidian vault ([[wikilinks]] → typed edges)
vitrus import-notion ./export           # a Notion markdown export
vitrus import-chat conversations.json   # a ChatGPT or Claude export
vitrus import-gbrain ./gbrain           # migrate from GBrain

The connector framework is in the core (Apache-2.0): one interface (fetch() → records with content + ACL), idempotent ingest, incremental prune, and permission capture on every sync — remove someone from a channel and their access is revoked on the next sync, automatically.

Seven first-class live connectors over one injectable, mock-testable HTTP layer (5 pagination styles — REST-Link · GET-cursor · POST-cursor · GraphQL · offset · pageToken): GitHub · Slack · Notion · Linear · Jira · Drive · Gmail. Incremental sync (--since, prune-safe), webhook → live delta (GitHub direct; Slack triggers a re-sync), and a durable, crash-recovery sync queue with a cron scheduler. Plus offline adapters: Email (participants become the ACL) · Calendar · a generic Docs adapter · an MCP-source bridge (any MCP server becomes a source). And eight one-token presets on the generic REST engine — Stripe · HubSpot · Salesforce · Asana · Teams · Dropbox · Figma · Zoom — pick one, paste a token, it syncs (no bespoke code). Everything funnels into one brain, so the same alice mentioned in Slack and authoring a PR fuses into a single graph node.

GITHUB_TOKEN=… vitrus ingest github --live --repo owner/name              # pull (incremental with --since)
vitrus ingest slack --live --channel C0… --queue                          # enqueue a durable sync job

Capabilities

• Gap analysis — five deterministic kinds: missing (referenced but undocumented), contradiction (conflicting edges), stale (superseded), single-point (bus-factor risk), uncited (event with no source). Derived from graph structure and explicit text signals only.
• Proactive attention — vitrus watch makes gap analysis temporal: stale knowledge, unresolved incidents and aging gaps surfaced without being asked. Deterministic, no LLM. Nightly vitrus dream consolidates (dedup, salience, citation-fix for uncited nodes, contradiction digest) and vitrus brief prints a morning briefing — a standing, self-maintaining radar over your memory.
• Ops-map — vitrus ops (MCP ops_report) reads the company as a system and flags operational inefficiencies: unowned services, bus-factor (single-person) risk, bottlenecks (overloaded hubs), broken handoffs (depending on superseded ground), and redundant tools (embedding-similar services). Severity-ranked, each finding cites real nodes — evidence, not a consultant's guess.
• Conflict resolution — vitrus conflicts / vitrus resolve (MCP resolve_conflict) detects contradictions and shows both sides; resolve by choosing the winner — the loser is superseded (marked stale) and the conflict closes. Nothing overwritten in silence.
• Write-back loop — agents read before they act and write after they decide: MCP record_decision / capture_session + vitrus decide + vitrus hooks install (Claude/Cursor/Codex). Decisions persist with their sources, so the brain stays live; a decision that contradicts an existing one is flagged back to the agent.
• Self-linking graph — [[type::slug]] typed edges, extracted without an LLM; bi-temporal — vitrus dashboard --graph --asof <ISO> (and getConnections/graphSnapshot) answer "what did we believe in March?" (time-travel on the edge graph; correct from real created_at/expired_at).
• Schema packs — a loadable taxonomy (vitrus-base): vitrus schema lint flags nodes/edges that violate the type model (unknown types, illegal edge endpoints); vitrus schema explain <type> documents a type and the edges it can participate in. Keeps a large brain's taxonomy honest.
• Hybrid retrieval — vector + BM25 + entity match, RRF-fused; optional reranker.
• Provenance everywhere — every claim traces to node → chunk → source URI.
• ACL, fail-closed — enforced at the index layer; unauthorized content never appears in results.
• Confidence + freshness — every answer carries a confidence score and oldest-source age.
• Durable job queue — vitrus agent run "…" && vitrus agent work && vitrus jobs (crash-recovering).

Providers (BYO-LLM)

Offline-deterministic by default — no API key needed. Production providers are env-driven, one interface:

	Providers	Env
Embedder	OpenAI · Gemini · Cohere · offline hashing (default)	VITRUS_EMBED_PROVIDER
Synthesizer	OpenAI · Anthropic · Gemini · Ollama (local) · offline extractive	VITRUS_SYNTH_PROVIDER
Reranker	Cohere · Voyage · ZeroEntropy · lexical (default off)	VITRUS_RERANK_PROVIDER

With a production embedder the brain is multilingual: ask in one language, retrieve sources written in another.

Agents (MCP)

Serve the brain to any agent over the Model Context Protocol — stdio + Streamable HTTP, with OAuth 2.1 Resource Server support:

claude mcp add vitrus -- bunx @vitrus/mcp     # stdio, one line
vitrus-mcp --http 3000                        # or Streamable HTTP on :3000/mcp

Agents read before they act and write after they decide. Read tools: search · think · gap_report · ops_report · provenance · verify. Write tools: record_decision · capture_session · resolve_conflict (remember / forget / improve too). One command wires the loop into Claude Code / Cursor / Codex: vitrus hooks install. Markdown sources are exposed as vitrus://node/<slug> resources. Agents see only what the token's user is allowed to see — ACL is enforced at the index layer, fail-closed. The output of an import can also be an executable Agent Skill (SKILL.md) wired live to MCP.

Architecture

Four layers, each depending only on the one below:

source of truth   markdown (+ .edges.json sidecar) in git   ← you own this
      ↓
engine            PGLite / Postgres+pgvector · hybrid search (vector + BM25 + entity → RRF)
      ↓                                       · self-linking graph ([[type::slug]], LLM-free) · bi-temporal edges
trust surface     gap analysis · provenance · verify · confidence · attention
      ↓
presentation      CLI · MCP (stdio + HTTP) · SKILL.md export · web dashboard (cloud)

Two engines, one contract: PGLite (WASM, zero-setup) for personal brains, Postgres+pgvector for teams — same SQL, same engine, same answers. Invariants: Markdown is canonical (reset index → rebuild → answer unchanged). The graph is LLM-free. Gaps are deterministic. ACL is fail-closed.

Testing & gates

Runs on Bun (no build step). Four CI gates, all green:

bun run typecheck      # strict tsc
bun run test           # 200+ tests (node:test runner)
bun run eval           # source-hit ≥90% + gap recall/precision 100%
bun run leak-test      # unauthorized access = 0 (ACL fail-closed)

Troubleshooting

Symptom	Fix
vitrus: command not found	cd packages/core && bun link (or use bunx @vitrus/core)
Answers feel weak in non-English	Set a production embedder: VITRUS_EMBED_PROVIDER=openai + key (default hashing embedder is language-naive)
pg errors on import	Team scale needs bun add pg and a reachable VITRUS_PG_URL (PGLite needs neither)
MCP server not showing tools	Check claude mcp list; for HTTP, the endpoint is /mcp and auth is Authorization: Bearer <token>
"is my index stale?"	The index is disposable: vitrus reset && vitrus import ./brain rebuilds everything from Markdown
Anything else	vitrus doctor first — it reports backend, providers and health without leaking secrets

Docs

Guide	What's inside
Quickstart	From zero to a queried brain in 60 seconds.
Architecture	The layers, hybrid search, the self-linking graph, invariants.
CLI reference	Every vitrus command, grouped by what it does.
Providers	Offline-default; plug in OpenAI/Ollama embedders, synthesizers, rerankers.
Scaling	PGLite → Postgres+pgvector, migrations, the job queue, multi-tenant RLS.
MCP	Serve the brain to agents (stdio + HTTP); the tool set.
Examples	Six runnable recipes — graph, gaps, verify, MCP, Postgres.

Repository layout

packages/
  core/     @vitrus/core — engine, hybrid search, gap analysis, CLI, connectors (Apache-2.0)
    src/        the engine and CLI source (Bun runs TS directly, no build)
    brain/      a sample brain you can `vitrus import`
    migrations/ schema + row-level security
    test/       the test + eval + leak-test suites
  mcp/      @vitrus/mcp — the Model Context Protocol server (Apache-2.0)
docs/       the guides linked above
examples/   runnable recipes
assets/     logo + icon

This repo is the open core: everything above is Apache-2.0 licensed and self-hostable end-to-end, with no feature flags and no fake "community edition". Gap analysis is never gated.

Benchmarks

Gap detection has no public benchmark — so we built Gap-Eval (open corpus + harness, in this repo) and publish the numbers with their methodology:

vitrus bench gapeval --determinism    # or: bun run gapeval

metric	v0 result
Recall / precision (overall, 18 gold-labeled cases, 5 gap kinds)	100% / 100%
False positives on clean brains (negative control)	0
Determinism (same brain → byte-identical gaps, twice)	PASS

Honest framing: v0 is a controlled synthetic corpus (hand-authored brains with known gaps that exercise the engine's real mechanisms — dangling wikilinks, contradicts/supersedes edges, provenance-less events). It proves the detector does exactly what it documents, deterministically, with zero fabricated gaps; it does not claim real-world generalization. The corpus lives at packages/core/src/eval/gapeval/corpus — adding a harder case is a one-directory PR. Retrieval benchmarks (LongMemEval/LoCoMo format, BYO dataset) run via bun run bench.

Vitrus Cloud

There is also a hosted version at app.vitrus.dev — the same Apache-2.0 engine in this repo, deployed multi-tenant, for teams that don't want to run their own. What it adds is operations, not capability:

• Web dashboard — Ask, Gap Explorer, knowledge Graph, Entities, Verify, and trace-to-source on every answer.

• Managed connectors — a gallery of 13 sources with stored credentials, scheduled sync and per-sync permission capture. Live sync: Slack, GitHub, Notion, Linear, Google Drive, Jira, Confluence, GitLab, Discord, and an MCP bridge (any MCP server's resources become a source); plus real-time WhatsApp webhook ingest and staged Email/Calendar imports.

• Answers where you work (Slack) — a /vitrus <question> command returns the glass-box answer — sources + the yellow what-it-doesn't-know box — right in a channel, fail-closed so private channels never leak. And a proactive attention digest posts what's decaying (stale knowledge, unresolved incidents, aging gaps) into a channel on a schedule — the vitrus watch radar delivered where your team already is, no LLM guessing.

• A per-org MCP endpoint — https://api.vitrus.dev/t/<org>/mcp with bearer auth, so your agents read the same brain your team does. Claude Code, Codex, Cursor, OpenClaw, Hermes — any MCP client over Streamable HTTP (copy-paste setup per agent on the dashboard's Agent access page):

  claude mcp add --transport http vitrus \
    https://api.vitrus.dev/t/<org>/mcp \
    --header "Authorization: Bearer <token>"
  
  openclaw mcp add vitrus --url https://api.vitrus.dev/t/<org>/mcp \
    --transport streamable-http --header "Authorization: Bearer <token>"

• Team & ACL management — roles (admin/member/viewer), seat-based membership, and an audit log of who asked what.

• Account & support — self-serve workspace administration and a built-in support desk (available on every account, including free ones).

Signing up is free — the Free plan includes the full dashboard with 1 brain · 1 seat · 2 connectors · 5k nodes; Pro ($25/seat/mo or $249/seat/yr) adds seats and scale. Either way there is no lock-in by design: your knowledge stays portable Markdown, and leaving the cloud means vitrus import on your own machine.

Vitrus Enterprise

For regulated, on-prem and air-gapped deployments — governments, municipalities, factories — there is Vitrus Enterprise, which extends this open engine to relational databases (MySQL/Postgres) and ERP systems (SAP, Canias) without modifying it. The thesis is preserved on structured data: the LLM proposes, a deterministic guard decides — and it shows the gap instead of bluffing.

• Text-to-SQL with a deterministic anti-hallucination guard — NL question → candidate SELECT → an LLM-free guard (single-statement · read-only/SELECT-only · no unknown tables/columns · PII policy · mandatory limit) → read-only execution → answer + provenance. Can't answer safely → an honest gap, not a confident wrong number.
• Verified-query memory — confirmed question → SQL pairs become deterministic, auditable few-shot memory, so accuracy compounds over time (only guard-passed queries are remembered).
• Governed MCP for agents — an MCP server exposes the SQL brain (sql_ask, sql_run, list_tables, verify_claim, teach_query) with the guard, row-level security, column masking, and audit enforced inside every tool, so Claude / Cursor / Codex / OpenClaw agents query governed data without bypassing it. stdio + HTTP.
• Structured glass-box — deterministic data-quality gaps (orphan FKs, stale rows, missing PKs), claim verification with evidence, full provenance, and a KVKK/GDPR audit trail with PII masking.
• Fully local & air-gapped — local LLM (Ollama/Gemma) + local embedder (BGE-M3/Qwen3); data never leaves the building. One-command docker compose, or an air-gapped USB bundle.
• Modern white-label console — a single-tenant dark dashboard over your existing databases, connected read-only by construction (SELECT-only user · read-only transaction · statement timeout · AST guard), with deterministic client-side charts (zero code execution) and suggested starter / follow-up questions.
• ERP & connectors — MSSQL / Oracle / SAP HANA drivers for SAP (S/4HANA via HANA SQL & CDS; ECC via a read-only replica) and Canias, plus token-REST connectors (GitHub, GitLab, Jira, Notion, Zendesk, Stripe, Salesforce…).

The core in this repository stays open; Enterprise is the commercial layer built on top. Details → vitrus-enterprise-info.

Contributing

Issues and PRs welcome — the roadmap is real deferred work, openly tracked. See CONTRIBUTING.md and the security policy. The fastest way to help: try the quickstart, and file an issue for anything that didn't take 60 seconds.

License + credit

@vitrus/core and @vitrus/mcp are Apache-2.0 (see LICENSE). The cloud apps (dashboard, multi-tenant API) live in a separate non-public repo.

Vitrus draws on ideas explored by GBrain — Markdown-canonical memory and an LLM-free typed graph — implemented independently here with its own engine and a different emphasis: the gap box. If GBrain's shape fits you better, use it; honest memory winning in any form is the point.

vitrus.dev · live demo · cloud dashboard

Built for teams that want to trust their answers.