Truenote

Website

A citation-first RAG system for support teams that need an answer they can verify before continuing the call.

Truenote turns SOPs, policy documents, screenshots, and tables into a controlled knowledge base. Customer service representatives ask a question and receive a grounded answer with clickable source excerpts. If the evidence is weak or the answer fails citation checks, Truenote refuses instead of guessing.

Why Truenote

A plausible answer is only the beginning. Truenote is built around the next question a representative has to answer: Can I trust this enough to say it to a customer?

Need	What Truenote does
Find exact policy terms and natural-language matches	Runs vector and PostgreSQL full-text search in parallel, then uses trigram search for keyword zero-hits and Cohere to rerank the merged candidates.
Keep unsupported answers off the screen	Refuses before generation when retrieval confidence is too low. Generated answers must cite known retrieved chunks or they are rejected.
Prevent cross-program retrieval	Filters every retrieval query by server-resolved program_id and classification, then applies a final fail-closed scope check.
Preserve context across chunk boundaries	Adds adjacent chunks for the strongest reranked anchors without letting those unscored neighbors affect the confidence gate.
Catch bad source material before it goes live	Holds uploads through file checks, malware scanning, content DLP, parsing, preview, and role-authorized activation or review.
Measure quality instead of judging a demo	Attributes failures to retrieval, reranking, thresholding, or generation, with optional claim-level faithfulness judging.

Retrieval and answer pipeline

flowchart LR
    Q["Question"] --> E["Embed"]
    E --> V["Vector search"]
    Q --> K["Full-text search"]
    K -->|"zero hits"| T["Trigram fallback"]
    V --> M["Merge and deduplicate"]
    K --> M
    T --> M
    M --> R["Cohere rerank"]
    R --> G{"Confidence gate"}
    G -->|"below threshold"| X["Refuse without an LLM call"]
    G -->|"passes"| N["Add adjacent context"]
    N --> L["ZDR-pinned generation route"]
    L --> C{"Citation and content validation"}
    C -->|"valid"| A["Answer with clickable sources"]
    C -->|"invalid or all routes fail"| X

Vector, full-text, trigram, neighbor, citation, and history reads are scoped in SQL to the authenticated user's program and clearance. Conversation history may help rewrite a follow-up into a standalone question, but it is not factual evidence for the answer.

Security work

Security is part of Truenote's data path, not a separate checklist. The repository includes controls for authorization, controlled ingestion, model input and output, audit delivery, browser requests, dependency review, and recovery-oriented retention.

Area	What is implemented	Evidence and operating path
Program and classification isolation	SQL filters use server-resolved scope and a final fail-closed program check.	Negative tests cover cross-program access, malformed principals, and classification boundaries.
Grounded generation	Retrieval gates, untrusted-excerpt instructions, citation validation, sensitive-output blocking, and defensive refusal protect every answer.	The eval harness measures retrieval, refusal, citation, and claim-level faithfulness.
Controlled ingestion	File signatures, EICAR checks, default-on scanner enforcement, content DLP, inactive versions, role-authorized activation or review, revocation, and retention gates protect source activation.	Lifecycle records preserve provenance, scan results, audited temporary scanner overrides, reviewer decisions, and document history.
Authentication and browser defense	Argon2id local passwords, hashed session tokens, OIDC Authorization Code with PKCE, MFA or ACR validation, CSP, Origin checks, and Fetch Metadata checks protect access.	Automated tests exercise identity validation, foreign origins, security headers, and privileged routes.
Audit and alerting	Hash-chained, append-only security events. A worker job prints each committed event to the log in order and emails the owner on break-glass and super user logins, account and role changes, security setting changes, failed-login and denial spikes, and failed audit writes. A readiness endpoint checks the database and the worker.	Alert rules and their production test record: docs/security/monitoring.md.
Supply chain	Pull requests, main, weekly, and manual runs execute PCI/vulnerability evidence checks, type checks, the production build, unit tests, high-severity dependency audit, CycloneDX SBOM generation, Gitleaks, and CodeQL security-extended analysis.	A safe baseline accounts for all 51 retained CodeQL results; the strict managed-release gate honestly remains blocked by missing owners, dates, and dispositions. Alert upload, current hosted execution, and release-linked results still require live verification.

Read the security documentation index, the PCI DSS readiness evidence pack, and the technical security capabilities brief. Report vulnerabilities through SECURITY.md.

This is the beginning of the README. Read the rest at the original. Read the full README ↗