{"slug": "show-hn-vitrus-the-company-brain-that-tells-you-what-it-doesn-t-know", "title": "Show HN: Vitrus – the company brain that tells you what it doesn't know", "summary": "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.", "body_md": "Search hands you raw pages. Vitrus hands you **the answer + its sources + what it doesn't know** —\nall in **portable Markdown files you own**.\n\n[Live demo](https://vitrus.dev#demo) · [Quickstart](#install) · [Docs](#docs) · [Architecture](#architecture) · [Cloud](#vitrus-cloud) · [Roadmap](https://github.com/ahmetvural79/Vitrus/issues)\n\nOne brain — read by humansandagents. It cites every claim, and admits what it doesn't know.\n\n- 🧠\n**Ask your company in plain language**→ a sourced answer plus an honest list of what isn't documented ([see it](#what-this-looks-like)). - 🔌\n**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`\n\n. - 🎓\n**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`\n\n. - 🔎\n**Trust the ranking.**`--explain`\n\nprints every score factor; graph-signal ranking promotes results that are connected to, or corroborated across, other sources. - ⚡\n**Capture without friction.** One-command notes, ingest from any REST endpoint, or drop files in a watched inbox folder.`vitrus capture`\n\n·`vitrus ingest rest|inbox`\n\n. - 🤖\n**27 MCP tools** so Claude, Cursor and your own agents share the exact same trusted, permission-aware memory.\n\n*New since the last release — see What's new below.*\n\n``` bash\n$ vitrus think \"how was the payment outage resolved\"\n\nThe payment service returned 503s due to a gateway rate-limit breach.\nResolved by raising the limit from 500 to 1000 rps [1], per the\nrate-limit decision [2].\n\nSources:\n  [1] durable/runbooks/rate-limit\n  [2] durable/decisions/d-007\n\n⚠ What your brain doesn't know (1):\n  · \"durable/companies/acme\" is referenced but undocumented (missing)\n\nConfidence: 82% · oldest source: 12 days\n```\n\nThat gap box is the point of the project. Every answer ships with its **sources** and an honest,\n**deterministic** list of what your knowledge base *hasn't* documented. There is no LLM in the gap\ndetector, so it can't hallucinate a gap into existence — or out of it. A claim with no source is\nshown as a gap, never papered over.\n\n**Agent-native API hub.** Import an OpenAPI spec (`vitrus api import <spec>`\n\n), retrieve the right endpoint for a task (`vitrus api search`\n\n), and**verify a call deterministically before running it**(`vitrus api verify`\n\n→ valid / missing_args / wrong_type / unknown_args /**unknown_endpoint**/ deprecated) — the anti-hallucination gate.`vitrus api call`\n\nverifies, then executes. Also`vitrus ingest rest --config <c.json>`\n\nto pull any REST response into the brain. Visual API-integration drawer in the dashboard.**Day-one onboarding.**`vitrus onboard \"<role>\"`\n\nbuilds a sourced, pedagogically-ordered learning path from the brain (who to ask + what's not documented yet);`vitrus quiz \"<topic>\"`\n\ngenerates recall questions graded deterministically by`verify`\n\n.`--explain`\n\nranking attribution.`vitrus search \"<q>\" --explain`\n\nprints 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)`\n\nschema — no migration).**MCP surface 13 → 27 tools**(`entities`\n\n,`graph_query`\n\n,`get_node`\n\n,`chunks`\n\n,`attention`\n\n,`conflicts`\n\n,`api_search`\n\n/`api_verify`\n\n/`api_call`\n\n,`onboarding_path`\n\n,`quiz`\n\n, …; content tools are ACL fail-closed).**One-command capture.**`vitrus capture \"<note>\"`\n\n(arg/file/stdin) + a watched inbox folder (`vitrus ingest inbox <dir>`\n\n) for mobile capture.**12 prebuilt skills.**`vitrus skills list|install`\n\n— a validated SKILL.md library that teaches agents how to use Vitrus.\n\nThree design rules hold everywhere:\n\n**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.\n\nPick your entry point:\n\n```\n# 1) Zero-setup local brain (PGLite, no database server)\nbunx @vitrus/core init --pglite     # creates ./.vitrus\nvitrus import ./brain               # ingest markdown (embeds + self-linking graph)\nvitrus think \"how was the outage resolved\"\n\n# 2) Wire it into Claude Code / Cursor / OpenClaw / Hermes as MCP — two commands\ngit clone https://github.com/ahmetvural79/Vitrus && cd Vitrus/packages/core && bun install && bun link\nclaude mcp add vitrus -- bunx @vitrus/mcp\n\n# 3) Team scale: same engine on Postgres + pgvector\nbun add pg\nVITRUS_PG_URL=postgres://user@host/db vitrus import ./brain\n```\n\n`vitrus doctor`\n\nprints backend, providers and health (it never leaks secrets).\n\n```\nvitrus search \"rate limit\"     # hybrid retrieval: vector + BM25 + entity → RRF-fused hits\nvitrus think  \"what is the payment rate limit and why\"   # synthesized answer + sources + gap box + confidence\n```\n\n`search`\n\ngives you ranked nodes; `think`\n\ngives you the answer with provenance. Both respect ACLs and\nboth are honest about what isn't there.\n\nAnd two that most tools don't have:\n\n```\nvitrus watch    # proactive: stale knowledge, unresolved incidents, aging gaps — what needs attention\nvitrus verify \"the rate limit for payments is 500 rps\"\n# → STALE — supported by decisions/d-007, but superseded during the outage (now 1000 rps)\n```\n\n`verify`\n\nreturns one of four deterministic verdicts — **grounded · stale · contradicted ·\nunsupported** — with supporting sources and conflicts. No LLM judge; it's hybrid search + gap\nanalysis over your own record. Also available programmatically (`@vitrus/core/verify`\n\n) and as an MCP\ntool, so agents can fact-check **themselves** before acting.\n\nMarkdown is canonical — anything that becomes Markdown becomes knowledge:\n\n```\nvitrus import ./brain          # a folder of .md files (+ optional .edges.json sidecars)\n```\n\nThe connector framework is in the core (Apache-2.0): one interface (`fetch()`\n\n→ records with **content +\nACL**), idempotent ingest, incremental prune, and **permission capture on every sync** — remove\nsomeone from a channel and their access is revoked on the next sync, automatically.\n\n**Seven first-class live connectors** over one injectable, mock-testable HTTP layer (5 pagination\nstyles — REST-Link · GET-cursor · POST-cursor · GraphQL · offset · pageToken): **GitHub · Slack ·\nNotion · Linear · Jira · Drive · Gmail**. Incremental sync (`--since`\n\n, prune-safe), **webhook → live\ndelta** (GitHub direct; Slack triggers a re-sync), and a **durable, crash-recovery sync queue** with a\ncron scheduler. Plus offline adapters: **Email** (participants become the ACL) · **Calendar** · a\ngeneric **Docs** adapter · an **MCP-source bridge** (any MCP server becomes a source). Everything\nfunnels into **one brain**, so the same `alice`\n\nmentioned in Slack and authoring a PR fuses into a\nsingle graph node.\n\n```\nGITHUB_TOKEN=… vitrus ingest github --live --repo owner/name              # pull (incremental with --since)\nvitrus ingest slack --live --channel C0… --queue                          # enqueue a durable sync job\n```\n\n**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`\n\nmakes gap analysis*temporal*:*stale knowledge*,*unresolved incidents*and*aging gaps*surfaced**without being asked**. Deterministic, no LLM; schedule it (with nightly`vitrus dream`\n\nconsolidation) for a standing radar over your memory.**Ops-map**—`vitrus ops`\n\n(MCP`ops_report`\n\n) 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`\n\n/`vitrus resolve`\n\n(MCP`resolve_conflict`\n\n) 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`\n\n/`capture_session`\n\n+`vitrus decide`\n\n+`vitrus hooks install`\n\n(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]]`\n\ntyped edges, extracted without an LLM;**bi-temporal**—`vitrus dashboard --graph --asof <ISO>`\n\n(and`getConnections`\n\n/`graphSnapshot`\n\n) answer*\"what did we believe in March?\"*(time-travel on the edge graph; correct from real`created_at`\n\n/`expired_at`\n\n).**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`\n\n(crash-recovering).\n\nOffline-deterministic by default — no API key needed. Production providers are env-driven, one interface:\n\n| Providers | Env | |\n|---|---|---|\nEmbedder |\nOpenAI · Gemini · Cohere · offline hashing (default) | `VITRUS_EMBED_PROVIDER` |\nSynthesizer |\nOpenAI · Anthropic · Gemini · Ollama (local) · offline extractive | `VITRUS_SYNTH_PROVIDER` |\nReranker |\nCohere · Voyage · ZeroEntropy · lexical (default off) | `VITRUS_RERANK_PROVIDER` |\n\nWith a production embedder the brain is multilingual: ask in one language, retrieve sources written in another.\n\nServe the brain to any agent over the Model Context Protocol — **stdio + Streamable HTTP**, with\nOAuth 2.1 Resource Server support:\n\n```\nclaude mcp add vitrus -- bunx @vitrus/mcp     # stdio, one line\nvitrus-mcp --http 3000                        # or Streamable HTTP on :3000/mcp\n```\n\nAgents **read before they act and write after they decide.** Read tools: `search`\n\n· `think`\n\n·\n`gap_report`\n\n· `ops_report`\n\n· `provenance`\n\n· `verify`\n\n. Write tools: `record_decision`\n\n·\n`capture_session`\n\n· `resolve_conflict`\n\n(`remember`\n\n/ `forget`\n\n/ `improve`\n\ntoo). One command wires the\nloop into Claude Code / Cursor / Codex: `vitrus hooks install`\n\n. Markdown sources are exposed as\n`vitrus://node/<slug>`\n\nresources. Agents see **only what the token's user is allowed to see** — ACL is\nenforced at the index layer, fail-closed. The output of an import can also be an executable\n**Agent Skill (SKILL.md)** wired live to MCP.\n\nFour layers, each depending only on the one below:\n\n```\nsource of truth   markdown (+ .edges.json sidecar) in git   ← you own this\n      ↓\nengine            PGLite / Postgres+pgvector · hybrid search (vector + BM25 + entity → RRF)\n      ↓                                       · self-linking graph ([[type::slug]], LLM-free) · bi-temporal edges\ntrust surface     gap analysis · provenance · verify · confidence · attention\n      ↓\npresentation      CLI · MCP (stdio + HTTP) · SKILL.md export · web dashboard (cloud)\n```\n\nTwo engines, one contract: **PGLite** (WASM, zero-setup) for personal brains, **Postgres+pgvector**\nfor teams — same SQL, same engine, same answers. Invariants: **Markdown is canonical** (reset index →\nrebuild → answer unchanged). **The graph is LLM-free.** **Gaps are deterministic.** **ACL is\nfail-closed.**\n\nRuns on **Bun** (no build step). Four CI gates, all green:\n\n```\nbun run typecheck      # strict tsc\nbun run test           # 200+ tests (node:test runner)\nbun run eval           # source-hit ≥90% + gap recall/precision 100%\nbun run leak-test      # unauthorized access = 0 (ACL fail-closed)\n```\n\n| Symptom | Fix |\n|---|---|\n`vitrus: command not found` |\n`cd packages/core && bun link` (or use `bunx @vitrus/core` ) |\n| Answers feel weak in non-English | Set a production embedder: `VITRUS_EMBED_PROVIDER=openai` + key (default hashing embedder is language-naive) |\n`pg` errors on import |\nTeam scale needs `bun add pg` and a reachable `VITRUS_PG_URL` (PGLite needs neither) |\n| MCP server not showing tools | Check `claude mcp list` ; for HTTP, the endpoint is `/mcp` and auth is `Authorization: Bearer <token>` |\n| \"is my index stale?\" | The index is disposable: `vitrus reset && vitrus import ./brain` rebuilds everything from Markdown |\n| Anything else | `vitrus doctor` first — it reports backend, providers and health without leaking secrets |\n\n| Guide | What's inside |\n|---|---|\n|\n\n[Architecture](/ahmetvural79/Vitrus/blob/main/docs/ARCHITECTURE.md)[CLI reference](/ahmetvural79/Vitrus/blob/main/docs/CLI.md)`vitrus`\n\ncommand, 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)\n\n```\npackages/\n  core/     @vitrus/core — engine, hybrid search, gap analysis, CLI, connectors (Apache-2.0)\n    src/        the engine and CLI source (Bun runs TS directly, no build)\n    brain/      a sample brain you can `vitrus import`\n    migrations/ schema + row-level security\n    test/       the test + eval + leak-test suites\n  mcp/      @vitrus/mcp — the Model Context Protocol server (Apache-2.0)\ndocs/       the guides linked above\nexamples/   runnable recipes\nassets/     logo + icon\n```\n\nThis repo is the **open core**: everything above is Apache-2.0 licensed and self-hostable end-to-end, with no feature\nflags and no fake \"community edition\". Gap analysis is never gated.\n\nGap detection has no public benchmark — so we built **Gap-Eval** (open corpus + harness, in this\nrepo) and publish the numbers with their methodology:\n\n```\nvitrus bench gapeval --determinism    # or: bun run gapeval\n```\n\n| metric | v0 result |\n|---|---|\n| Recall / precision (overall, 18 gold-labeled cases, 5 gap kinds) | 100% / 100% |\n| False positives on clean brains (negative control) | 0 |\n| Determinism (same brain → byte-identical gaps, twice) | PASS |\n\nHonest framing: v0 is a **controlled synthetic corpus** (hand-authored brains with known gaps that\nexercise the engine's real mechanisms — dangling wikilinks, `contradicts`\n\n/`supersedes`\n\nedges,\nprovenance-less events). It proves the detector does exactly what it documents, deterministically,\nwith zero fabricated gaps; it does not claim real-world generalization. The corpus lives at\n[ packages/core/src/eval/gapeval/corpus](/ahmetvural79/Vitrus/blob/main/packages/core/src/eval/gapeval/corpus) — adding a harder\ncase is a one-directory PR. Retrieval benchmarks (LongMemEval/LoCoMo format, BYO dataset) run via\n\n`bun run bench`\n\n.There is also a hosted version at ** app.vitrus.dev** — the same Apache-2.0 engine\nin this repo, deployed multi-tenant, for teams that don't want to run their own. What it adds is\noperations, not capability:\n\n-\n**Web dashboard**— Ask,** Gap Explorer**, knowledge** Graph**,** Entities**,** Verify**, and trace-to-source on every answer. -\n**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. -\n**A per-org MCP endpoint**—`https://api.vitrus.dev/t/<org>/mcp`\n\nwith 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):\n\n```\nclaude mcp add --transport http vitrus \\\n  https://api.vitrus.dev/t/<org>/mcp \\\n  --header \"Authorization: Bearer <token>\"\n\nopenclaw mcp add vitrus --url https://api.vitrus.dev/t/<org>/mcp \\\n  --transport streamable-http --header \"Authorization: Bearer <token>\"\n```\n\n-\n**Team & ACL management**— roles (admin/member/viewer), seat-based membership, and an audit log of who asked what. -\n**Account & support**— self-serve workspace administration and a built-in support desk (available on every account, including free ones).\n\nSigning up is free — the Free plan includes the full dashboard with 1 brain · 1 seat · 2 connectors ·\n5k nodes; Pro ($25/seat/mo or $249/seat/yr) adds seats and scale. Either way there is no lock-in by\ndesign: your knowledge stays portable Markdown, and leaving the cloud means `vitrus import`\n\non your\nown machine.\n\nIssues and PRs welcome — the [roadmap](https://github.com/ahmetvural79/Vitrus/issues) is real deferred\nwork, openly tracked. See [CONTRIBUTING.md](/ahmetvural79/Vitrus/blob/main/CONTRIBUTING.md) and the\n[security policy](/ahmetvural79/Vitrus/blob/main/SECURITY.md). The fastest way to help: try the quickstart, and file an issue for\nanything that didn't take 60 seconds.\n\n`@vitrus/core`\n\nand `@vitrus/mcp`\n\nare **Apache-2.0** (see [LICENSE](/ahmetvural79/Vitrus/blob/main/LICENSE)). The cloud apps (dashboard,\nmulti-tenant API) live in a separate non-public repo.\n\nVitrus draws on ideas explored by [GBrain](https://github.com/garrytan/gbrain) — Markdown-canonical\nmemory and an LLM-free typed graph — implemented independently here with its own engine and a\ndifferent emphasis: the gap box. If GBrain's shape fits you better, use it; honest memory winning in\nany form is the point.\n\n** vitrus.dev** ·\n\n**·**\n\n[live demo](https://vitrus.dev#demo)\n\n[cloud dashboard](https://app.vitrus.dev)*Built for teams that want to trust their answers.*", "url": "https://wpnews.pro/news/show-hn-vitrus-the-company-brain-that-tells-you-what-it-doesn-t-know", "canonical_source": "https://github.com/ahmetvural79/Vitrus", "published_at": "2026-06-20 23:22:42+00:00", "updated_at": "2026-06-20 23:37:06.375836+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents", "large-language-models", "ai-products"], "entities": ["Vitrus", "Claude", "Cursor", "OpenAPI", "MCP", "Voyage", "ZeroEntropy"], "alternates": {"html": "https://wpnews.pro/news/show-hn-vitrus-the-company-brain-that-tells-you-what-it-doesn-t-know", "markdown": "https://wpnews.pro/news/show-hn-vitrus-the-company-brain-that-tells-you-what-it-doesn-t-know.md", "text": "https://wpnews.pro/news/show-hn-vitrus-the-company-brain-that-tells-you-what-it-doesn-t-know.txt", "jsonld": "https://wpnews.pro/news/show-hn-vitrus-the-company-brain-that-tells-you-what-it-doesn-t-know.jsonld"}}