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
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). - 🔌
Make any API agent-native. Import an OpenAPI spec, retrieve the right endpoint for a task, andverify 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 withwho to askandwhat'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.
$ 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
), andverify 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. Alsovitrus 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 byverify
.--explain
ranking attribution.vitrus search "<q>" --explain
prints each hit's score factors: vector/bm25/entity ranks + tier/cosine and the newgraph-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 frozenvector(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 isknown / 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:
bunx @vitrus/core init --pglite # creates ./.vitrus
vitrus import ./brain # ingest markdown (embeds + self-linking graph)
vitrus think "how was the outage resolved"
git clone https://github.com/ahmetvural79/Vitrus && cd Vitrus/packages/core && bun install && bun link
claude mcp add vitrus -- bunx @vitrus/mcp
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"
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 analysistemporal:stale knowledge,unresolved incidentsandaging gapssurfacedwithout being asked. Deterministic, no LLM; schedule it (with nightlyvitrus dream
consolidation) for a standing radar over your memory.Ops-map—vitrus ops
(MCPops_report
) reads the company as a system and flags operational inefficiencies:unownedservices,bus-factor(single-person) risk,bottlenecks(overloaded hubs),broken handoffs(depending on superseded ground), andredundant tools(embedding-similar services). Severity-ranked, each finding cites real nodes — evidence, not a consultant's guess.Conflict resolution—vitrus conflicts
/vitrus resolve
(MCPresolve_conflict
) detects contradictions and showsboth 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**: MCPrecord_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>
(andgetConnections
/graphSnapshot
) answer*"what did we believe in March?"*(time-travel on the edge graph; correct from realcreated_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 |
|---|---|
ArchitectureCLI referencevitrus
command, grouped by what it does.ProvidersScalingMCPExamples
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 — 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'sAgent accesspage):
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 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.
@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** ·
·
cloud dashboardBuilt for teams that want to trust their answers.