Vault

Permission-Aware Enterprise Knowledge System

Vault is an enterprise-grade knowledge retrieval system that enables support teams, account managers, and customer success staff to ask natural-language questions across scattered internal documents and receive cited, grounded answers — while enforcing strict permission boundaries that prevent unauthorized content from ever reaching the language model.

Enterprise knowledge is fragmented across dozens of systems:

• Support tickets in Zendesk or Intercom
• Engineering discussions in Jira and Confluence
• Team conversations in Slack
• Call recordings and transcripts in Gong or Chorus
• Company policies in Google Docs or Notion
• Customer data in CSVs and spreadsheets

When a support agent asks, "What did we promise this customer?", the answer might exist across a support ticket from last quarter, a Slack thread from the engineering team, and a signed contract amendment — but finding it requires navigating three different tools, each with its own search limitations.

Worse, some of those documents contain information the agent shouldn't see: HR notes, executive escalations, or confidential pricing details for other accounts.

Vault solves both problems simultaneously.

Vault ingests documents, parses and chunks them into searchable segments, and indexes them in a vector database with rich metadata — including department, classification, allowed_roles, and source identifiers.

When a user asks a question, Vault:

1. Authenticates the user and determines their permission scope
2. Filters retrieval at the database level, before any content reaches the language model
3. Searches using a hybrid approach (vector similarity + keyword matching)
4. Reranks results for maximum relevance
5. Generates a cited answer using only authorized sources
6. Logs the full trace for audit and compliance

The critical design principle: permission filtering happens before retrieval, not after generation. Unauthorized content never enters the model's context window.

Vault's permission model is not a post-processing filter — it's architectural. User roles and document access controls are enforced at the vector store query level. The language model only ever sees content the authenticated user is authorized to access.

• Role-based access control (RBAC) across eight roles — intern, employee, engineer, manager, hr, legal, finance, admin — mapped to five clearance tiers (public → admin)
• Per-chunk ACLs — every chunk carries an explicit list of roles allowed to read it
• Union of roles — a user holding multiple roles gets the combined access of all of them
• Deny by default — a chunk with no matching role is invisible; a user with no roles retrieves nothing
• Audit logging of every query, retrieved chunk, denial, and generated answer

See Access Policy for the full model, matrix, and enforcement details.

Vault connects to the tools your team already uses:

Each source connector extracts structured metadata (account, department, timestamp) and maps it to Vault's unified permission model.

Vault combines two search paradigms for maximum recall:

• Vector similarity for semantic understanding ("customer complained about billing" matches "invoice discrepancy")
• Keyword query expansion for exact matches (specific ticket IDs, error codes, proper nouns) — filler words are stripped and domain terms are expanded before retrieval

Results are merged and reranked using Cohere's cross-encoder for state-of-the-art relevance.

Every answer includes inline citations linking back to source documents. Users can verify claims, trace information to its origin, and assess recency. The system explicitly refuses to answer when insufficient authorized information exists, rather than hallucinating a response.

Every query generates a complete audit trail:

• User identity and timestamp
• Permission scope applied
• Retrieved chunks (with scores)
• Generated answer with citations
• Processing latency

This supports compliance requirements, debugging, and continuous quality improvement.

Question: "What's the SLA for this customer's enterprise tier?"

Vault retrieves the customer's contract terms, their support history, and the current SLA policy — but only if the agent has access to that account's documents.

Question: "What did we promise in the last renewal call?"

Vault synthesizes the call transcript, the follow-up email, and the contract amendment to provide a complete answer with source citations.

Question: "What was the root cause of the outage affecting Acme Corp?"

Vault pulls from the incident report, Slack discussion thread, and post-mortem document — scoped to the engineering team's permission level.

Question: "Show me all references to data retention policies across our support documentation."*

Vault searches across all policy documents, support scripts, and training materials, citing each reference with its source and last-updated timestamp.

This project enforces permission-aware retrieval: a user can only get answers drawn from documents their roles allow. Access is decided before retrieval, so restricted content is never fetched, ranked, or shown to the language model on behalf of an unauthorized user.

