vkbm
Citation-Grounded 4-Layer Knowledge Base & Associative Memory Engine

vkbm — Citation-Grounded 4-Level Knowledge Base & Associative Memory Engine

vkbm — Citation-Grounded 4-Level Knowledge Base & Associative Memory Engine

vkbm is a high-assurance, zero-dependency 4-Level Hierarchical Knowledge Base (Book -> Section -> Rule -> Quote) and Hybrid Truncated-SVD + BM25 Associative Memory Engine. It compiles unstructured and structured regulatory handbooks, compliance policies, legal contracts, and operational runbooks into an out-of-core paged vector graph with word-for-word printed-page citation verification, clause-by-clause contract gap analysis, and built-in OpenAI (/v1/chat/completions) & Model Context Protocol (POST /mcp, --mcp-stdio) agent endpoints.


Core Capabilities

Capability Operational Mechanics Key Guarantee
4-Level Hierarchical Knowledge Graph (L3..L0) Compiles documents into a 4-tier Associative HNSW pyramid: L3 Booklet & Pinned Supervisory Axioms -> L2 Table-of-Contents Sections -> L1 Multi-Sentence Normative Rules & Deontic Modalities -> L0 Verbatim Page-Cited Quotes. Structural context and parent-child lineage are preserved across every retrieval turn.
Hybrid Truncated SVD + BM25 Associative Recall Combines corpus-adaptive Randomized Truncated SVD (LSA latent subspace), 650+ domain #syn_* synset expansions, signed character 3–5gram subwords, Okapi BM25 lexical scoring, +0.55 rare-bigram phrase boost, and HNSW spreading activation. Recalls exact regulatory terms (12 CFR 30, CECL) and cross-vocabulary paraphrases (RPO/RTO <-> resumption targets).
Out-of-Core 4 KB Binary Vector Pager (VVEC v2) Pages int8 symmetric quantized vectors (260 B @ 256-D, 132 B @ 128-D) through a bounded 4 KB binary page cache (8.0 MB default RAM budget) backed by a crash-safe write-ahead log (index.wal) and atomic index snapshots (index.idx). Scales from 18,000 handbook nodes to multi-million-passage corpora within a fixed memory envelope.
2-Turn Coarse-to-Fine WorkingSet Zoom Loads compact L3/L2 summaries on Turn 1, identifies the highest-relevance sections, and executes zoom_in(L2 -> L1/L0) via $O(1)$ shard byte-offset seeks on Turn 2, rendering sorted TOON-LD @graph tables. Cuts LLM prompt token consumption by 61.4%–80% compared to flat top-$K$ chunk retrieval.
Deterministic Word-for-Word Citation Verifier Audits structured citations (@id, doc_id, section_id, printed_page, quoted_span) directly against L0 passage shards using exact and whitespace-normalized substring matching. Eliminates fabricated section references, wrong page numbers, and paraphrased quotes masquerading as verbatim text.
Clause-by-Clause Contract Gap Auditor Splits vendor agreements (MSAs, cloud schedules, SLAs) into normative clauses, tags deontic modalities (mandatory, prohibition, supervisory, commitment, permission), and classifies coverage as MATCHED, PARTIAL_REVIEW, or GAP_ALERT. Evaluates a 40-clause contract in under 90 ms without requiring external GPU infrastructure.
OpenAI Proxy, MCP Server & Role-Separated Web Studio Serves 22 REST endpoints, an OpenAI-compatible /v1/chat/completions proxy, an 8-tool JSON-RPC 2.0 MCP server (POST /mcp & --mcp-stdio), and a 4-portal browser workspace (/ui/auth, /ui/portal, /ui/delegated, /ui/admin). Drop-in memory plane for human examiners, vllm inference gateways, vsight SOC analysts, and autonomous MCP agents.

Live Interactive Studio Preview

Examiner Associative Recall & TOON-LD @graph Inspector

vkbm Examiner Portal — 4-Layer Associative Recall, Token Budget Telemetry, and TOON-LD Graph Output

Clause-by-Clause Contract Gap Audit

vkbm Examiner Portal — Vendor MSA Clause-by-Clause Compliance Audit with Modality Tags and Page Citations


End-to-End Pipeline & Daemon Binaries

vkbm ships a unified walkthrough executable alongside specialized, composable CLI binaries for deterministic offline corpus compilation and online associative memory serving:

Binary Primary Purpose Typical Output / Interface
vkbm Self-contained walkthrough demonstrating VVEC v2 initialization, L3 axiom pinning, 4-layer handbook ingestion, Truncated SVD fitting, TOON-LD recall, and zoom_in / zoom_out navigation. Console telemetry & TOON-LD @graph output
build_index Extracts PDF pages (pdftotext -layout), resolves 2-pass TOC sections and 2-regime printed-page footers, and emits normalized passage indices. <corpus>_index.json
build_vectors Tokenizes passages with legal-negation preservation and domain synsets, fits Randomized Truncated SVD (LSA), and computes concept vectors. <corpus>_data.json
build_page Bundles <corpus>_data.json into a 100% offline, single-file browser search portal with zero remote asset dependencies. knowledge_base.html
build_export Exports citation-carrying consolidated Markdown volumes with <!-- page printed="N" pdf="N" --> provenance markers. exports/<corpus>.md
verify_artifacts Cryptographically and structurally audits compiled indices, vector dimensions, page coverage, and zero-remote-reference HTML invariants. Exit code 0 on full pass
serve_memory Runs the stateful 4-layer associative memory HTTP daemon, Web Studio, OpenAI /v1/chat/completions proxy, and MCP JSON-RPC 2.0 server. http://127.0.0.1:7331 or --mcp-stdio
bench_eval Executes deterministic retrieval ablation (Recall@5, MRR), token-budget compression, VVEC v2 quantization fidelity, and contract gap audit benchmarks. Benchmark scorecard

5-Minute Quickstart

1. Run the Self-Contained Associative Memory Walkthrough

Execute the vkbm binary to verify local VVEC v2 quantized paging, 4-layer HNSW graph construction, pure-CPU Truncated SVD fitting, and WorkingSet zoom:

POWERSHELL
# Windows
.\dist\bin\windows\vkbm.exe
BASH
# Linux
./dist/bin/linux/vkbm

2. Compile an Offline Citation-Grounded Corpus

Compile a structured PDF corpus (such as corpora/occ.json or corpora/ffiec.json) through the 5-stage deterministic pipeline:

BASH
./dist/bin/linux/build_index --corpus occ
./dist/bin/linux/build_vectors --corpus occ --dims 128
./dist/bin/linux/build_page --corpus occ
./dist/bin/linux/build_export --corpus occ
./dist/bin/linux/verify_artifacts --corpus occ

3. Launch the serve_memory Daemon, Web Studio & Agent Server

Start the persistent associative memory engine with int8 VVEC v2 quantization and 256-D hybrid vectors:

BASH
./dist/bin/linux/serve_memory \
  --dir ./.vstore/regulatory_kb \
  --host 127.0.0.1 \
  --port 7331 \
  --dim 256 \
  --quantize-int8 \
  --budget 600

Once running on http://127.0.0.1:7331:

  • Interactive Web Studio: Open http://127.0.0.1:7331/ui/auth to launch Examiner, Corpus Steward, or Global Admin sessions.
  • Associative Recall API: POST http://127.0.0.1:7331/recall
  • Contract Gap Audit API: POST http://127.0.0.1:7331/audit_contract
  • Citation Span Verifier API: POST http://127.0.0.1:7331/verify_citations
  • OpenAI Chat Proxy: POST http://127.0.0.1:7331/v1/chat/completions
  • MCP Tool Endpoint: POST http://127.0.0.1:7331/mcp

