# Show HN: Vitrus – the company brain that tells you what it doesn't know > Source: > Published: 2026-06-20 23:22:42+00:00 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](https://vitrus.dev#demo) · [Quickstart](#install) · [Docs](#docs) · [Architecture](#architecture) · [Cloud](#vitrus-cloud) · [Roadmap](https://github.com/ahmetvural79/Vitrus/issues) One brain — read by humansandagents. 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](#what-this-looks-like)). - 🔌 **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` . - 🤖 **27 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.* ``` bash $ 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. **Agent-native API hub.** Import an OpenAPI spec (`vitrus api import ` ), 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 ` to pull any REST response into the brain. Visual API-integration drawer in the dashboard.**Day-one onboarding.**`vitrus onboard ""` builds a sourced, pedagogically-ordered learning path from the brain (who to ask + what's not documented yet);`vitrus quiz ""` generates recall questions graded deterministically by`verify` .`--explain` ranking attribution.`vitrus search "" --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 → 27 tools**(`entities` ,`graph_query` ,`get_node` ,`chunks` ,`attention` ,`conflicts` ,`api_search` /`api_verify` /`api_call` ,`onboarding_path` ,`quiz` , …; content tools are ACL fail-closed).**One-command capture.**`vitrus capture ""` (arg/file/stdin) + a watched inbox folder (`vitrus ingest inbox ` ) 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. 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). ``` 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. Markdown is canonical — anything that becomes Markdown becomes knowledge: ``` vitrus import ./brain # a folder of .md files (+ optional .edges.json sidecars) ``` 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). 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 ``` **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; schedule it (with nightly`vitrus dream` consolidation) for a standing 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 ` (and`getConnections` /`graphSnapshot` ) answer*"what did we believe in March?"*(time-travel on the edge graph; correct from real`created_at` /`expired_at` ).**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). 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. 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/` 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. 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.** 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) ``` | 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 ` | | "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 | | Guide | What's inside | |---|---| | [Architecture](/ahmetvural79/Vitrus/blob/main/docs/ARCHITECTURE.md)[CLI reference](/ahmetvural79/Vitrus/blob/main/docs/CLI.md)`vitrus` command, grouped by what it does.[Providers](/ahmetvural79/Vitrus/blob/main/docs/PROVIDERS.md)[Scaling](/ahmetvural79/Vitrus/blob/main/docs/SCALING.md)[MCP](/ahmetvural79/Vitrus/blob/main/docs/MCP.md)[Examples](/ahmetvural79/Vitrus/blob/main/examples/README.md) ``` 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. 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](/ahmetvural79/Vitrus/blob/main/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` .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. - **A per-org MCP endpoint**—`https://api.vitrus.dev/t//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//mcp \ --header "Authorization: Bearer " openclaw mcp add vitrus --url https://api.vitrus.dev/t//mcp \ --transport streamable-http --header "Authorization: Bearer " ``` - **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. Issues and PRs welcome — the [roadmap](https://github.com/ahmetvural79/Vitrus/issues) is real deferred work, openly tracked. See [CONTRIBUTING.md](/ahmetvural79/Vitrus/blob/main/CONTRIBUTING.md) and the [security policy](/ahmetvural79/Vitrus/blob/main/SECURITY.md). The fastest way to help: try the quickstart, and file an issue for anything that didn't take 60 seconds. `@vitrus/core` and `@vitrus/mcp` are **Apache-2.0** (see [LICENSE](/ahmetvural79/Vitrus/blob/main/LICENSE)). The cloud apps (dashboard, multi-tenant API) live in a separate non-public repo. Vitrus draws on ideas explored by [GBrain](https://github.com/garrytan/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](https://vitrus.dev#demo) [cloud dashboard](https://app.vitrus.dev)*Built for teams that want to trust their answers.*