Note on the corpus. All documents are real, publicly available files (GitLab Handbook, CUAD contracts, SEC 10-K filings, Indian labour codes). Because public documents carry no access levels of their own, the roles, departments, and ACLs below are a simulated overlay defined to model a mid-sized software company. The access model is the thing being demonstrated; the documents are not confidential.

A mid-sized, remote-first software company with an Indian office: engineering, sales and marketing, HR, legal, and finance functions, plus company-wide material available to everyone.

1. Need-to-know over seniority. Legal and finance share a sensitivity tier but never see each other's documents. A single clearance ladder cannot express this, so every chunk carries an explicit list of roles allowed to read it.
2. Least privilege. Every role gets company-wide (general) material and only the departments its work requires.
3. Separation of duties. HR data stays with HR (and managers, for their reports). Security policy goes to engineers, who implement it. Contracts go to legal. Financial filings go to finance.
4. Deny by default. A chunk with no matching role is invisible. A user with no roles retrieves nothing.

Each role maps to exactly one clearance tier (many roles to one tier). Users may hold multiple roles; their access is the union.

Tiers drive legacy UI gating (a user's level is the highest tier among their roles). Retrieval is enforced by role, not tier.

Document sources by department:

• Each chunk is stored in the vector index with metadata: department, classification, allowed_roles, and source identifiers.
• At query time the user's roles are resolved server-side and applied as a metadata filter: {"allowed_roles": {"$in": user_roles}}. The model never decides what a user may see.
• Citations are re-checked against the user's roles before display.
• Every query, retrieved chunk ID, and denial is written to an audit log.

A leakage test suite runs adversarial and boundary queries per role and asserts that no restricted content appears. Cases include:

Canary strings are real, distinctive passages taken from restricted documents (for example, a specific party name and clause from one contract, or a specific figure from a 10-K). If a canary appears in a response to an unauthorized role, the test fails.

Results: fill in after running the suite (pass rate, number of cases, date).

• Managers can read the full HR folder, including compensation material. This is a deliberate simplification; a production system would likely scope managers to their own reports.
• Unmapped handbook pages default to general. A conservative production policy would default unmapped content to a restricted tier instead.
• Roles and ACLs are simulated. There is no real identity provider; personas are seeded users for demonstration and validation.
• Permission changes require updating chunk metadata in the vector index. Postgres is the source of truth and the index is a synced copy.

Vault's security model is designed for enterprise compliance requirements:

Unlike systems that filter results after the language model has already processed them, Vault filters at the vector store query level. Unauthorized content is never loaded into memory, never sent to the model, and never appears in logs or traces.

Retrieval is gated by role, using the allowed_roles ACL described in Access Policy. Clearance tiers (public → admin) are retained only for legacy UI gating — they are never used as the retrieval filter, because a single ladder cannot express that legal and finance share a tier but must not read each other's documents.

Every interaction is logged with full context: who asked what, what was retrieved, what was generated, and which permissions were applied. This supports SOC 2, HIPAA, and enterprise compliance requirements.

Vault includes a comprehensive evaluation framework to measure system quality:

A curated set of 50 questions spanning:

• Easy lookups — Single-source factual questions
• Cross-document synthesis — Answers requiring multiple sources
• Conflicting sources — Cases where documents disagree
• Stale information — Questions about outdated content
• Permission boundaries — Cases requiring refusal or restricted answers
• Edge cases — Ambiguous, malformed, or adversarial queries

Retrieval Quality (measured independently from generation):

• Precision@5 — Relevance of top-5 retrieved chunks
• Recall@k — Coverage of all relevant documents
• Mean Reciprocal Rank — Position of first relevant result

Generation Quality:

• Faithfulness — Groundedness in retrieved sources
• Relevance — Alignment with user's question
• Citation accuracy — Correctness of source attributions

Security (Non-Negotiable):

• Unauthorized leakage rate — Must be exactly 0.0
• Permission boundary accuracy — Correct refusals and scoping

POST /api/auth/register
POST /api/auth/login

POST /api/query
Authorization: Bearer <token>
Body: { "question": "string", "context": "optional" }
Response: { "answer": "string", "citations": [...], "trace_id": "string" }

POST /api/documents/ingest
GET  /api/documents/{id}
DELETE /api/documents/{id}

GET /health

MIT License. See LICENSE for details.