Show HN: Vitrus – the company brain that tells you what it doesn't know

Vitrus, a new knowledge management tool, provides sourced answers and explicitly lists what it doesn't know, using deterministic gap detection to avoid hallucination. It offers agent-native API integration, onboarding paths, and graph-signal ranking, aiming to serve as a trusted company brain for both humans and AI agents.

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 <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 → 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 "<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. 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 <ISO 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/<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. 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 <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 | | 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/<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. 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.