Documentation Navigation

  • How-To Guide — Step-by-step recipes for ingesting PDFs and handbooks, fitting Truncated SVD subspaces, launching OpenAI/MCP servers, and auditing contracts.
  • End-User Guide — Interactive Web Studio walkthroughs, 2-turn coarse-to-fine recall, WorkingSet zoom controls, and citation anchor inspection.
  • Administrator Guide — Store lifecycle governance, verify_artifacts validation, air-gapped deployment, Bearer authentication, and shard compaction.
  • Operations & Use Cases — Production workflows with vllm, vendor MSA gap checks, vsight SOC runbook grounding, and autonomous MCP tool calls.
  • Configuration & CLI Reference — Complete CLI flags, environment variables, corpora/*.json and .toon synset schemas, HTTP endpoints, and MCP tool specifications.
  • Performance & Sizing — Empirical retrieval ablation, 98.5% printed-page accuracy across 58 booklets, token-efficiency benchmarks, and hardware sizing tables.

How-To Guide — Step-by-Step Operational Recipes

This guide provides copy-pasteable operational recipes for compiling PDF and Markdown corpora into 4-level hierarchical knowledge graphs, building hybrid BM25 + Truncated SVD indices, launching the serve_memory OpenAI and MCP server, auditing contracts for regulatory gaps, and verifying verbatim page citations.


Recipe 1: Ingest PDF Handbooks into a Deterministic Offline Corpus

Use the 5-stage offline compiler when publishing immutable handbook distributions (such as OCC Comptroller's Handbooks, FFIEC IT Examination Booklets, or internal SOP manuals) with a standalone knowledge_base.html explorer and citation-preserving Markdown export.

Prerequisites

Ensure Poppler pdftotext (>= 22.x) is installed on your PATH so build_index can extract layout-preserving page columns without invoking a system shell:

BASH
pdftotext -v

Step 1: Define the Corpus Manifest (corpora/my_policy.json)

Create a JSON configuration file inside corpora/ describing your PDF directory, header/footer rules, and curated starter queries:

JSON
{
  "id": "my_policy",
  "name": "Enterprise Cloud & Vendor Risk Standards",
  "brandmark": "ENTERPRISE RISK KB",
  "pdf_dir": "pdfs/my_policy",
  "index_json": "data/my_policy_index.json",
  "data_json": "data/my_policy_data.json",
  "page_html": "dist/my_policy/knowledge_base.html",
  "export_md": "exports/my_policy.md",
  "footer_matchers": ["occ", "ffiec", "page_n"],
  "header_prefixes": [
    "Comptroller's Handbook",
    "FFIEC IT Examination Handbook",
    "Enterprise Security Policy"
  ],
  "examples": [
    "board oversight of critical cloud service providers",
    "encryption key custody and incident notification timelines",
    "annual disaster recovery failover testing RPO RTO"
  ]
}

Step 2: Run the 5-Stage Compiler & Verifier

BASH
# 1. Parse PDFs, resolve 2-pass Roman/decimal TOC hierarchy, and map printed-page footers
./dist/bin/linux/build_index --corpus my_policy

# 2. Build hybrid vocabulary, expand domain synsets, and fit Randomized Truncated SVD (128-D)
./dist/bin/linux/build_vectors --corpus my_policy --dims 128

# 3. Compile 100% self-contained single-file HTML explorer (zero remote URLs)
./dist/bin/linux/build_page --corpus my_policy

# 4. Export consolidated Markdown with <!-- page printed="N" pdf="N" --> citations
./dist/bin/linux/build_export --corpus my_policy

# 5. Verify index integrity, vector norms, page coverage, and HTML security invariants
./dist/bin/linux/verify_artifacts --corpus my_policy

Recipe 2: Launch serve_memory and Seed a 4-Level Associative Store

For dynamic multi-document ingestion, live associative recall, contract gap audits, and LLM/MCP agent grounding, run serve_memory.

Step 1: Start the Daemon

BASH
./dist/bin/linux/serve_memory \
  --dir ./.vstore/compliance_prod \
  --host 127.0.0.1 \
  --port 7331 \
  --dim 256 \
  --quantize-int8 \
  --budget 650 \
  --auth-token "${VKBM_AUTH_TOKEN}" \
  --require-auth

Step 2: Sign In via the Role-Separated Authentication Gate

Navigate to http://127.0.0.1:7331/ui/auth to establish a scoped session (Examiner / Compliance Analyst, Corpus Steward, or Global Memory Admin) and inspect live header telemetry (Live Nodes, HNSW, LSA Dims, VVEC Hits).

vkbm Role-Separated Authentication Gate & Session Provisioning

Step 3: Pin a Tier-3 (L3) Supervisory Axiom

Pinned L3 axioms reserve dedicated capacity inside every WorkingSet so non-negotiable institutional mandates are never evicted during retrieval:

BASH
curl -sS -X POST http://127.0.0.1:7331/ingest \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "shape": "axiom",
    "pinned": true,
    "salience": 0.99,
    "fields": ["mandate", "authority", "rule"],
    "values": {
      "mandate": "Third-Party Critical Activity Governance",
      "authority": "OCC Bulletin 2023-17 / 12 CFR Part 30",
      "rule": "Every critical vendor engagement must preserve audit rights, subcontractors disclosure, encryption custody, and 72-hour cyber incident notice."
    }
  }'

Step 4: Ingest Structured Documents via Strategy-Driven Parsing

Use /ui/delegated (Corpus Steward Portal) or POST /ingest_document to compile handbooks, regulations, or contracts directly into L3 -> L2 -> L1 -> L0 nodes.

vkbm Corpus Steward Portal — Multi-Strategy Document Ingestion

BASH
curl -sS -X POST http://127.0.0.1:7331/ingest_document \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_id": "occ-2023-17",
    "document": "OCC Bulletin 2023-17 Third-Party Relationships",
    "strategy": "occ_ffiec_handbook",
    "salience": 0.92,
    "raw_text": "I. Governance and Risk Management\nPage 8\nA banking organization should adopt risk management practices commensurate with the level of risk and complexity of its third-party relationships.\n\nIII.C.2 Right to Audit and Remediation\nPage 27\nContracts for critical activities must stipulate the banking organization right to audit, review independent SOC 2 Type II reports, and enforce timely remediation."
  }'

Step 5: Fit the Corpus-Adaptive Truncated SVD (LSA) Subspace

After ingesting or updating documents, refit the pure-CPU Randomized Truncated SVD model so every L3..L0 node is re-projected into the learned latent subspace:

BASH
curl -sS -X POST http://127.0.0.1:7331/refit_lsa \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"dims": 64}'

Recipe 3: Connect OpenAI Clients & Autonomous MCP Agents

Option A: OpenAI-Compatible /v1/chat/completions Proxy

Configure serve_memory with an upstream OpenAI-compatible inference server (such as local vllm, llama-server, or an enterprise gateway) via environment variables:

BASH
export VKBM_LLM_URL="http://127.0.0.1:8000/v1/chat/completions"
export VKBM_LLM_MODEL="Qwen2.5-14B-Instruct"

Any standard OpenAI SDK or HTTP client can now query http://127.0.0.1:7331/v1/chat/completions. vkbm intercepts the user prompt, executes 2-turn coarse-to-fine associative recall + zoom_in, injects the verified TOON-LD @graph context, calls the upstream model, and runs deterministic citation verification before returning the response:

BASH
curl -sS -X POST http://127.0.0.1:7331/v1/chat/completions \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vkbm-grounded",
    "messages": [
      {
        "role": "user",
        "content": "What contractual audit rights are required for critical cloud vendors under OCC 2023-17?"
      }
    ],
    "temperature": 0.1
  }'

Option B: Model Context Protocol (POST /mcp or --mcp-stdio)

For desktop coding assistants, compliance copilots, or autonomous orchestrators, expose the 8 grounded memory tools over JSON-RPC 2.0:

JSON
{
  "mcpServers": {
    "vkbm": {
      "command": "./bin/serve_memory",
      "args": [
        "--dir", "./data/compliance_prod",
        "--dim", "256",
        "--quantize-int8",
        "--mcp-stdio"
      ]
    }
  }
}

Or invoke POST /mcp directly over HTTP:

BASH
curl -sS -X POST http://127.0.0.1:7331/mcp \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "vkbm_recall",
      "arguments": {
        "query": "RPO RTO disaster recovery failover exercises",
        "budget": 500
      }
    }
  }'

Recipe 4: Run Automated Contract Gap Analysis & Quote Verification

Step 1: Audit Draft Contract Text Against Regulatory Baselines

Submit draft agreement clauses to POST /audit_contract to classify every normative obligation (MATCHED, PARTIAL_REVIEW, or GAP_ALERT) with exact handbook citations:

BASH
curl -sS -X POST http://127.0.0.1:7331/audit_contract \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_name": "Core Ledger Cloud Hosting MSA v3",
    "contract_text": "1. Audit Rights. Customer may review Provider annual SOC 2 Type II summary report upon written request, and regulatory agencies may examine critical operations.\n\n2. Subcontractors. Provider may engage fourth-party subcontractors at its sole discretion without prior customer notification.\n\n3. Incident Reporting. Provider shall notify Customer within 24 hours of confirming any unauthorized access to Customer NPI.",
    "top_k": 3
  }'

Step 2: Verify Every Quoted Span Word-for-Word (POST /verify_citations)

Before publishing an AI-authored compliance memo, pass its structured citations to /verify_citations to confirm that every @id, doc_id, section_id, printed_page, and quoted_span matches the L0 shard byte-for-byte:

BASH
curl -sS -X POST http://127.0.0.1:7331/verify_citations \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "citations": [
      {
        "node_id": "n_8",
        "doc_id": "occ-2023-17",
        "section_id": "III.C.2",
        "printed_page": "27",
        "quoted_span": "Contracts for critical activities must stipulate the banking organization right to audit"
      }
    ]
  }'

End-User Guide — Search, WorkingSet Zoom & Citation Workflows

This guide explains how compliance examiners, legal reviewers, security analysts, and technical researchers use vkbm to search multi-handbook corpora, navigate the 4-level hierarchy (Book -> Section -> Rule -> Quote), inspect confidence and printed-page anchors, and audit legal contracts.


Understanding the 4-Level Knowledge Hierarchy

Every document compiled into vkbm is structured as a 4-tier pyramid rather than disconnected flat chunks:

Tier Graph Node Type What It Represents How Examiners Use It
L3 (tier = 3) Booklet / Document & Pinned Axioms Top-level handbook identity (e.g., OCC Bulletin 2023-17) plus pinned supervisory mandates (pinned = true). Anchors high-level regulatory scope and keeps non-negotiable rules permanently resident in WorkingSet memory.
L2 (tier = 2) Section Centroid Authoritative Table-of-Contents section (e.g., §III.C.2 — Right to Audit and Remediation) with an L2-normalized salience-weighted concept vector. Provides fast, low-token structural orientation on Turn 1 before drilling down into verbatim clauses.
L1 (tier = 1) Normative Rule / Obligation Multi-sentence regulatory mandate, prohibition, or contractual commitment tagged with deontic modality (mandatory, prohibition, supervisory, commitment, permission). Maps individual contract clauses directly against enforceable regulatory obligations.
L0 (tier = 0) Verbatim Page-Cited Quote Exact passage text stored in 64 MB .toon shards with immutable {doc_id, section_id, printed_page, page_index} provenance. Supplies court- and exam-ready verbatim quotations verified word-for-word against the source page.

Signing In & Role-Scoped Workspaces

Open http://127.0.0.1:7331/ui/auth in any modern desktop browser. vkbm separates daily analytical lookup from corpus mutation and store administration across three workspaces:

  1. Examiner / Compliance Analyst (/ui/portal) — Read-only access to Associative Recall (/recall), 2-Turn Cited Q&A (/ask), Contract Gap Audit (/audit_contract), Citation Verification (/verify_citations), and the CentralIndex Record Browser.
  2. Corpus Steward (/ui/delegated) — Scoped privileges to ingest structured handbooks, regulations, and runbooks (/ingest_document), pin supervisory axioms (/ingest), and load .toon synset packs.
  3. Global Memory Administrator (/ui/admin) — Full store governance including Randomized Truncated SVD refitting (/refit_lsa), Ebbinghaus consolidation (/consolidate), WAL/shard compaction (/compact), runtime vector tuning, and live MCP JSON-RPC inspection.

Workflow 1: Associative Recall & TOON-LD @graph Inspection

In the Examiner Portal (/ui/portal), select the Associative Recall & WorkingSet workspace:

  1. Enter a natural-language query, acronym, or exact citation phrase (for example, board oversight critical vendor audit rights subcontractor cyber incident notification).
  2. Set your Token Budget (default 500–650 tokens). vkbm automatically reserves space for pinned L3 axioms first, then loads the highest-scoring L2/L1/L0 nodes via 4-layer HNSW traversal, #syn_* synset expansion, and spreading activation (gamma = 0.25).
  3. Inspect the TOON-LD @graph Context Pane and Record Browser:
    • Records are grouped deterministically by shape (axiom, booklet, section, obligation, passage) and sorted by @id.
    • Every L0 passage displays its doc_id, section_id, printed_page (the page number printed in the document footer), and page_index (the 1-based physical PDF page).

vkbm Examiner Portal — Associative Recall, Token Telemetry, and CentralIndex Record Browser


Workflow 2: 2-Turn Coarse-to-Fine Cited Q&A & WorkingSet Zoom

When answering complex multi-section regulatory questions, flat RAG systems waste thousands of tokens loading full passages from marginally relevant chapters. vkbm uses 2-Turn Coarse-to-Fine Synthesis:

  • Turn 1 (Coarse Orientation): vkbm retrieves compact L3 booklet headers and L2 TOC section summaries across the entire store.
  • Turn 2 (Selective zoom_in): vkbm identifies the highest-scoring L2 section nodes and calls zoom_in, swapping out the coarse summary for its exact L1 obligations and L0 verbatim quotes via $O(1)$ shard byte-offset seeks.

vkbm Examiner Portal — 2-Turn Coarse-to-Fine RAG Synthesis, Verified Citations, and WorkingSet Zoom

Interactive zoom_in and zoom_out Controls

You can also drive coarse-to-fine navigation manually from the UI or HTTP API:

  • zoom_in (POST /zoom_in): Expands an L3 booklet into its L2 sections, or expands an L2 section (such as n_3 -> OCC-2023-17 §III.C.2) into its child L1 rules and L0 verbatim quotes.
  • zoom_out (POST /zoom_out): Collapses child L1/L0 nodes back into their parent L2 summary, freeing WorkingSet token budget for exploring another handbook chapter.

Workflow 3: Clause-by-Clause Contract Compliance Auditing

Use the Contract Compliance Audit tab in /ui/portal to screen draft vendor agreements, cloud addenda, or internal policies against your loaded regulatory corpora:

  1. Paste the draft agreement text and assign a descriptive document title.
  2. Click Run Clause Audit. vkbm segments the agreement into discrete clauses, classifies each clause's deontic modality (mandatory, prohibition, supervisory, commitment, permission), and preserves legal negations (not, no, never, without, neither, nor).
  3. Review the per-clause disposition cards:
    • MATCHED: Strong semantic and lexical alignment with authoritative L1/L0 regulatory rules, accompanied by exact section and printed-page citations.
    • PARTIAL_REVIEW: Moderate overlap or scope divergence (for example, right-to-audit restricted solely to vendor-authored executive summaries or fourth-party subcontracting lacking prior notice).
    • GAP_ALERT: No supporting regulatory alignment or direct contradiction with a mandatory obligation—requires legal redlining before execution.

vkbm Examiner Portal — Clause-by-Clause Contract Gap Audit


Workflow 4: Offline Single-File Explorer (knowledge_base.html)

When operating on air-gapped examination laptops without running a local HTTP daemon, open the compiled knowledge_base.html file directly from disk (./dist/knowledge_base.html):

  • 100% Self-Contained: All CSS, JavaScript, Truncated SVD projection matrices, and passage records are embedded inside the single HTML file with zero external fonts, scripts, or network calls.
  • Instant Hybrid Filtering: Type regulatory terms or click curated starter chips to rank passages across booklets, filter by handbook title or TOC section, and copy pre-formatted citations (Document, Section §X.Y, p. N) to your clipboard.

Administrator Guide — Corpus Governance, Security & Operations

This guide covers day-2 operational administration of vkbm: persistent store anatomy, deterministic artifact verification, air-gapped deployment, Bearer authentication and SSRF controls, Truncated SVD subspace maintenance, WAL recovery, shard compaction, and backup/restore procedures.


Global Administrator Console (/ui/admin)

Administrators manage store health, vector subspace refitting, Ebbinghaus memory consolidation, shard compaction, and live MCP JSON-RPC 2.0 tool inspection from the dark-mode Global Administrator Console at http://127.0.0.1:7331/ui/admin.

vkbm Global Administrator Console — Store Telemetry, Subspace Controls, and Live MCP JSON-RPC Inspector

Key Header Telemetry Indicators

Metric Meaning Operational Target
Live Nodes Active non-tombstoned records across L3 booklets/axioms, L2 sections, L1 rules, and L0 passages. Scales linearly; run /compact if deleted tombstones exceed 15% of total records.
HNSW Indexed vertices inside the 4-layer Associative HNSW navigation graph (graph.vhnsw). Should equal Live Nodes after ingestion and compaction.
LSA Dims Active latent dimensions of the Randomized Truncated SVD model (lsa.vlsa). Typically 32–128 (0 before initial /refit_lsa call).
VVEC Hits Cumulative 4 KB binary vector page cache hits served from RAM without OS page faults. > 98% hit ratio under normal WorkingSet workloads (2,048 pages = 8.0 MB cache).

Store Directory Layout & Crash-Safe Persistence

A serve_memory store directory (--dir ./data/store) maintains strict separation between append-only TOON text shards, binary paged vectors, HNSW graph topology, and atomic metadata snapshots:

TEXT
./data/store/
├── store.lock                  # Exclusive single-writer lock with live OS PID verification
├── index.idx                   # Atomic CentralIndex metadata snapshot (temp-write + fsync + rename)
├── index.wal                   # Append-only Write-Ahead Log replayed automatically after unclean shutdown
├── vectors.vvec                # 4 KB page-aligned binary vector file (VVEC v1 f32 or VVEC v2 int8)
├── graph.vhnsw                 # Persisted 4-layer Associative HNSW adjacency lists & entry point
├── lsa.vlsa                    # Persisted Randomized Truncated SVD vocabulary & projection matrix
└── shape_<name>_seg<N>.toon    # Auto-rotated 64 MB immutable TOON record shards (axiom, section, passage, ...)

Deterministic Corpus Verification (verify_artifacts)

Before promoting compiled corpora to examination laptops, compliance portals, or production serve_memory nodes, run verify_artifacts as a mandatory release gate:

BASH
./dist/bin/linux/verify_artifacts --corpus occ
./dist/bin/linux/verify_artifacts --corpus ffiec

verify_artifacts enforces six structural and security invariants:

  1. Schema & Manifest Completeness: Confirms <corpus>_index.json, <corpus>_data.json, knowledge_base.html, and exports/<corpus>.md exist and parse cleanly.
  2. Citation Provenance Coverage: Verifies every passage carries non-empty doc_id, section_id, printed_page, and valid 1-based page_index bounds.
  3. Numerical Vector Sanity: Confirms every Truncated SVD projection row and passage concept vector matches the declared dimensionality with finite norms (zero NaN or Inf values).
  4. Zero Unescaped Script Closers: Confirms embedded JSON blocks inside knowledge_base.html escape </script> sequences (<\/script>) to prevent DOM breakout.
  5. 100% Air-Gapped Self- Containment: Scans knowledge_base.html outside #kbdata prose to guarantee zero remote http://, https://, //, javascript:, or vbscript: references.
  6. Markdown Export Fidelity: Verifies consolidated Markdown exports preserve <!-- page printed="N" pdf="N" --> anchors and escape embedded Markdown headings/fences inside verbatim regulatory text.

Authentication, Network Binding & Air-Gapped Hardening

1. Loopback-First Binding, TLS Proxy & Production Deployment

By default, serve_memory binds exclusively to 127.0.0.1:7331. In multi-user enterprise deployments:

  • Keep serve_memory bound to loopback (or an isolated container network) behind a TLS-terminating reverse proxy (such as Caddy, NGINX, or Envoy) enforcing HTTPS/HSTS and mTLS or OIDC. Reference production manifests ship in Dockerfile, deploy/compose.yaml, deploy/Caddyfile, and deploy/vkbm.service.
  • Enable --require-auth, --secure-cookies, and --audit-log, and inject a high-entropy 256-bit secret via VKBM_AUTH_TOKEN (rather than passing secrets on shared process command lines). serve_memory fails closed at startup if --require-auth is enabled without a configured token:
BASH
export VKBM_AUTH_TOKEN="$(openssl rand -hex 32)"
./dist/bin/linux/serve_memory \
  --store ./data \
  --addr 127.0.0.1:7331 \
  --require-auth \
  --secure-cookies \
  --session-ttl 28800 \
  --llm-timeout 60 \
  --audit-log
  • Observability & Backpressure: Scrape GET /metrics (Prometheus exposition format) for store telemetry, HTTP request/error counts, auth denials, rate-limit counters, and active connections. When active_conns reaches max_concurrent_conns (32), excess connections receive an immediate 503 Service Unavailable response without stalling the accept loop. Expensive and authentication endpoints enforce per-minute rate limiting (429 Too Many Requests), and token budgets are bounded (16..16384).

2. Upstream LLM Endpoint Validation (Anti-SSRF & Chunked HTTP)

When configuring /ask or /v1/chat/completions to call an inference server (VKBM_LLM_URL or runtime POST /configure), vkbm enforces strict http:// URL validation (rejecting cleartext https:// on raw sockets to prevent accidental credential leakage—use a local TLS proxy sidecar for remote HTTPS endpoints), loopback-only targets on runtime /configure unless --allow-remote-config is explicitly enabled, CRLF/header-injection guards, Transfer-Encoding: chunked decoding, configurable --llm-timeout (default 60s), and bounded response sizes (<= 2 MB for LLM completions; <= 64 KB for inbound HTTP requests with 413 Payload Too Large).

3. Air-Gapped Operation

vkbm requires zero external network access for indexing, Randomized Truncated SVD training, VVEC v2 paging, 4-layer HNSW recall, contract gap auditing (/audit_contract), and word-for-word citation verification (/verify_citations). Only optional generative synthesis (/ask, /v1/chat/completions) or optional external Matryoshka embeddings (--embed-url) initiate outbound HTTP connections—typically to a co-located loopback vllm instance on the same air-gapped host.


Subspace Maintenance, Consolidation & Compaction

Refitting Truncated SVD (POST /refit_lsa)

Whenever corpus stewards ingest new regulatory booklets exceeding ~10% of existing store volume, trigger an online Truncated SVD refit so domain co-occurrence patterns update across all vectors:

BASH
curl -sS -X POST http://127.0.0.1:7331/refit_lsa \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"dims": 64}'

Ebbinghaus Consolidation & Shard Compaction (POST /consolidate, POST /compact)

For long-running agent memory stores that accumulate transient working observations alongside permanent L3 pinned axioms and handbook corpora:

BASH
# Apply Ebbinghaus salience decay and prune low-salience unpinned transient records
curl -sS -X POST http://127.0.0.1:7331/consolidate \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"min_salience": 0.15}'

# Rewrite .toon shards, compact vectors.vvec, rebuild graph.vhnsw, and truncate index.wal
curl -sS -X POST http://127.0.0.1:7331/compact \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}'

Backup, Export & Disaster Recovery

  1. Consistent Hot Snapshot Prep: Run POST /compact first so all pending index.wal mutations are checkpointed into index.idx, vectors.vvec, graph.vhnsw, and compacted .toon shards.
  2. Cold Archive Copy: Stop serve_memory cleanly (SIGTERM), archive the store directory (tar -czf vkbm-store-$(date +%F).tar.gz ./data/compliance_prod), and record its SHA-256 digest.
  3. Portable Markdown Audit Export: For human-readable archival independent of binary indices, run build_export to generate exports/<corpus>.md with full YAML frontmatter and printed-page markers.

Operations & Use Cases — Production Integration Playbooks

This guide presents four concrete operational playbooks showing how banking compliance teams, corporate legal departments, security operations centers (vsight), and autonomous AI agent pipelines deploy vkbm in production.


Use Case 1: Regulatory Handbook Q&A with vllm (Zero-Hallucination RAG)

Scenario

Bank examiners and risk officers need answers across 58 OCC Comptroller's Handbook and FFIEC IT Examination booklets (4,768 pages, 11,387 passages) running on an internal air-gapped workstation paired with vllm. Every claim must cite the exact booklet, Roman-numeral section, and printed page number.

Operational Workflow

  1. Start serve_memory pointed at the local vllm OpenAI server:
BASH
export VKBM_LLM_URL="http://127.0.0.1:8000/v1/chat/completions"
export VKBM_LLM_MODEL="Qwen2.5-32B-Instruct-AWQ"
export VKBM_AUTH_TOKEN="exam-workstation-local-token"

./dist/bin/linux/serve_memory \
  --dir ./data/occ_ffiec_store \
  --host 127.0.0.1 \
  --port 7331 \
  --dim 256 \
  --quantize-int8 \
  --budget 700 \
  --require-auth
  1. Execute a 2-Turn Coarse-to-Fine Grounded Query (POST /ask):
BASH
curl -sS -X POST http://127.0.0.1:7331/ask \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are management responsibilities for testing disaster recovery resumption targets and documenting exceptions to credit underwriting policy?",
    "budget": 700,
    "auto_zoom": true,
    "verify": true
  }'
  1. Resulting Grounded Payload:
    • Turn 1 loads L3 booklet nodes and L2 section centroids across FFIEC Business Continuity Management and OCC Commercial Loans, automatically expanding resumption targets <-> RPO/RTO via #syn_rpo_rto.
    • Turn 2 executes zoom_in into FFIEC-BCM §IV.B and OCC-CLS §II.B.1, injecting compact TOON-LD @graph rows (~470 tokens instead of 2,400+ tokens of raw chunks).
    • Before returning, vkbm runs its deterministic span verifier over every citation emitted by vllm and attaches per-citation VERIFIED_EXACT status badges.

Scenario

Procurement and legal counsel receive a 35-page Cloud Core Banking Master Services Agreement (MSA) from a critical SaaS provider. Before redlining, counsel needs an automated clause-by-clause gap report against OCC Bulletin 2023-17, 12 CFR Part 30, and FFIEC Information Security baselines.

Operational Workflow

Submit the vendor contract directly to POST /audit_contract:

BASH
curl -sS -X POST http://127.0.0.1:7331/audit_contract \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_name": "ApexCore Cloud Banking MSA (Draft 2026-11)",
    "top_k": 3,
    "contract_text": "Section 4.1 Encryption. Provider shall encrypt Customer data in transit using TLS 1.3 and at rest using AES-256, with Customer retaining logical key revocation rights.\n\nSection 7.2 Audit Scope. Customer audit rights are limited to reviewing Provider self-attested security whitepaper once every twenty-four months; on-site or regulator-led examinations are excluded.\n\nSection 9.4 Subprocessing. Provider may delegate data processing to offshore fourth-party subcontractors without prior notice to Customer."
  }'

Example Structured Audit Response

JSON
{
  "contract_name": "ApexCore Cloud Banking MSA (Draft 2026-11)",
  "clauses_evaluated": 3,
  "summary": {
    "matched": 1,
    "partial_review": 1,
    "gap_alert": 1
  },
  "clauses": [
    {
      "clause_index": 1,
      "heading": "Section 4.1 Encryption",
      "modality": "mandatory",
      "status": "MATCHED",
      "top_score": 0.84,
      "citations": [
        {
          "node_id": "n_19",
          "doc_id": "ffiec-infosec",
          "section_id": "II.C.7",
          "printed_page": "34"
        }
      ]
    },
    {
      "clause_index": 2,
      "heading": "Section 7.2 Audit Scope",
      "modality": "prohibition",
      "status": "GAP_ALERT",
      "top_score": 0.31,
      "notes": "Negation/exclusion detected ('excluded') against mandatory supervisory audit right baseline.",
      "citations": [
        {
          "node_id": "n_8",
          "doc_id": "occ-2023-17",
          "section_id": "III.C.2",
          "printed_page": "27"
        }
      ]
    },
    {
      "clause_index": 3,
      "heading": "Section 9.4 Subprocessing",
      "modality": "permission",
      "status": "PARTIAL_REVIEW",
      "top_score": 0.49,
      "citations": [
        {
          "node_id": "n_12",
          "doc_id": "occ-2023-17",
          "section_id": "III.C.5",
          "printed_page": "31"
        }
      ]
    }
  ]
}

Use Case 3: SOC Runbook & Incident Grounding with vsight

Scenario

During an active security incident surfaced in vsight (for example, anomalous credential egress from a payment gateway host), Tier-2 SOC responders need immediate, citation-verified containment steps from internal Incident Response Runbooks alongside mandatory 36-hour / 72-hour regulatory notification thresholds.

Operational Workflow

  1. Ingest internal Markdown/text SOC playbooks using "strategy": "generic_structured" alongside federal notification rules ("strategy": "federal_regulation"):
BASH
curl -sS -X POST http://127.0.0.1:7331/ingest_document \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_id": "soc-ir-04",
    "document": "SOC Playbook IR-04 Credential Compromise & Token Revocation",
    "strategy": "generic_structured",
    "salience": 0.95,
    "raw_text": "## 1. Immediate Containment (0-15 Minutes)\nPage 1\nIsolate affected host via EDR network quarantine, revoke active OIDC refresh tokens, and rotate vault transit keys.\n\n## 2. Regulatory Escalation Thresholds\nPage 2\nIf unauthorized access affects core payment settlement or customer NPI, escalate to General Counsel within 2 hours to evaluate the 36-hour federal banking agency computer-security incident notification rule (12 CFR Part 53)."
  }'
  1. When vsight triggers an alert webhook, query POST /recall with budget: 450 to attach exact runbook steps and regulatory escalation citations directly into the incident ticket in < 1 ms.

Use Case 4: Autonomous Agent Grounding via Model Context Protocol (MCP)

Scenario

An autonomous compliance engineering agent needs structured tool access to inspect store statistics, recall coarse hierarchy, zoom into specific regulatory sections, and self-verify citations before opening a pull request or compliance report.

JSON-RPC 2.0 Tool Invocation Sequence (POST /mcp)

1. Discover Available Grounded Tools (tools/list)

BASH
curl -sS -X POST http://127.0.0.1:7331/mcp \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 101,
    "method": "tools/list",
    "params": {}
  }'

2. Recall Coarse Hierarchy & Zoom Into Exact Rules (vkbm_recall -> vkbm_zoom_in)

BASH
curl -sS -X POST http://127.0.0.1:7331/mcp \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 102,
    "method": "tools/call",
    "params": {
      "name": "vkbm_zoom_in",
      "arguments": {
        "node_id": "n_3",
        "budget": 600
      }
    }
  }'

3. Self-Audit Draft Citations Before Final Output (vkbm_verify_citations)

BASH
curl -sS -X POST http://127.0.0.1:7331/mcp \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 103,
    "method": "tools/call",
    "params": {
      "name": "vkbm_verify_citations",
      "arguments": {
        "citations": [
          {
            "node_id": "n_8",
            "doc_id": "occ-2023-17",
            "section_id": "III.C.2",
            "printed_page": "27",
            "quoted_span": "Contracts for critical activities must stipulate the banking organization right to audit"
          }
        ]
      }
    }
  }'

Configuration & CLI Reference

This reference documents every command-line binary, runtime flag, environment variable, corpus configuration schema, .toon synset grammar, HTTP REST endpoint, OpenAI proxy endpoint, and Model Context Protocol (MCP) JSON-RPC 2.0 tool in vkbm.


1. Command-Line Binaries

vkbm — Unified Associative Memory Walkthrough

Runs an isolated temporary store walkthrough (VVEC v2 initialization, L3 axiom pinning, 4-layer handbook ingestion, Truncated SVD subspace fitting, TOON-LD recall, and zoom_in / zoom_out WorkingSet transitions).

BASH
vkbm

build_index — Structural PDF & TOC Indexer

Extracts pages via Poppler pdftotext -layout (direct argument vector execution, zero shell), runs the 2-pass Roman/decimal TOC parser and 2-regime printed-page footer state machine, and writes <corpus>_index.json.

Flag Short Default Description
--corpus <id> -c occ Corpus identifier resolving corpora/<id>.json.
--pdf-dir <dir> -p (from config) Override source PDF directory path.
--out <path> -o (from config) Override output <corpus>_index.json file path.
--max-pages <n> -m 0 (unlimited) Optional per-PDF page cap for rapid smoke testing.
--help -h false Display usage and exit.

build_vectors — Hybrid Lexical, Synset & Truncated SVD Vectorizer

Builds vocabulary weights, expands #syn_* domain synsets, fits Randomized Truncated SVD (LSA), and writes <corpus>_data.json.

Flag Short Default Description
--corpus <id> -c occ Corpus identifier resolving corpora/<id>.json.
--dims <k> -d 128 Number of latent Truncated SVD concept dimensions (16..512).
--power-iters <q> -q 3 Subspace power iterations for singular value separation (2..6).
--in <path> -i (from config) Override input <corpus>_index.json path.
--out <path> -o (from config) Override output <corpus>_data.json path.
--help -h false Display usage and exit.

build_page — Air-Gapped Single-File HTML Compiler

Renders <corpus>_data.json into a 100% self-contained browser search application (knowledge_base.html) with XSS-hardened single-pass JSON substitution.

Flag Short Default Description
--corpus <id> -c occ Corpus identifier resolving corpora/<id>.json.
--in <path> -i (from config) Override input <corpus>_data.json path.
--out <path> -o (from config) Override output knowledge_base.html path.
--help -h false Display usage and exit.

build_export — Citation-Carrying Markdown Volume Exporter

Reads compiled handbook pages in canonical PDF order (deduplicating shared multi-section pages) and writes exports/<corpus>.md with YAML frontmatter and <!-- page printed="N" pdf="N" --> markers.

Flag Short Default Description
--corpus <id> -c occ Corpus identifier resolving corpora/<id>.json.
--out <path> -o (from config) Override output Markdown export path.
--help -h false Display usage and exit.

verify_artifacts — Deterministic Artifact & Security Verifier

Audits <corpus>_index.json, <corpus>_data.json, knowledge_base.html, and exports/<corpus>.md for schema completeness, printed-page coverage, finite vector norms, and zero remote HTML references.

BASH
verify_artifacts --corpus occ

serve_memory — 4-Layer Associative Memory HTTP, OpenAI & MCP Daemon

Flag Default Description
--store, --dir <path> (corpus store) Persistent store directory containing vectors.vvec, graph.vhnsw, lsa.vlsa, index.idx, index.wal, and .toon shards.
--corpus <id> (optional) Corpus identifier (e.g., occ, ffiec) to open or compile into a memory store.
--config <path> (optional) Explicit corpus JSON manifest path (e.g., corpora/occ.json).
--addr <host:port> 127.0.0.1:7331 TCP listen address (127.0.0.1:7331 recommended; front with a TLS reverse proxy for remote traffic).
--build-only false Build the corpus memory store on disk and exit without starting the HTTP daemon.
--mcp-stdio false Run in headless Model Context Protocol (MCP) JSON-RPC 2.0 stdio mode for desktop agents instead of HTTP.
--llm-url <url> (env) Upstream OpenAI-compatible (/v1/chat/completions) or Ollama (/api/chat) http:// URL (use a local TLS sidecar proxy for remote HTTPS endpoints).
--llm-model <id> gpt-4o-mini Upstream LLM model identifier for grounded synthesis.
--llm-key <key> (env) Optional upstream API key (defaults to OPENAI_API_KEY environment variable).
--llm-timeout <sec> 60 Outbound LLM HTTP read/write timeout in seconds (VKBM_LLM_TIMEOUT).
--embed-url <url> "" Optional external HTTP embedding endpoint (e.g., Matryoshka nomic-embed-text).
--embed-model <name> nomic-embed-text External HTTP embedding model identifier.
--embed-alpha <f> 0.70 Hybrid blend weight $\alpha \in [0,1]$ between external neural embeddings and local LSA/synset features.
--synsets <path> "" Additional .toon synset file or directory to load on startup (bundled synsets/ auto-resolved relative to the binary).
--auth-token <tok> (env) Master Bearer/session authentication secret (prefer VKBM_AUTH_TOKEN in production).
--require-auth false Enforce server-side session authentication & RBAC across API routes. Fails closed at startup if neither --auth-token nor VKBM_AUTH_TOKEN is set.
--cors-origin <o> "" Optional explicit allowed Origin for CORS (default: same-origin only; foreign Origin headers return 403).
--allow-remote-config false Permit non-loopback http:// URLs in runtime POST /configure (default: loopback-only anti-SSRF guard).
--secure-cookies false Append ; Secure to Set-Cookie: vkbm_session=... headers (enable behind HTTPS termination; VKBM_SECURE_COOKIES=1).
--session-ttl <sec> 28800 Server-side session expiration TTL in seconds (8 hours default; VKBM_SESSION_TTL).
--audit-log false Emit structured JSON access and RBAC audit logs (ts, method, path, role, status, duration_ms) to stderr (VKBM_AUDIT_LOG=1).
--ask <query> "" Run a one-shot 2-turn coarse-to-fine RAG query + deterministic citation verification and print JSON.
--audit-contract <f> "" Run a one-shot clause-by-clause contract compliance audit against a file path or inline text and print JSON.

bench_eval — Retrieval Ablation, Token Compression & Latency Suite

Runs golden regulatory retrieval ablation, 2-turn WorkingSet token compression benchmarks, VVEC v2 cosine fidelity checks, and contract compliance clause throughput measurements.

BASH
bench_eval

2. Environment Variables

Variable Consumed By Purpose
VKBM_AUTH_TOKEN serve_memory Master Bearer secret when --auth-token is omitted on the command line (recommended over CLI flags in production).
VKBM_LLM_URL serve_memory Upstream OpenAI-compatible or Ollama http:// chat completions endpoint (e.g., http://127.0.0.1:11434/v1/chat/completions).
VKBM_LLM_MODEL serve_memory Upstream model identifier (default: gpt-4o-mini).
OPENAI_API_KEY serve_memory Optional Bearer key forwarded only to the configured upstream VKBM_LLM_URL.
VKBM_LLM_TIMEOUT serve_memory Outbound LLM HTTP read/write timeout in seconds (default: 60).
VKBM_SECURE_COOKIES serve_memory Set to 1/true to append ; Secure to session cookies behind TLS reverse proxies.
VKBM_SESSION_TTL serve_memory Server-side session TTL in seconds (default: 28800).
VKBM_AUDIT_LOG serve_memory Set to 1/true to emit structured JSON request/audit logs to stderr.
VKBM_MARCH Build Pipeline Optional Linux target CPU tuning flags (e.g., -march=x86-64-v3 -mfma); defaults to portable -O3.

3. Configuration File Schemas

Corpus Manifest (corpora/<id>.json)

JSON
{
  "id": "occ",
  "name": "OCC Comptroller's Handbook",
  "brandmark": "OCC HANDBOOK KB",
  "pdf_dir": "pdfs/occ",
  "index_json": "data/occ_index.json",
  "data_json": "data/occ_data.json",
  "page_html": "dist/occ/knowledge_base.html",
  "export_md": "exports/occ.md",
  "footer_matchers": ["occ", "page_n"],
  "header_prefixes": ["Comptroller's Handbook"],
  "examples": [
    "commercial loan underwriting exceptions",
    "third-party risk management board oversight"
  ]
}

Domain Synset Pack (synsets/*.toon)

vkbm ships three curated .toon synset packs (synsets/general.toon, synsets/banking_regulatory.toon, synsets/contracts_compliance.toon) mapping canonical #syn_* tokens to domain acronyms and paraphrases:

TEXT
# Canonical Token | Comma-Separated Equivalence Phrases
syn_rpo_rto       | recovery point objective, recovery time objective, rpo, rto, resumption targets, maximum tolerable downtime
syn_cecl          | current expected credit losses, cecl, asc 326, allowance for credit losses, acl
syn_right_audit   | right to audit, audit rights, independent examination, soc 2 type ii, supervisory access

Ingestion Strategies (POST /ingest_document)

strategy Value Target Document Structure
auto Inspects TOC leaders, Roman/CFR markers, and numbered clauses to select the best structural parser automatically.
occ_ffiec_handbook Roman-numeral & decimal supervisory handbooks (I.A.1, II.B.2) with printed-page footers.
federal_regulation CFR / statutory hierarchy (Part, Subpart, § 30.4(a), Appendix).
legal_contract Commercial agreements (Article, Section 1.1, WHEREAS, schedules, deontic clause splitting).
generic_structured Markdown (#..####) and numbered operational SOPs/runbooks.

4. HTTP REST & OpenAI API Reference (serve_memory)

Method & Path Role Scope Description
GET /health Public Liveness probe returning {"status":"ok"} and store readiness.
GET /metrics Examiner+ Prometheus/OpenMetrics text exposition (vkbm_records_live, vkbm_pager_hits_total, vkbm_http_requests_total, vkbm_auth_denials_total, vkbm_rate_limited_total, vkbm_active_connections).
GET /stats Examiner+ Returns live, tombstones, wal_ops, hnsw_nodes, hnsw_max_layer, lsa_dims, vocab_size, page_hits, page_faults, pinned_tokens.
GET /records Examiner+ Record listing filterable by tier (capped at 200 rows per response).
POST /materialize Examiner+ Fetches full TOON field payloads for a specific @id node identifier via $O(1)$ shard byte offsets.
POST /ingest Steward+ Inserts a typed record (shape, fields, values, salience, pinned, tier).
POST /ingest_document Steward+ Parses a multi-section document via strategy into linked L3 -> L2 -> L1 -> L0 nodes.
POST /recall Examiner+ Executes 4-layer HNSW + Truncated SVD + BM25 associative recall within budget (16..16384 tokens) and renders TOON-LD @graph.
POST /zoom_in Examiner+ Expands an L3 or L2 parent node into its child L2/L1/L0 records inside the WorkingSet.
POST /zoom_out Examiner+ Collapses child records back into their parent L2/L3 summary node.
POST /ask Examiner+ Runs 2-turn coarse-to-fine retrieval, calls upstream LLM (or offline synthesizer), and verifies cited spans.
POST /verify_citations Examiner+ Deterministically checks @id, doc_id, section_id, printed_page, and quoted_span against L0 shards.
POST /audit_contract Examiner+ Splits contract text into clauses, tags modalities, and classifies regulatory gaps (MATCHED, PARTIAL_REVIEW, UNMAPPED_GAP). Rate-limited; persist_contract: true requires Steward+.
POST /refit_lsa Admin Trains Randomized Truncated SVD (dims <= 512) over current corpus and re-projects all live vectors. Rate-limited.
POST /consolidate Steward+ Clusters related L1 records via L2-normalized vector centroids into L2 concept summaries.
POST /compact Admin Compacts segmented .toon shards, cleans orphaned segments, rebuilds graph.vhnsw, and checkpoints index.wal. Rate-limited.
POST /load_synsets Steward+ Hot-reloads a contained .toon/.json synset pack from the store directory or bundled synsets/ directory.
POST /configure Admin Updates runtime upstream LLM/embedder connection parameters (loopback-only unless --allow-remote-config is set).
GET /v1/models Examiner+ OpenAI-compatible model discovery endpoint (vkbm-compliance-v1, vkbm-contract-auditor).
POST /v1/chat/completions Examiner+ OpenAI-compatible chat completion proxy with automatic TOON-LD injection and citation verification.
POST /mcp Examiner+ Model Context Protocol JSON-RPC 2.0 endpoint (initialize, tools/list, tools/call). Enforces read-only RBAC for portal sessions (-32003 Forbidden on mutating tools).
POST /api/v1/auth/session Public Mints a 256-bit OS CSPRNG role-scoped session (portal, delegated, admin) and HttpOnly; SameSite=Strict cookie (requires valid auth_token when configured; rate-limited; fails closed with 503 if --require-auth has no token).
POST /api/v1/auth/logout Public Revokes the active server-side session token and expires the vkbm_session cookie (Max-Age=0).
GET /api/v1/self/profile Examiner+ Returns active session role, workspace routes, and store summary.

5. Model Context Protocol (MCP) Tool Catalog

MCP Tool Name Arguments Grounded Output
vkbm_ask question (string), budget (int, opt), auto_zoom (bool, opt) Synthesized answer + TOON-LD @graph + deterministic citation verification report.
vkbm_audit_contract contract_name (string), contract_text (string), top_k (int, opt) Clause-by-clause MATCHED / PARTIAL_REVIEW / GAP_ALERT matrix with handbook citations.
vkbm_recall query (string), budget (int, opt) Loaded node IDs, token usage, and sorted TOON-LD @graph context block.
vkbm_zoom_in node_id (string), budget (int, opt) Expanded child L1 obligations and L0 verbatim page-cited passages.
vkbm_zoom_out node_id (string) Collapsed L2/L3 parent summary and reclaimed token count.
vkbm_verify_citations citations (array of {node_id, doc_id, section_id, printed_page, quoted_span}) Per-citation VERIFIED_EXACT, VERIFIED_NORMALIZED, METADATA_MISMATCH, or UNVERIFIED_SPAN verdict.
vkbm_ingest_axiom mandate (string), scope (string), pinned (bool, opt) Newly assigned @id of the pinned L3 supervisory axiom.
vkbm_stats (none) Live store, VVEC pager hit/fault counters, LSA dimensions, and HNSW layer counts.

Performance, Retrieval Ablation & Hardware Sizing

This guide documents empirical retrieval accuracy, printed-page citation fidelity, token-budget compression ratios, VVEC v2 quantization precision, SIMD microbenchmarks, and hardware sizing envelopes measured with bench_eval and production -prod builds.


1. Empirical Retrieval Ablation (bench_eval)

Regulatory and legal queries frequently fail under naive lexical search (because examiners ask about "resumption targets" while handbooks state "recovery time objectives") and also fail under pure dense embeddings (which blur exact statutory identifiers such as 12 CFR 30.4(c) vs. 12 CFR 53.3).

bench_eval evaluates progressive retrieval stages across golden regulatory paraphrase and exact-citation query suites:

Retrieval Configuration Recall@5 Recall@10 Mean Reciprocal Rank (MRR) Key Failure Mode Eliminated
1. Lexical Okapi BM25 Only 62.5% 75.0% 0.5417 Misses cross-vocabulary regulatory paraphrases (CECL <-> allowance for credit losses).
2. BM25 + Character 3–5gram Subwords 75.0% 87.5% 0.6875 Captures morphological variants (subcontracting / subcontractors), still misses disjoint synonyms.
3. + Randomized Truncated SVD (LSA Subspace) 87.5% 100.0% 0.8333 Bridges latent co-occurrence concepts across multi-booklet corpora without external GPUs.
4. + #syn_* Domain Synsets + Rare Bigram Boost (+0.55) 100.0% 100.0% 0.9583 Locks onto exact multi-word terms of art while preserving acronym equivalence.
5. Full vkbm 4-Layer HNSW + Spreading Activation ($\gamma = 0.25$) 100.0% 100.0% 1.0000 Propagates activation from high-scoring L2 sections into normative L1 rules and L0 quotes.

2. Printed-Page Citation & Structural TOC Accuracy

Evaluated across 58 official OCC Comptroller's Handbook and FFIEC IT Examination booklets (4,768 PDF pages, 11,387 extracted passages):

Structural Metric Measured Result Engineering Mechanism
Printed-Page Footer Attribution Accuracy 98.5% 2-regime footer state machine handling Roman-numeral front matter (i..xii), booklet-prefixed footers (FFIEC IT Examination Handbook), and monotonic gap interpolation.
Multi-Line TOC Hierarchy Resolution 99.1% 2-pass lookahead Roman/letter/decimal parser (I -> A -> 1 -> a) with dot-leader stripping and running-header suppression.
Verbatim Quote Verification Precision 100.0% deterministic Exact and whitespace-normalized substring span check directly against immutable L0 .toon shards (0% false-positive hallucinated quotes).

3. Prompt Token Compression vs. Naive Flat Chunk RAG

Conventional RAG retrieves top-$K$ (K = 10..20) fixed-size 512-token chunks, injecting 5,000–10,000 tokens of repetitive boilerplate per turn. vkbm combines 2-Turn Coarse-to-Fine WorkingSet Zoom with compact TOON-LD @graph tabular serialization:

Retrieval Strategy Avg. Context Tokens / Query Relative Token Cost Structural Lineage Preserved?
Flat Top-12 Chunk RAG (JSON array) 2,480 tokens 1.00x (baseline) No (orphaned text slices)
Flat Top-12 Passages (TOON-LD tabular) 1,590 tokens 0.64x (-35.9%) Partial (metadata columns deduplicated)
vkbm 2-Turn L3/L2 -> Selective zoom_in(L1/L0) 473 – 955 tokens 0.19x – 0.38x (61.4% – 80.9% reduction) Yes (L3 -> L2 -> L1 -> L0 + pinned axioms)

4. VVEC v2 Quantization Fidelity & Latency Microbenchmarks

Measured on a standard x86-64 workstation (-prod optimized native binary, single-core latency and warm serve_memory daemon throughput):

Operation / Subsystem VVEC v1 (f32) VVEC v2 (int8 + f32 scale) Notes
On-Disk Bytes per 256-D Vector 1,024 B (4 vecs / 4 KB page) 260 B (15 vecs / 4 KB page) 3.85x higher cache density per 4 KB VectorPager frame
On-Disk Bytes per 128-D Vector 512 B (8 vecs / 4 KB page) 132 B (31 vecs / 4 KB page) 3.88x higher cache density
Pairwise Cosine Similarity Fidelity 1.00000 (exact) 0.9991 mean (> 0.995 p99) Zero measurable degradation in Recall@5 or MRR
256-D SIMD Dot Product 68.5 ns 54.2 ns Unrolled auto-vectorized FMA / integer accumulation (146x faster than unoptimized debug builds)
Single-Pass WorkingSet zoom_in (L2 -> L1/L0) 0.19 ms 0.18 ms $O(1)$ .toon shard byte-offset seeks
4-Layer Associative Recall (18K nodes) 0.42 ms 0.31 ms Includes #syn_* expansion, HNSW search, and TOON-LD rendering
4-Layer Associative Recall (150K nodes) 0.85 ms 0.58 ms Warm 8.0 MB VectorPager cache
Contract Gap Audit (POST /audit_contract) 2.4 ms / clause 2.1 ms / clause ~84 ms total for a 40-clause vendor MSA
Randomized Truncated SVD Fit (12K passages, k=64) 410 ms 410 ms Pure-CPU Halko–Martinsson–Tropp (q=3 power iterations)
Warm serve_memory /recall Throughput 1,450 QPS 2,180 QPS Loopback HTTP keep-alive

5. Hardware & Store Sizing Reference

Because VectorPager bounds resident vector pages (--max-pages, default 2,048 pages = 8.0 MB) and .toon text records stream on demand via byte-offset seeks, vkbm runs predictably from constrained edge VMs to multi-million-passage enterprise servers:

Corpus Scale Example Workload VVEC v2 (256-D) Disk .toon + HNSW Disk Recommended --max-pages Daemon Steady-State RAM
Small (18,000 nodes) 60 regulatory handbooks (~5,000 pages) 4.8 MB ~22 MB 2,048 (8 MB cache) ~38 MB
Medium (150,000 nodes) 500 handbooks + 1,000 vendor contracts 39 MB ~185 MB 8,192 (32 MB cache) ~115 MB
Large (1,000,000 nodes) Enterprise policy lake + multi-year legal archive 260 MB ~1.2 GB 32,768 (128 MB cache) ~540 MB
XL (5,000,000 nodes) National regulatory + technical library 1.30 GB ~6.1 GB 65,536 (256 MB cache) ~1.9 GB

Reproducing Benchmarks Locally

Run the deterministic benchmark binary from your compiled release directory at any time:

POWERSHELL
# Windows
.\dist\bin\windows\bench_eval.exe
BASH
# Linux
./dist/bin/linux/bench_eval

vkbm — Consolidated End-User, Administrator & Operations Handbook

vkbm — Citation-Grounded Knowledge Base & 4-Layer Associative Memory Engine


Part I: vkbm — Citation-Grounded 4-Level Knowledge Base & Associative Memory Engine

vkbm is a high-assurance, zero-dependency 4-Level Hierarchical Knowledge Base (Book -> Section -> Rule -> Quote) and Hybrid Truncated-SVD + BM25 Associative Memory Engine. It compiles unstructured and structured regulatory handbooks, compliance policies, legal contracts, and operational runbooks into an out-of-core paged vector graph with word-for-word printed-page citation verification, clause-by-clause contract gap analysis, and built-in OpenAI (/v1/chat/completions) & Model Context Protocol (POST /mcp, --mcp-stdio) agent endpoints.


Core Capabilities

Capability Operational Mechanics Key Guarantee
4-Level Hierarchical Knowledge Graph (L3..L0) Compiles documents into a 4-tier Associative HNSW pyramid: L3 Booklet & Pinned Supervisory Axioms -> L2 Table-of-Contents Sections -> L1 Multi-Sentence Normative Rules & Deontic Modalities -> L0 Verbatim Page-Cited Quotes. Structural context and parent-child lineage are preserved across every retrieval turn.
Hybrid Truncated SVD + BM25 Associative Recall Combines corpus-adaptive Randomized Truncated SVD (LSA latent subspace), 650+ domain #syn_* synset expansions, signed character 3–5gram subwords, Okapi BM25 lexical scoring, +0.55 rare-bigram phrase boost, and HNSW spreading activation. Recalls exact regulatory terms (12 CFR 30, CECL) and cross-vocabulary paraphrases (RPO/RTO <-> resumption targets).
Out-of-Core 4 KB Binary Vector Pager (VVEC v2) Pages int8 symmetric quantized vectors (260 B @ 256-D, 132 B @ 128-D) through a bounded 4 KB binary page cache (8.0 MB default RAM budget) backed by a crash-safe write-ahead log (index.wal) and atomic index snapshots (index.idx). Scales from 18,000 handbook nodes to multi-million-passage corpora within a fixed memory envelope.
2-Turn Coarse-to-Fine WorkingSet Zoom Loads compact L3/L2 summaries on Turn 1, identifies the highest-relevance sections, and executes zoom_in(L2 -> L1/L0) via $O(1)$ shard byte-offset seeks on Turn 2, rendering sorted TOON-LD @graph tables. Cuts LLM prompt token consumption by 61.4%–80% compared to flat top-$K$ chunk retrieval.
Deterministic Word-for-Word Citation Verifier Audits structured citations (@id, doc_id, section_id, printed_page, quoted_span) directly against L0 passage shards using exact and whitespace-normalized substring matching. Eliminates fabricated section references, wrong page numbers, and paraphrased quotes masquerading as verbatim text.
Clause-by-Clause Contract Gap Auditor Splits vendor agreements (MSAs, cloud schedules, SLAs) into normative clauses, tags deontic modalities (mandatory, prohibition, supervisory, commitment, permission), and classifies coverage as MATCHED, PARTIAL_REVIEW, or GAP_ALERT. Evaluates a 40-clause contract in under 90 ms without requiring external GPU infrastructure.
OpenAI Proxy, MCP Server & Role-Separated Web Studio Serves 22 REST endpoints, an OpenAI-compatible /v1/chat/completions proxy, an 8-tool JSON-RPC 2.0 MCP server (POST /mcp & --mcp-stdio), and a 4-portal browser workspace (/ui/auth, /ui/portal, /ui/delegated, /ui/admin). Drop-in memory plane for human examiners, vllm inference gateways, vsight SOC analysts, and autonomous MCP agents.

Live Interactive Studio Preview

Examiner Associative Recall & TOON-LD @graph Inspector

vkbm Examiner Portal — 4-Layer Associative Recall, Token Budget Telemetry, and TOON-LD Graph Output

Clause-by-Clause Contract Gap Audit

vkbm Examiner Portal — Vendor MSA Clause-by-Clause Compliance Audit with Modality Tags and Page Citations


End-to-End Pipeline & Daemon Binaries

vkbm ships a unified walkthrough executable alongside specialized, composable CLI binaries for deterministic offline corpus compilation and online associative memory serving:

Binary Primary Purpose Typical Output / Interface
vkbm Self-contained walkthrough demonstrating VVEC v2 initialization, L3 axiom pinning, 4-layer handbook ingestion, Truncated SVD fitting, TOON-LD recall, and zoom_in / zoom_out navigation. Console telemetry & TOON-LD @graph output
build_index Extracts PDF pages (pdftotext -layout), resolves 2-pass TOC sections and 2-regime printed-page footers, and emits normalized passage indices. <corpus>_index.json
build_vectors Tokenizes passages with legal-negation preservation and domain synsets, fits Randomized Truncated SVD (LSA), and computes concept vectors. <corpus>_data.json
build_page Bundles <corpus>_data.json into a 100% offline, single-file browser search portal with zero remote asset dependencies. knowledge_base.html
build_export Exports citation-carrying consolidated Markdown volumes with <!-- page printed="N" pdf="N" --> provenance markers. exports/<corpus>.md
verify_artifacts Cryptographically and structurally audits compiled indices, vector dimensions, page coverage, and zero-remote-reference HTML invariants. Exit code 0 on full pass
serve_memory Runs the stateful 4-layer associative memory HTTP daemon, Web Studio, OpenAI /v1/chat/completions proxy, and MCP JSON-RPC 2.0 server. http://127.0.0.1:7331 or --mcp-stdio
bench_eval Executes deterministic retrieval ablation (Recall@5, MRR), token-budget compression, VVEC v2 quantization fidelity, and contract gap audit benchmarks. Benchmark scorecard

5-Minute Quickstart

1. Run the Self-Contained Associative Memory Walkthrough

Execute the vkbm binary to verify local VVEC v2 quantized paging, 4-layer HNSW graph construction, pure-CPU Truncated SVD fitting, and WorkingSet zoom:

POWERSHELL
# Windows
.\dist\bin\windows\vkbm.exe
BASH
# Linux
./dist/bin/linux/vkbm

2. Compile an Offline Citation-Grounded Corpus

Compile a structured PDF corpus (such as corpora/occ.json or corpora/ffiec.json) through the 5-stage deterministic pipeline:

BASH
./dist/bin/linux/build_index --corpus occ
./dist/bin/linux/build_vectors --corpus occ --dims 128
./dist/bin/linux/build_page --corpus occ
./dist/bin/linux/build_export --corpus occ
./dist/bin/linux/verify_artifacts --corpus occ

3. Launch the serve_memory Daemon, Web Studio & Agent Server

Start the persistent associative memory engine with int8 VVEC v2 quantization and 256-D hybrid vectors:

BASH
./dist/bin/linux/serve_memory \
  --dir ./.vstore/regulatory_kb \
  --host 127.0.0.1 \
  --port 7331 \
  --dim 256 \
  --quantize-int8 \
  --budget 600

Once running on http://127.0.0.1:7331:

  • Interactive Web Studio: Open http://127.0.0.1:7331/ui/auth to launch Examiner, Corpus Steward, or Global Admin sessions.
  • Associative Recall API: POST http://127.0.0.1:7331/recall
  • Contract Gap Audit API: POST http://127.0.0.1:7331/audit_contract
  • Citation Span Verifier API: POST http://127.0.0.1:7331/verify_citations
  • OpenAI Chat Proxy: POST http://127.0.0.1:7331/v1/chat/completions
  • MCP Tool Endpoint: POST http://127.0.0.1:7331/mcp

Documentation Navigation

  • How-To Guide — Step-by-step recipes for ingesting PDFs and handbooks, fitting Truncated SVD subspaces, launching OpenAI/MCP servers, and auditing contracts.
  • End-User Guide — Interactive Web Studio walkthroughs, 2-turn coarse-to-fine recall, WorkingSet zoom controls, and citation anchor inspection.
  • Administrator Guide — Store lifecycle governance, verify_artifacts validation, air-gapped deployment, Bearer authentication, and shard compaction.
  • Operations & Use Cases — Production workflows with vllm, vendor MSA gap checks, vsight SOC runbook grounding, and autonomous MCP tool calls.
  • Configuration & CLI Reference — Complete CLI flags, environment variables, corpora/*.json and .toon synset schemas, HTTP endpoints, and MCP tool specifications.
  • Performance & Sizing — Empirical retrieval ablation, 98.5% printed-page accuracy across 58 booklets, token-efficiency benchmarks, and hardware sizing tables.

Part II: How-To Guide — Step-by-Step Operational Recipes

This guide provides copy-pasteable operational recipes for compiling PDF and Markdown corpora into 4-level hierarchical knowledge graphs, building hybrid BM25 + Truncated SVD indices, launching the serve_memory OpenAI and MCP server, auditing contracts for regulatory gaps, and verifying verbatim page citations.


Recipe 1: Ingest PDF Handbooks into a Deterministic Offline Corpus

Use the 5-stage offline compiler when publishing immutable handbook distributions (such as OCC Comptroller's Handbooks, FFIEC IT Examination Booklets, or internal SOP manuals) with a standalone knowledge_base.html explorer and citation-preserving Markdown export.

Prerequisites

Ensure Poppler pdftotext (>= 22.x) is installed on your PATH so build_index can extract layout-preserving page columns without invoking a system shell:

BASH
pdftotext -v

Step 1: Define the Corpus Manifest (corpora/my_policy.json)

Create a JSON configuration file inside corpora/ describing your PDF directory, header/footer rules, and curated starter queries:

JSON
{
  "id": "my_policy",
  "name": "Enterprise Cloud & Vendor Risk Standards",
  "brandmark": "ENTERPRISE RISK KB",
  "pdf_dir": "pdfs/my_policy",
  "index_json": "data/my_policy_index.json",
  "data_json": "data/my_policy_data.json",
  "page_html": "dist/my_policy/knowledge_base.html",
  "export_md": "exports/my_policy.md",
  "footer_matchers": ["occ", "ffiec", "page_n"],
  "header_prefixes": [
    "Comptroller's Handbook",
    "FFIEC IT Examination Handbook",
    "Enterprise Security Policy"
  ],
  "examples": [
    "board oversight of critical cloud service providers",
    "encryption key custody and incident notification timelines",
    "annual disaster recovery failover testing RPO RTO"
  ]
}

Step 2: Run the 5-Stage Compiler & Verifier

BASH
# 1. Parse PDFs, resolve 2-pass Roman/decimal TOC hierarchy, and map printed-page footers
./dist/bin/linux/build_index --corpus my_policy

# 2. Build hybrid vocabulary, expand domain synsets, and fit Randomized Truncated SVD (128-D)
./dist/bin/linux/build_vectors --corpus my_policy --dims 128

# 3. Compile 100% self-contained single-file HTML explorer (zero remote URLs)
./dist/bin/linux/build_page --corpus my_policy

# 4. Export consolidated Markdown with <!-- page printed="N" pdf="N" --> citations
./dist/bin/linux/build_export --corpus my_policy

# 5. Verify index integrity, vector norms, page coverage, and HTML security invariants
./dist/bin/linux/verify_artifacts --corpus my_policy

Recipe 2: Launch serve_memory and Seed a 4-Level Associative Store

For dynamic multi-document ingestion, live associative recall, contract gap audits, and LLM/MCP agent grounding, run serve_memory.

Step 1: Start the Daemon

BASH
./dist/bin/linux/serve_memory \
  --dir ./.vstore/compliance_prod \
  --host 127.0.0.1 \
  --port 7331 \
  --dim 256 \
  --quantize-int8 \
  --budget 650 \
  --auth-token "${VKBM_AUTH_TOKEN}" \
  --require-auth

Step 2: Sign In via the Role-Separated Authentication Gate

Navigate to http://127.0.0.1:7331/ui/auth to establish a scoped session (Examiner / Compliance Analyst, Corpus Steward, or Global Memory Admin) and inspect live header telemetry (Live Nodes, HNSW, LSA Dims, VVEC Hits).

vkbm Role-Separated Authentication Gate & Session Provisioning

Step 3: Pin a Tier-3 (L3) Supervisory Axiom

Pinned L3 axioms reserve dedicated capacity inside every WorkingSet so non-negotiable institutional mandates are never evicted during retrieval:

BASH
curl -sS -X POST http://127.0.0.1:7331/ingest \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "shape": "axiom",
    "pinned": true,
    "salience": 0.99,
    "fields": ["mandate", "authority", "rule"],
    "values": {
      "mandate": "Third-Party Critical Activity Governance",
      "authority": "OCC Bulletin 2023-17 / 12 CFR Part 30",
      "rule": "Every critical vendor engagement must preserve audit rights, subcontractors disclosure, encryption custody, and 72-hour cyber incident notice."
    }
  }'

Step 4: Ingest Structured Documents via Strategy-Driven Parsing

Use /ui/delegated (Corpus Steward Portal) or POST /ingest_document to compile handbooks, regulations, or contracts directly into L3 -> L2 -> L1 -> L0 nodes.

vkbm Corpus Steward Portal — Multi-Strategy Document Ingestion

BASH
curl -sS -X POST http://127.0.0.1:7331/ingest_document \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_id": "occ-2023-17",
    "document": "OCC Bulletin 2023-17 Third-Party Relationships",
    "strategy": "occ_ffiec_handbook",
    "salience": 0.92,
    "raw_text": "I. Governance and Risk Management\nPage 8\nA banking organization should adopt risk management practices commensurate with the level of risk and complexity of its third-party relationships.\n\nIII.C.2 Right to Audit and Remediation\nPage 27\nContracts for critical activities must stipulate the banking organization right to audit, review independent SOC 2 Type II reports, and enforce timely remediation."
  }'

Step 5: Fit the Corpus-Adaptive Truncated SVD (LSA) Subspace

After ingesting or updating documents, refit the pure-CPU Randomized Truncated SVD model so every L3..L0 node is re-projected into the learned latent subspace:

BASH
curl -sS -X POST http://127.0.0.1:7331/refit_lsa \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"dims": 64}'

Recipe 3: Connect OpenAI Clients & Autonomous MCP Agents

Option A: OpenAI-Compatible /v1/chat/completions Proxy

Configure serve_memory with an upstream OpenAI-compatible inference server (such as local vllm, llama-server, or an enterprise gateway) via environment variables:

BASH
export VKBM_LLM_URL="http://127.0.0.1:8000/v1/chat/completions"
export VKBM_LLM_MODEL="Qwen2.5-14B-Instruct"

Any standard OpenAI SDK or HTTP client can now query http://127.0.0.1:7331/v1/chat/completions. vkbm intercepts the user prompt, executes 2-turn coarse-to-fine associative recall + zoom_in, injects the verified TOON-LD @graph context, calls the upstream model, and runs deterministic citation verification before returning the response:

BASH
curl -sS -X POST http://127.0.0.1:7331/v1/chat/completions \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vkbm-grounded",
    "messages": [
      {
        "role": "user",
        "content": "What contractual audit rights are required for critical cloud vendors under OCC 2023-17?"
      }
    ],
    "temperature": 0.1
  }'

Option B: Model Context Protocol (POST /mcp or --mcp-stdio)

For desktop coding assistants, compliance copilots, or autonomous orchestrators, expose the 8 grounded memory tools over JSON-RPC 2.0:

JSON
{
  "mcpServers": {
    "vkbm": {
      "command": "./bin/serve_memory",
      "args": [
        "--dir", "./data/compliance_prod",
        "--dim", "256",
        "--quantize-int8",
        "--mcp-stdio"
      ]
    }
  }
}

Or invoke POST /mcp directly over HTTP:

BASH
curl -sS -X POST http://127.0.0.1:7331/mcp \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "vkbm_recall",
      "arguments": {
        "query": "RPO RTO disaster recovery failover exercises",
        "budget": 500
      }
    }
  }'

Recipe 4: Run Automated Contract Gap Analysis & Quote Verification

Step 1: Audit Draft Contract Text Against Regulatory Baselines

Submit draft agreement clauses to POST /audit_contract to classify every normative obligation (MATCHED, PARTIAL_REVIEW, or GAP_ALERT) with exact handbook citations:

BASH
curl -sS -X POST http://127.0.0.1:7331/audit_contract \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_name": "Core Ledger Cloud Hosting MSA v3",
    "contract_text": "1. Audit Rights. Customer may review Provider annual SOC 2 Type II summary report upon written request, and regulatory agencies may examine critical operations.\n\n2. Subcontractors. Provider may engage fourth-party subcontractors at its sole discretion without prior customer notification.\n\n3. Incident Reporting. Provider shall notify Customer within 24 hours of confirming any unauthorized access to Customer NPI.",
    "top_k": 3
  }'

Step 2: Verify Every Quoted Span Word-for-Word (POST /verify_citations)

Before publishing an AI-authored compliance memo, pass its structured citations to /verify_citations to confirm that every @id, doc_id, section_id, printed_page, and quoted_span matches the L0 shard byte-for-byte:

BASH
curl -sS -X POST http://127.0.0.1:7331/verify_citations \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "citations": [
      {
        "node_id": "n_8",
        "doc_id": "occ-2023-17",
        "section_id": "III.C.2",
        "printed_page": "27",
        "quoted_span": "Contracts for critical activities must stipulate the banking organization right to audit"
      }
    ]
  }'

Part III: End-User Guide — Search, WorkingSet Zoom & Citation Workflows

This guide explains how compliance examiners, legal reviewers, security analysts, and technical researchers use vkbm to search multi-handbook corpora, navigate the 4-level hierarchy (Book -> Section -> Rule -> Quote), inspect confidence and printed-page anchors, and audit legal contracts.


Understanding the 4-Level Knowledge Hierarchy

Every document compiled into vkbm is structured as a 4-tier pyramid rather than disconnected flat chunks:

Tier Graph Node Type What It Represents How Examiners Use It
L3 (tier = 3) Booklet / Document & Pinned Axioms Top-level handbook identity (e.g., OCC Bulletin 2023-17) plus pinned supervisory mandates (pinned = true). Anchors high-level regulatory scope and keeps non-negotiable rules permanently resident in WorkingSet memory.
L2 (tier = 2) Section Centroid Authoritative Table-of-Contents section (e.g., §III.C.2 — Right to Audit and Remediation) with an L2-normalized salience-weighted concept vector. Provides fast, low-token structural orientation on Turn 1 before drilling down into verbatim clauses.
L1 (tier = 1) Normative Rule / Obligation Multi-sentence regulatory mandate, prohibition, or contractual commitment tagged with deontic modality (mandatory, prohibition, supervisory, commitment, permission). Maps individual contract clauses directly against enforceable regulatory obligations.
L0 (tier = 0) Verbatim Page-Cited Quote Exact passage text stored in 64 MB .toon shards with immutable {doc_id, section_id, printed_page, page_index} provenance. Supplies court- and exam-ready verbatim quotations verified word-for-word against the source page.

Signing In & Role-Scoped Workspaces

Open http://127.0.0.1:7331/ui/auth in any modern desktop browser. vkbm separates daily analytical lookup from corpus mutation and store administration across three workspaces:

  1. Examiner / Compliance Analyst (/ui/portal) — Read-only access to Associative Recall (/recall), 2-Turn Cited Q&A (/ask), Contract Gap Audit (/audit_contract), Citation Verification (/verify_citations), and the CentralIndex Record Browser.
  2. Corpus Steward (/ui/delegated) — Scoped privileges to ingest structured handbooks, regulations, and runbooks (/ingest_document), pin supervisory axioms (/ingest), and load .toon synset packs.
  3. Global Memory Administrator (/ui/admin) — Full store governance including Randomized Truncated SVD refitting (/refit_lsa), Ebbinghaus consolidation (/consolidate), WAL/shard compaction (/compact), runtime vector tuning, and live MCP JSON-RPC inspection.

Workflow 1: Associative Recall & TOON-LD @graph Inspection

In the Examiner Portal (/ui/portal), select the Associative Recall & WorkingSet workspace:

  1. Enter a natural-language query, acronym, or exact citation phrase (for example, board oversight critical vendor audit rights subcontractor cyber incident notification).
  2. Set your Token Budget (default 500–650 tokens). vkbm automatically reserves space for pinned L3 axioms first, then loads the highest-scoring L2/L1/L0 nodes via 4-layer HNSW traversal, #syn_* synset expansion, and spreading activation (gamma = 0.25).
  3. Inspect the TOON-LD @graph Context Pane and Record Browser:
    • Records are grouped deterministically by shape (axiom, booklet, section, obligation, passage) and sorted by @id.
    • Every L0 passage displays its doc_id, section_id, printed_page (the page number printed in the document footer), and page_index (the 1-based physical PDF page).

vkbm Examiner Portal — Associative Recall, Token Telemetry, and CentralIndex Record Browser


Workflow 2: 2-Turn Coarse-to-Fine Cited Q&A & WorkingSet Zoom

When answering complex multi-section regulatory questions, flat RAG systems waste thousands of tokens loading full passages from marginally relevant chapters. vkbm uses 2-Turn Coarse-to-Fine Synthesis:

  • Turn 1 (Coarse Orientation): vkbm retrieves compact L3 booklet headers and L2 TOC section summaries across the entire store.
  • Turn 2 (Selective zoom_in): vkbm identifies the highest-scoring L2 section nodes and calls zoom_in, swapping out the coarse summary for its exact L1 obligations and L0 verbatim quotes via $O(1)$ shard byte-offset seeks.

vkbm Examiner Portal — 2-Turn Coarse-to-Fine RAG Synthesis, Verified Citations, and WorkingSet Zoom

Interactive zoom_in and zoom_out Controls

You can also drive coarse-to-fine navigation manually from the UI or HTTP API:

  • zoom_in (POST /zoom_in): Expands an L3 booklet into its L2 sections, or expands an L2 section (such as n_3 -> OCC-2023-17 §III.C.2) into its child L1 rules and L0 verbatim quotes.
  • zoom_out (POST /zoom_out): Collapses child L1/L0 nodes back into their parent L2 summary, freeing WorkingSet token budget for exploring another handbook chapter.

Workflow 3: Clause-by-Clause Contract Compliance Auditing

Use the Contract Compliance Audit tab in /ui/portal to screen draft vendor agreements, cloud addenda, or internal policies against your loaded regulatory corpora:

  1. Paste the draft agreement text and assign a descriptive document title.
  2. Click Run Clause Audit. vkbm segments the agreement into discrete clauses, classifies each clause's deontic modality (mandatory, prohibition, supervisory, commitment, permission), and preserves legal negations (not, no, never, without, neither, nor).
  3. Review the per-clause disposition cards:
    • MATCHED: Strong semantic and lexical alignment with authoritative L1/L0 regulatory rules, accompanied by exact section and printed-page citations.
    • PARTIAL_REVIEW: Moderate overlap or scope divergence (for example, right-to-audit restricted solely to vendor-authored executive summaries or fourth-party subcontracting lacking prior notice).
    • GAP_ALERT: No supporting regulatory alignment or direct contradiction with a mandatory obligation—requires legal redlining before execution.

vkbm Examiner Portal — Clause-by-Clause Contract Gap Audit


Workflow 4: Offline Single-File Explorer (knowledge_base.html)

When operating on air-gapped examination laptops without running a local HTTP daemon, open the compiled knowledge_base.html file directly from disk (./dist/knowledge_base.html):

  • 100% Self-Contained: All CSS, JavaScript, Truncated SVD projection matrices, and passage records are embedded inside the single HTML file with zero external fonts, scripts, or network calls.
  • Instant Hybrid Filtering: Type regulatory terms or click curated starter chips to rank passages across booklets, filter by handbook title or TOC section, and copy pre-formatted citations (Document, Section §X.Y, p. N) to your clipboard.

Part IV: Administrator Guide — Corpus Governance, Security & Operations

This guide covers day-2 operational administration of vkbm: persistent store anatomy, deterministic artifact verification, air-gapped deployment, Bearer authentication and SSRF controls, Truncated SVD subspace maintenance, WAL recovery, shard compaction, and backup/restore procedures.


Global Administrator Console (/ui/admin)

Administrators manage store health, vector subspace refitting, Ebbinghaus memory consolidation, shard compaction, and live MCP JSON-RPC 2.0 tool inspection from the dark-mode Global Administrator Console at http://127.0.0.1:7331/ui/admin.

vkbm Global Administrator Console — Store Telemetry, Subspace Controls, and Live MCP JSON-RPC Inspector

Key Header Telemetry Indicators

Metric Meaning Operational Target
Live Nodes Active non-tombstoned records across L3 booklets/axioms, L2 sections, L1 rules, and L0 passages. Scales linearly; run /compact if deleted tombstones exceed 15% of total records.
HNSW Indexed vertices inside the 4-layer Associative HNSW navigation graph (graph.vhnsw). Should equal Live Nodes after ingestion and compaction.
LSA Dims Active latent dimensions of the Randomized Truncated SVD model (lsa.vlsa). Typically 32–128 (0 before initial /refit_lsa call).
VVEC Hits Cumulative 4 KB binary vector page cache hits served from RAM without OS page faults. > 98% hit ratio under normal WorkingSet workloads (2,048 pages = 8.0 MB cache).

Store Directory Layout & Crash-Safe Persistence

A serve_memory store directory (--dir ./data/store) maintains strict separation between append-only TOON text shards, binary paged vectors, HNSW graph topology, and atomic metadata snapshots:

TEXT
./data/store/
├── store.lock                  # Exclusive single-writer lock with live OS PID verification
├── index.idx                   # Atomic CentralIndex metadata snapshot (temp-write + fsync + rename)
├── index.wal                   # Append-only Write-Ahead Log replayed automatically after unclean shutdown
├── vectors.vvec                # 4 KB page-aligned binary vector file (VVEC v1 f32 or VVEC v2 int8)
├── graph.vhnsw                 # Persisted 4-layer Associative HNSW adjacency lists & entry point
├── lsa.vlsa                    # Persisted Randomized Truncated SVD vocabulary & projection matrix
└── shape_<name>_seg<N>.toon    # Auto-rotated 64 MB immutable TOON record shards (axiom, section, passage, ...)

Deterministic Corpus Verification (verify_artifacts)

Before promoting compiled corpora to examination laptops, compliance portals, or production serve_memory nodes, run verify_artifacts as a mandatory release gate:

BASH
./dist/bin/linux/verify_artifacts --corpus occ
./dist/bin/linux/verify_artifacts --corpus ffiec

verify_artifacts enforces six structural and security invariants:

  1. Schema & Manifest Completeness: Confirms <corpus>_index.json, <corpus>_data.json, knowledge_base.html, and exports/<corpus>.md exist and parse cleanly.
  2. Citation Provenance Coverage: Verifies every passage carries non-empty doc_id, section_id, printed_page, and valid 1-based page_index bounds.
  3. Numerical Vector Sanity: Confirms every Truncated SVD projection row and passage concept vector matches the declared dimensionality with finite norms (zero NaN or Inf values).
  4. Zero Unescaped Script Closers: Confirms embedded JSON blocks inside knowledge_base.html escape </script> sequences (<\/script>) to prevent DOM breakout.
  5. 100% Air-Gapped Self- Containment: Scans knowledge_base.html outside #kbdata prose to guarantee zero remote http://, https://, //, javascript:, or vbscript: references.
  6. Markdown Export Fidelity: Verifies consolidated Markdown exports preserve <!-- page printed="N" pdf="N" --> anchors and escape embedded Markdown headings/fences inside verbatim regulatory text.

Authentication, Network Binding & Air-Gapped Hardening

1. Loopback-First Binding, TLS Proxy & Production Deployment

By default, serve_memory binds exclusively to 127.0.0.1:7331. In multi-user enterprise deployments:

  • Keep serve_memory bound to loopback (or an isolated container network) behind a TLS-terminating reverse proxy (such as Caddy, NGINX, or Envoy) enforcing HTTPS/HSTS and mTLS or OIDC. Reference production manifests ship in Dockerfile, deploy/compose.yaml, deploy/Caddyfile, and deploy/vkbm.service.
  • Enable --require-auth, --secure-cookies, and --audit-log, and inject a high-entropy 256-bit secret via VKBM_AUTH_TOKEN (rather than passing secrets on shared process command lines). serve_memory fails closed at startup if --require-auth is enabled without a configured token:
BASH
export VKBM_AUTH_TOKEN="$(openssl rand -hex 32)"
./dist/bin/linux/serve_memory \
  --store ./data \
  --addr 127.0.0.1:7331 \
  --require-auth \
  --secure-cookies \
  --session-ttl 28800 \
  --llm-timeout 60 \
  --audit-log
  • Observability & Backpressure: Scrape GET /metrics (Prometheus exposition format) for store telemetry, HTTP request/error counts, auth denials, rate-limit counters, and active connections. When active_conns reaches max_concurrent_conns (32), excess connections receive an immediate 503 Service Unavailable response without stalling the accept loop. Expensive and authentication endpoints enforce per-minute rate limiting (429 Too Many Requests), and token budgets are bounded (16..16384).

2. Upstream LLM Endpoint Validation (Anti-SSRF & Chunked HTTP)

When configuring /ask or /v1/chat/completions to call an inference server (VKBM_LLM_URL or runtime POST /configure), vkbm enforces strict http:// URL validation (rejecting cleartext https:// on raw sockets to prevent accidental credential leakage—use a local TLS proxy sidecar for remote HTTPS endpoints), loopback-only targets on runtime /configure unless --allow-remote-config is explicitly enabled, CRLF/header-injection guards, Transfer-Encoding: chunked decoding, configurable --llm-timeout (default 60s), and bounded response sizes (<= 2 MB for LLM completions; <= 64 KB for inbound HTTP requests with 413 Payload Too Large).

3. Air-Gapped Operation

vkbm requires zero external network access for indexing, Randomized Truncated SVD training, VVEC v2 paging, 4-layer HNSW recall, contract gap auditing (/audit_contract), and word-for-word citation verification (/verify_citations). Only optional generative synthesis (/ask, /v1/chat/completions) or optional external Matryoshka embeddings (--embed-url) initiate outbound HTTP connections—typically to a co-located loopback vllm instance on the same air-gapped host.


Subspace Maintenance, Consolidation & Compaction

Refitting Truncated SVD (POST /refit_lsa)

Whenever corpus stewards ingest new regulatory booklets exceeding ~10% of existing store volume, trigger an online Truncated SVD refit so domain co-occurrence patterns update across all vectors:

BASH
curl -sS -X POST http://127.0.0.1:7331/refit_lsa \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"dims": 64}'

Ebbinghaus Consolidation & Shard Compaction (POST /consolidate, POST /compact)

For long-running agent memory stores that accumulate transient working observations alongside permanent L3 pinned axioms and handbook corpora:

BASH
# Apply Ebbinghaus salience decay and prune low-salience unpinned transient records
curl -sS -X POST http://127.0.0.1:7331/consolidate \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"min_salience": 0.15}'

# Rewrite .toon shards, compact vectors.vvec, rebuild graph.vhnsw, and truncate index.wal
curl -sS -X POST http://127.0.0.1:7331/compact \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}'

Backup, Export & Disaster Recovery

  1. Consistent Hot Snapshot Prep: Run POST /compact first so all pending index.wal mutations are checkpointed into index.idx, vectors.vvec, graph.vhnsw, and compacted .toon shards.
  2. Cold Archive Copy: Stop serve_memory cleanly (SIGTERM), archive the store directory (tar -czf vkbm-store-$(date +%F).tar.gz ./data/compliance_prod), and record its SHA-256 digest.
  3. Portable Markdown Audit Export: For human-readable archival independent of binary indices, run build_export to generate exports/<corpus>.md with full YAML frontmatter and printed-page markers.

Part V: Operations & Use Cases — Production Integration Playbooks

This guide presents four concrete operational playbooks showing how banking compliance teams, corporate legal departments, security operations centers (vsight), and autonomous AI agent pipelines deploy vkbm in production.


Use Case 1: Regulatory Handbook Q&A with vllm (Zero-Hallucination RAG)

Scenario

Bank examiners and risk officers need answers across 58 OCC Comptroller's Handbook and FFIEC IT Examination booklets (4,768 pages, 11,387 passages) running on an internal air-gapped workstation paired with vllm. Every claim must cite the exact booklet, Roman-numeral section, and printed page number.

Operational Workflow

  1. Start serve_memory pointed at the local vllm OpenAI server:
BASH
export VKBM_LLM_URL="http://127.0.0.1:8000/v1/chat/completions"
export VKBM_LLM_MODEL="Qwen2.5-32B-Instruct-AWQ"
export VKBM_AUTH_TOKEN="exam-workstation-local-token"

./dist/bin/linux/serve_memory \
  --dir ./data/occ_ffiec_store \
  --host 127.0.0.1 \
  --port 7331 \
  --dim 256 \
  --quantize-int8 \
  --budget 700 \
  --require-auth
  1. Execute a 2-Turn Coarse-to-Fine Grounded Query (POST /ask):
BASH
curl -sS -X POST http://127.0.0.1:7331/ask \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are management responsibilities for testing disaster recovery resumption targets and documenting exceptions to credit underwriting policy?",
    "budget": 700,
    "auto_zoom": true,
    "verify": true
  }'
  1. Resulting Grounded Payload:
    • Turn 1 loads L3 booklet nodes and L2 section centroids across FFIEC Business Continuity Management and OCC Commercial Loans, automatically expanding resumption targets <-> RPO/RTO via #syn_rpo_rto.
    • Turn 2 executes zoom_in into FFIEC-BCM §IV.B and OCC-CLS §II.B.1, injecting compact TOON-LD @graph rows (~470 tokens instead of 2,400+ tokens of raw chunks).
    • Before returning, vkbm runs its deterministic span verifier over every citation emitted by vllm and attaches per-citation VERIFIED_EXACT status badges.

Scenario

Procurement and legal counsel receive a 35-page Cloud Core Banking Master Services Agreement (MSA) from a critical SaaS provider. Before redlining, counsel needs an automated clause-by-clause gap report against OCC Bulletin 2023-17, 12 CFR Part 30, and FFIEC Information Security baselines.

Operational Workflow

Submit the vendor contract directly to POST /audit_contract:

BASH
curl -sS -X POST http://127.0.0.1:7331/audit_contract \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_name": "ApexCore Cloud Banking MSA (Draft 2026-11)",
    "top_k": 3,
    "contract_text": "Section 4.1 Encryption. Provider shall encrypt Customer data in transit using TLS 1.3 and at rest using AES-256, with Customer retaining logical key revocation rights.\n\nSection 7.2 Audit Scope. Customer audit rights are limited to reviewing Provider self-attested security whitepaper once every twenty-four months; on-site or regulator-led examinations are excluded.\n\nSection 9.4 Subprocessing. Provider may delegate data processing to offshore fourth-party subcontractors without prior notice to Customer."
  }'

Example Structured Audit Response

JSON
{
  "contract_name": "ApexCore Cloud Banking MSA (Draft 2026-11)",
  "clauses_evaluated": 3,
  "summary": {
    "matched": 1,
    "partial_review": 1,
    "gap_alert": 1
  },
  "clauses": [
    {
      "clause_index": 1,
      "heading": "Section 4.1 Encryption",
      "modality": "mandatory",
      "status": "MATCHED",
      "top_score": 0.84,
      "citations": [
        {
          "node_id": "n_19",
          "doc_id": "ffiec-infosec",
          "section_id": "II.C.7",
          "printed_page": "34"
        }
      ]
    },
    {
      "clause_index": 2,
      "heading": "Section 7.2 Audit Scope",
      "modality": "prohibition",
      "status": "GAP_ALERT",
      "top_score": 0.31,
      "notes": "Negation/exclusion detected ('excluded') against mandatory supervisory audit right baseline.",
      "citations": [
        {
          "node_id": "n_8",
          "doc_id": "occ-2023-17",
          "section_id": "III.C.2",
          "printed_page": "27"
        }
      ]
    },
    {
      "clause_index": 3,
      "heading": "Section 9.4 Subprocessing",
      "modality": "permission",
      "status": "PARTIAL_REVIEW",
      "top_score": 0.49,
      "citations": [
        {
          "node_id": "n_12",
          "doc_id": "occ-2023-17",
          "section_id": "III.C.5",
          "printed_page": "31"
        }
      ]
    }
  ]
}

Use Case 3: SOC Runbook & Incident Grounding with vsight

Scenario

During an active security incident surfaced in vsight (for example, anomalous credential egress from a payment gateway host), Tier-2 SOC responders need immediate, citation-verified containment steps from internal Incident Response Runbooks alongside mandatory 36-hour / 72-hour regulatory notification thresholds.

Operational Workflow

  1. Ingest internal Markdown/text SOC playbooks using "strategy": "generic_structured" alongside federal notification rules ("strategy": "federal_regulation"):
BASH
curl -sS -X POST http://127.0.0.1:7331/ingest_document \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "doc_id": "soc-ir-04",
    "document": "SOC Playbook IR-04 Credential Compromise & Token Revocation",
    "strategy": "generic_structured",
    "salience": 0.95,
    "raw_text": "## 1. Immediate Containment (0-15 Minutes)\nPage 1\nIsolate affected host via EDR network quarantine, revoke active OIDC refresh tokens, and rotate vault transit keys.\n\n## 2. Regulatory Escalation Thresholds\nPage 2\nIf unauthorized access affects core payment settlement or customer NPI, escalate to General Counsel within 2 hours to evaluate the 36-hour federal banking agency computer-security incident notification rule (12 CFR Part 53)."
  }'
  1. When vsight triggers an alert webhook, query POST /recall with budget: 450 to attach exact runbook steps and regulatory escalation citations directly into the incident ticket in < 1 ms.

Use Case 4: Autonomous Agent Grounding via Model Context Protocol (MCP)

Scenario

An autonomous compliance engineering agent needs structured tool access to inspect store statistics, recall coarse hierarchy, zoom into specific regulatory sections, and self-verify citations before opening a pull request or compliance report.

JSON-RPC 2.0 Tool Invocation Sequence (POST /mcp)

1. Discover Available Grounded Tools (tools/list)

BASH
curl -sS -X POST http://127.0.0.1:7331/mcp \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 101,
    "method": "tools/list",
    "params": {}
  }'

2. Recall Coarse Hierarchy & Zoom Into Exact Rules (vkbm_recall -> vkbm_zoom_in)

BASH
curl -sS -X POST http://127.0.0.1:7331/mcp \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 102,
    "method": "tools/call",
    "params": {
      "name": "vkbm_zoom_in",
      "arguments": {
        "node_id": "n_3",
        "budget": 600
      }
    }
  }'

3. Self-Audit Draft Citations Before Final Output (vkbm_verify_citations)

BASH
curl -sS -X POST http://127.0.0.1:7331/mcp \
  -H "Authorization: Bearer ${VKBM_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 103,
    "method": "tools/call",
    "params": {
      "name": "vkbm_verify_citations",
      "arguments": {
        "citations": [
          {
            "node_id": "n_8",
            "doc_id": "occ-2023-17",
            "section_id": "III.C.2",
            "printed_page": "27",
            "quoted_span": "Contracts for critical activities must stipulate the banking organization right to audit"
          }
        ]
      }
    }
  }'

Part VI: Configuration & CLI Reference

This reference documents every command-line binary, runtime flag, environment variable, corpus configuration schema, .toon synset grammar, HTTP REST endpoint, OpenAI proxy endpoint, and Model Context Protocol (MCP) JSON-RPC 2.0 tool in vkbm.


1. Command-Line Binaries

vkbm — Unified Associative Memory Walkthrough

Runs an isolated temporary store walkthrough (VVEC v2 initialization, L3 axiom pinning, 4-layer handbook ingestion, Truncated SVD subspace fitting, TOON-LD recall, and zoom_in / zoom_out WorkingSet transitions).

BASH
vkbm

build_index — Structural PDF & TOC Indexer

Extracts pages via Poppler pdftotext -layout (direct argument vector execution, zero shell), runs the 2-pass Roman/decimal TOC parser and 2-regime printed-page footer state machine, and writes <corpus>_index.json.

Flag Short Default Description
--corpus <id> -c occ Corpus identifier resolving corpora/<id>.json.
--pdf-dir <dir> -p (from config) Override source PDF directory path.
--out <path> -o (from config) Override output <corpus>_index.json file path.
--max-pages <n> -m 0 (unlimited) Optional per-PDF page cap for rapid smoke testing.
--help -h false Display usage and exit.

build_vectors — Hybrid Lexical, Synset & Truncated SVD Vectorizer

Builds vocabulary weights, expands #syn_* domain synsets, fits Randomized Truncated SVD (LSA), and writes <corpus>_data.json.

Flag Short Default Description
--corpus <id> -c occ Corpus identifier resolving corpora/<id>.json.
--dims <k> -d 128 Number of latent Truncated SVD concept dimensions (16..512).
--power-iters <q> -q 3 Subspace power iterations for singular value separation (2..6).
--in <path> -i (from config) Override input <corpus>_index.json path.
--out <path> -o (from config) Override output <corpus>_data.json path.
--help -h false Display usage and exit.

build_page — Air-Gapped Single-File HTML Compiler

Renders <corpus>_data.json into a 100% self-contained browser search application (knowledge_base.html) with XSS-hardened single-pass JSON substitution.

Flag Short Default Description
--corpus <id> -c occ Corpus identifier resolving corpora/<id>.json.
--in <path> -i (from config) Override input <corpus>_data.json path.
--out <path> -o (from config) Override output knowledge_base.html path.
--help -h false Display usage and exit.

build_export — Citation-Carrying Markdown Volume Exporter

Reads compiled handbook pages in canonical PDF order (deduplicating shared multi-section pages) and writes exports/<corpus>.md with YAML frontmatter and <!-- page printed="N" pdf="N" --> markers.

Flag Short Default Description
--corpus <id> -c occ Corpus identifier resolving corpora/<id>.json.
--out <path> -o (from config) Override output Markdown export path.
--help -h false Display usage and exit.

verify_artifacts — Deterministic Artifact & Security Verifier

Audits <corpus>_index.json, <corpus>_data.json, knowledge_base.html, and exports/<corpus>.md for schema completeness, printed-page coverage, finite vector norms, and zero remote HTML references.

BASH
verify_artifacts --corpus occ

serve_memory — 4-Layer Associative Memory HTTP, OpenAI & MCP Daemon

Flag Default Description
--store, --dir <path> (corpus store) Persistent store directory containing vectors.vvec, graph.vhnsw, lsa.vlsa, index.idx, index.wal, and .toon shards.
--corpus <id> (optional) Corpus identifier (e.g., occ, ffiec) to open or compile into a memory store.
--config <path> (optional) Explicit corpus JSON manifest path (e.g., corpora/occ.json).
--addr <host:port> 127.0.0.1:7331 TCP listen address (127.0.0.1:7331 recommended; front with a TLS reverse proxy for remote traffic).
--build-only false Build the corpus memory store on disk and exit without starting the HTTP daemon.
--mcp-stdio false Run in headless Model Context Protocol (MCP) JSON-RPC 2.0 stdio mode for desktop agents instead of HTTP.
--llm-url <url> (env) Upstream OpenAI-compatible (/v1/chat/completions) or Ollama (/api/chat) http:// URL (use a local TLS sidecar proxy for remote HTTPS endpoints).
--llm-model <id> gpt-4o-mini Upstream LLM model identifier for grounded synthesis.
--llm-key <key> (env) Optional upstream API key (defaults to OPENAI_API_KEY environment variable).
--llm-timeout <sec> 60 Outbound LLM HTTP read/write timeout in seconds (VKBM_LLM_TIMEOUT).
--embed-url <url> "" Optional external HTTP embedding endpoint (e.g., Matryoshka nomic-embed-text).
--embed-model <name> nomic-embed-text External HTTP embedding model identifier.
--embed-alpha <f> 0.70 Hybrid blend weight $\alpha \in [0,1]$ between external neural embeddings and local LSA/synset features.
--synsets <path> "" Additional .toon synset file or directory to load on startup (bundled synsets/ auto-resolved relative to the binary).
--auth-token <tok> (env) Master Bearer/session authentication secret (prefer VKBM_AUTH_TOKEN in production).
--require-auth false Enforce server-side session authentication & RBAC across API routes. Fails closed at startup if neither --auth-token nor VKBM_AUTH_TOKEN is set.
--cors-origin <o> "" Optional explicit allowed Origin for CORS (default: same-origin only; foreign Origin headers return 403).
--allow-remote-config false Permit non-loopback http:// URLs in runtime POST /configure (default: loopback-only anti-SSRF guard).
--secure-cookies false Append ; Secure to Set-Cookie: vkbm_session=... headers (enable behind HTTPS termination; VKBM_SECURE_COOKIES=1).
--session-ttl <sec> 28800 Server-side session expiration TTL in seconds (8 hours default; VKBM_SESSION_TTL).
--audit-log false Emit structured JSON access and RBAC audit logs (ts, method, path, role, status, duration_ms) to stderr (VKBM_AUDIT_LOG=1).
--ask <query> "" Run a one-shot 2-turn coarse-to-fine RAG query + deterministic citation verification and print JSON.
--audit-contract <f> "" Run a one-shot clause-by-clause contract compliance audit against a file path or inline text and print JSON.

bench_eval — Retrieval Ablation, Token Compression & Latency Suite

Runs golden regulatory retrieval ablation, 2-turn WorkingSet token compression benchmarks, VVEC v2 cosine fidelity checks, and contract compliance clause throughput measurements.

BASH
bench_eval

2. Environment Variables

Variable Consumed By Purpose
VKBM_AUTH_TOKEN serve_memory Master Bearer secret when --auth-token is omitted on the command line (recommended over CLI flags in production).
VKBM_LLM_URL serve_memory Upstream OpenAI-compatible or Ollama http:// chat completions endpoint (e.g., http://127.0.0.1:11434/v1/chat/completions).
VKBM_LLM_MODEL serve_memory Upstream model identifier (default: gpt-4o-mini).
OPENAI_API_KEY serve_memory Optional Bearer key forwarded only to the configured upstream VKBM_LLM_URL.
VKBM_LLM_TIMEOUT serve_memory Outbound LLM HTTP read/write timeout in seconds (default: 60).
VKBM_SECURE_COOKIES serve_memory Set to 1/true to append ; Secure to session cookies behind TLS reverse proxies.
VKBM_SESSION_TTL serve_memory Server-side session TTL in seconds (default: 28800).
VKBM_AUDIT_LOG serve_memory Set to 1/true to emit structured JSON request/audit logs to stderr.
VKBM_MARCH Build Pipeline Optional Linux target CPU tuning flags (e.g., -march=x86-64-v3 -mfma); defaults to portable -O3.

3. Configuration File Schemas

Corpus Manifest (corpora/<id>.json)

JSON
{
  "id": "occ",
  "name": "OCC Comptroller's Handbook",
  "brandmark": "OCC HANDBOOK KB",
  "pdf_dir": "pdfs/occ",
  "index_json": "data/occ_index.json",
  "data_json": "data/occ_data.json",
  "page_html": "dist/occ/knowledge_base.html",
  "export_md": "exports/occ.md",
  "footer_matchers": ["occ", "page_n"],
  "header_prefixes": ["Comptroller's Handbook"],
  "examples": [
    "commercial loan underwriting exceptions",
    "third-party risk management board oversight"
  ]
}

Domain Synset Pack (synsets/*.toon)

vkbm ships three curated .toon synset packs (synsets/general.toon, synsets/banking_regulatory.toon, synsets/contracts_compliance.toon) mapping canonical #syn_* tokens to domain acronyms and paraphrases:

TEXT
# Canonical Token | Comma-Separated Equivalence Phrases
syn_rpo_rto       | recovery point objective, recovery time objective, rpo, rto, resumption targets, maximum tolerable downtime
syn_cecl          | current expected credit losses, cecl, asc 326, allowance for credit losses, acl
syn_right_audit   | right to audit, audit rights, independent examination, soc 2 type ii, supervisory access

Ingestion Strategies (POST /ingest_document)

strategy Value Target Document Structure
auto Inspects TOC leaders, Roman/CFR markers, and numbered clauses to select the best structural parser automatically.
occ_ffiec_handbook Roman-numeral & decimal supervisory handbooks (I.A.1, II.B.2) with printed-page footers.
federal_regulation CFR / statutory hierarchy (Part, Subpart, § 30.4(a), Appendix).
legal_contract Commercial agreements (Article, Section 1.1, WHEREAS, schedules, deontic clause splitting).
generic_structured Markdown (#..####) and numbered operational SOPs/runbooks.

4. HTTP REST & OpenAI API Reference (serve_memory)

Method & Path Role Scope Description
GET /health Public Liveness probe returning {"status":"ok"} and store readiness.
GET /metrics Examiner+ Prometheus/OpenMetrics text exposition (vkbm_records_live, vkbm_pager_hits_total, vkbm_http_requests_total, vkbm_auth_denials_total, vkbm_rate_limited_total, vkbm_active_connections).
GET /stats Examiner+ Returns live, tombstones, wal_ops, hnsw_nodes, hnsw_max_layer, lsa_dims, vocab_size, page_hits, page_faults, pinned_tokens.
GET /records Examiner+ Record listing filterable by tier (capped at 200 rows per response).
POST /materialize Examiner+ Fetches full TOON field payloads for a specific @id node identifier via $O(1)$ shard byte offsets.
POST /ingest Steward+ Inserts a typed record (shape, fields, values, salience, pinned, tier).
POST /ingest_document Steward+ Parses a multi-section document via strategy into linked L3 -> L2 -> L1 -> L0 nodes.
POST /recall Examiner+ Executes 4-layer HNSW + Truncated SVD + BM25 associative recall within budget (16..16384 tokens) and renders TOON-LD @graph.
POST /zoom_in Examiner+ Expands an L3 or L2 parent node into its child L2/L1/L0 records inside the WorkingSet.
POST /zoom_out Examiner+ Collapses child records back into their parent L2/L3 summary node.
POST /ask Examiner+ Runs 2-turn coarse-to-fine retrieval, calls upstream LLM (or offline synthesizer), and verifies cited spans.
POST /verify_citations Examiner+ Deterministically checks @id, doc_id, section_id, printed_page, and quoted_span against L0 shards.
POST /audit_contract Examiner+ Splits contract text into clauses, tags modalities, and classifies regulatory gaps (MATCHED, PARTIAL_REVIEW, UNMAPPED_GAP). Rate-limited; persist_contract: true requires Steward+.
POST /refit_lsa Admin Trains Randomized Truncated SVD (dims <= 512) over current corpus and re-projects all live vectors. Rate-limited.
POST /consolidate Steward+ Clusters related L1 records via L2-normalized vector centroids into L2 concept summaries.
POST /compact Admin Compacts segmented .toon shards, cleans orphaned segments, rebuilds graph.vhnsw, and checkpoints index.wal. Rate-limited.
POST /load_synsets Steward+ Hot-reloads a contained .toon/.json synset pack from the store directory or bundled synsets/ directory.
POST /configure Admin Updates runtime upstream LLM/embedder connection parameters (loopback-only unless --allow-remote-config is set).
GET /v1/models Examiner+ OpenAI-compatible model discovery endpoint (vkbm-compliance-v1, vkbm-contract-auditor).
POST /v1/chat/completions Examiner+ OpenAI-compatible chat completion proxy with automatic TOON-LD injection and citation verification.
POST /mcp Examiner+ Model Context Protocol JSON-RPC 2.0 endpoint (initialize, tools/list, tools/call). Enforces read-only RBAC for portal sessions (-32003 Forbidden on mutating tools).
POST /api/v1/auth/session Public Mints a 256-bit OS CSPRNG role-scoped session (portal, delegated, admin) and HttpOnly; SameSite=Strict cookie (requires valid auth_token when configured; rate-limited; fails closed with 503 if --require-auth has no token).
POST /api/v1/auth/logout Public Revokes the active server-side session token and expires the vkbm_session cookie (Max-Age=0).
GET /api/v1/self/profile Examiner+ Returns active session role, workspace routes, and store summary.

5. Model Context Protocol (MCP) Tool Catalog

MCP Tool Name Arguments Grounded Output
vkbm_ask question (string), budget (int, opt), auto_zoom (bool, opt) Synthesized answer + TOON-LD @graph + deterministic citation verification report.
vkbm_audit_contract contract_name (string), contract_text (string), top_k (int, opt) Clause-by-clause MATCHED / PARTIAL_REVIEW / GAP_ALERT matrix with handbook citations.
vkbm_recall query (string), budget (int, opt) Loaded node IDs, token usage, and sorted TOON-LD @graph context block.
vkbm_zoom_in node_id (string), budget (int, opt) Expanded child L1 obligations and L0 verbatim page-cited passages.
vkbm_zoom_out node_id (string) Collapsed L2/L3 parent summary and reclaimed token count.
vkbm_verify_citations citations (array of {node_id, doc_id, section_id, printed_page, quoted_span}) Per-citation VERIFIED_EXACT, VERIFIED_NORMALIZED, METADATA_MISMATCH, or UNVERIFIED_SPAN verdict.
vkbm_ingest_axiom mandate (string), scope (string), pinned (bool, opt) Newly assigned @id of the pinned L3 supervisory axiom.
vkbm_stats (none) Live store, VVEC pager hit/fault counters, LSA dimensions, and HNSW layer counts.

Part VII: Performance, Retrieval Ablation & Hardware Sizing

This guide documents empirical retrieval accuracy, printed-page citation fidelity, token-budget compression ratios, VVEC v2 quantization precision, SIMD microbenchmarks, and hardware sizing envelopes measured with bench_eval and production -prod builds.


1. Empirical Retrieval Ablation (bench_eval)

Regulatory and legal queries frequently fail under naive lexical search (because examiners ask about "resumption targets" while handbooks state "recovery time objectives") and also fail under pure dense embeddings (which blur exact statutory identifiers such as 12 CFR 30.4(c) vs. 12 CFR 53.3).

bench_eval evaluates progressive retrieval stages across golden regulatory paraphrase and exact-citation query suites:

Retrieval Configuration Recall@5 Recall@10 Mean Reciprocal Rank (MRR) Key Failure Mode Eliminated
1. Lexical Okapi BM25 Only 62.5% 75.0% 0.5417 Misses cross-vocabulary regulatory paraphrases (CECL <-> allowance for credit losses).
2. BM25 + Character 3–5gram Subwords 75.0% 87.5% 0.6875 Captures morphological variants (subcontracting / subcontractors), still misses disjoint synonyms.
3. + Randomized Truncated SVD (LSA Subspace) 87.5% 100.0% 0.8333 Bridges latent co-occurrence concepts across multi-booklet corpora without external GPUs.
4. + #syn_* Domain Synsets + Rare Bigram Boost (+0.55) 100.0% 100.0% 0.9583 Locks onto exact multi-word terms of art while preserving acronym equivalence.
5. Full vkbm 4-Layer HNSW + Spreading Activation ($\gamma = 0.25$) 100.0% 100.0% 1.0000 Propagates activation from high-scoring L2 sections into normative L1 rules and L0 quotes.

2. Printed-Page Citation & Structural TOC Accuracy

Evaluated across 58 official OCC Comptroller's Handbook and FFIEC IT Examination booklets (4,768 PDF pages, 11,387 extracted passages):

Structural Metric Measured Result Engineering Mechanism
Printed-Page Footer Attribution Accuracy 98.5% 2-regime footer state machine handling Roman-numeral front matter (i..xii), booklet-prefixed footers (FFIEC IT Examination Handbook), and monotonic gap interpolation.
Multi-Line TOC Hierarchy Resolution 99.1% 2-pass lookahead Roman/letter/decimal parser (I -> A -> 1 -> a) with dot-leader stripping and running-header suppression.
Verbatim Quote Verification Precision 100.0% deterministic Exact and whitespace-normalized substring span check directly against immutable L0 .toon shards (0% false-positive hallucinated quotes).

3. Prompt Token Compression vs. Naive Flat Chunk RAG

Conventional RAG retrieves top-$K$ (K = 10..20) fixed-size 512-token chunks, injecting 5,000–10,000 tokens of repetitive boilerplate per turn. vkbm combines 2-Turn Coarse-to-Fine WorkingSet Zoom with compact TOON-LD @graph tabular serialization:

Retrieval Strategy Avg. Context Tokens / Query Relative Token Cost Structural Lineage Preserved?
Flat Top-12 Chunk RAG (JSON array) 2,480 tokens 1.00x (baseline) No (orphaned text slices)
Flat Top-12 Passages (TOON-LD tabular) 1,590 tokens 0.64x (-35.9%) Partial (metadata columns deduplicated)
vkbm 2-Turn L3/L2 -> Selective zoom_in(L1/L0) 473 – 955 tokens 0.19x – 0.38x (61.4% – 80.9% reduction) Yes (L3 -> L2 -> L1 -> L0 + pinned axioms)

4. VVEC v2 Quantization Fidelity & Latency Microbenchmarks

Measured on a standard x86-64 workstation (-prod optimized native binary, single-core latency and warm serve_memory daemon throughput):

Operation / Subsystem VVEC v1 (f32) VVEC v2 (int8 + f32 scale) Notes
On-Disk Bytes per 256-D Vector 1,024 B (4 vecs / 4 KB page) 260 B (15 vecs / 4 KB page) 3.85x higher cache density per 4 KB VectorPager frame
On-Disk Bytes per 128-D Vector 512 B (8 vecs / 4 KB page) 132 B (31 vecs / 4 KB page) 3.88x higher cache density
Pairwise Cosine Similarity Fidelity 1.00000 (exact) 0.9991 mean (> 0.995 p99) Zero measurable degradation in Recall@5 or MRR
256-D SIMD Dot Product 68.5 ns 54.2 ns Unrolled auto-vectorized FMA / integer accumulation (146x faster than unoptimized debug builds)
Single-Pass WorkingSet zoom_in (L2 -> L1/L0) 0.19 ms 0.18 ms $O(1)$ .toon shard byte-offset seeks
4-Layer Associative Recall (18K nodes) 0.42 ms 0.31 ms Includes #syn_* expansion, HNSW search, and TOON-LD rendering
4-Layer Associative Recall (150K nodes) 0.85 ms 0.58 ms Warm 8.0 MB VectorPager cache
Contract Gap Audit (POST /audit_contract) 2.4 ms / clause 2.1 ms / clause ~84 ms total for a 40-clause vendor MSA
Randomized Truncated SVD Fit (12K passages, k=64) 410 ms 410 ms Pure-CPU Halko–Martinsson–Tropp (q=3 power iterations)
Warm serve_memory /recall Throughput 1,450 QPS 2,180 QPS Loopback HTTP keep-alive

5. Hardware & Store Sizing Reference

Because VectorPager bounds resident vector pages (--max-pages, default 2,048 pages = 8.0 MB) and .toon text records stream on demand via byte-offset seeks, vkbm runs predictably from constrained edge VMs to multi-million-passage enterprise servers:

Corpus Scale Example Workload VVEC v2 (256-D) Disk .toon + HNSW Disk Recommended --max-pages Daemon Steady-State RAM
Small (18,000 nodes) 60 regulatory handbooks (~5,000 pages) 4.8 MB ~22 MB 2,048 (8 MB cache) ~38 MB
Medium (150,000 nodes) 500 handbooks + 1,000 vendor contracts 39 MB ~185 MB 8,192 (32 MB cache) ~115 MB
Large (1,000,000 nodes) Enterprise policy lake + multi-year legal archive 260 MB ~1.2 GB 32,768 (128 MB cache) ~540 MB
XL (5,000,000 nodes) National regulatory + technical library 1.30 GB ~6.1 GB 65,536 (256 MB cache) ~1.9 GB

Reproducing Benchmarks Locally

Run the deterministic benchmark binary from your compiled release directory at any time:

POWERSHELL
# Windows
.\dist\bin\windows\bench_eval.exe
BASH
# Linux
./dist/bin/linux/bench_eval