GoodQ4All: Local-First Multimodal AI Memory & Video Intelligence Stack

Offline Video Search, Scene Segmentation, Speech Transcription (Whisper), Speaker Diarization, and SQLite + Qdrant Semantic Search on Windows 11

_{(Note: The optional Ask GoodQ voice agent is a hosted extension using ElevenLabs APIs. The core GoodQ4All memory system itself is 100% local and offline.)}

---

⚡ The Local-First Multimodal Memory Stack

GoodQ4All is a 100% private, offline alternative to cloud-based media intelligence services. It ingests video, audio, and text files into queryable, structured scene-level memories, persisting the knowledge graph and vector representations locally on your computer.

Following a strict "proof-backed" system doctrine, GoodQ4All documents every perception step, tracks evidence manifests, and logs a comprehensive audit trail so that every memory claim can be verified.

---

🎬 From Media to Memory

No media fixture is bundled with this repository. For a local smoke, use a short clip you own or are licensed to process. The existing scripts/bootstrap_onboarding.py helper is an operator workflow, not an approved public fixture contract.

• Using This All-in-One Installer (Unified Windows Installer):

  🚀 View the latest GoodQ release

  [!IMPORTANT] System Requirement: Windows 11 only. GoodQ4All is built for Windows-first local execution. It requires at least 25 GB of free space to store local database structures, models, and cache files.

  • SmartScreen Workaround: Since the setup installer is currently self-signed, Windows SmartScreen may show an "Unknown Publisher" dialog. Click More info and select Run anyway to proceed.
  • Integrity Checksum: Verify your download authenticity by running the following command in PowerShell:

    Get-FileHash <downloaded-release-asset>

    Expected SHA256 hash: Refer to the GitHub Releases page for the latest signed executable checksum.

  

---

🛡️ Core Capabilities & Architecture

1. Proof-Backed Ingestion & Hardened API Facade

Machine memory should earn every claim it makes. GoodQ4All generates step-by-step logs (step_runs.jsonl), scene manifests, and intermediate features for every ingested file.

• Single-Use Confirmation Tokens: Ingestion submission routes are protected by a server-generated token handshake with single-use nonce validation, preventing unauthenticated/out-of-bounds execution.
• Epistemic Verification: Ingestion is tracked using verifiable manifests and SQLite-backed relational schemas.
• No Silent Failures: The Control Agent and Watchdog processes bubble errors directly to the operator consoles, providing absolute visibility into the execution stack.

2. Local Model Governance & VRAM Budgeting

To run large-parameter local models safely on consumer hardware (e.g. RTX 4070 Ti SUPER 16GB) without Out-of-Memory (OOM) crashes, GoodQ4All implements strict VRAM and execution controls:

• Model Lifecycle Manager: A specialized context manager (lib/model_lifecycle.py) that audits free VRAM using PyTorch and nvidia-smi before loading models, dynamically evicting idle networks from GPU memory.
• Local Agent Stack (MiniAgentClient): Gated LLM reasoning and local tool execution through zero-dependency policy enforcement middleware, loading schemas, policies, and contracts dynamically from the version-controlled agents/stack/ directory.
• Endpoint Fallback Orchestration: Automatically falls back from the primary local vLLM server (prefer_speed, running Qwen2.5) to a local Ollama service (prefer_quality, running Phi-4) or a CPU-safe model variant when VRAM thresholds are breached.

3. Experimental TurboQuant Sidecar Caching

High-precision float32 embeddings remain persisted in Qdrant and FAISS. TurboQuant is an optional SQLite sidecar experiment for candidate filtering; it is not enabled as the default retrieval path. Any activation must first demonstrate equivalent valid hits and no latency regression against the active Qdrant/FAISS baseline on the target corpus.

Note

Hybrid Precision Caching Model: Optional sidecar model: TurboQuant fields are additive only. Authoritative float32 vectors remain in Qdrant and FAISS, and a sidecar experiment must fail closed to normal retrieval when coverage, validity, or measured latency is insufficient.

4. Adaptive Hardware Profiles

The pipeline dynamically adjusts its computational needs to match your system specs:

• BASELINE (CPU-safe): Fully operational, offline-ready execution on standard CPU hardware. Bypasses GPU requirements gracefully.
• GPU_ENHANCED: Activates local NVIDIA GPU (CUDA 12.1) and WSL2 accelerated audio processing paths for fast, high-volume ingestion.

---

⚙️ Setup Paths

Route A: Standalone User Installation (Recommended)

GoodQ4All compiles the isolated Python environment, the Qdrant database, and perception libraries into a single executable wrapper:

1. Download the appropriate release asset from the GitHub Releases page, if one is provided for your platform.
2. Launch GoodQ4All from the desktop shortcut.
3. Open the local Retro Memory Explorer dashboard at http://127.0.0.1:30000/ui/retro_console_v1/.
4. Drag-and-drop video/audio files onto the yellow-dotted Upload Pad to begin automatic ingestion.

Route B: Developer Source Setup (Advanced)

If you are developing, customizing the pipeline, or running from source:

Developer Source Setup Steps (Advanced)

Step-by-Step Developer Installation

Step	Type or do this	Demo frame
1	Clone the official source: git clone https://github.com/GoodQ02/goodq-memory-engine.git
2	Enter the project cabin: cd goodq4all
3	Run the bootstrap installer: python scripts/bootstrap_install.py CPU-safe first-run variant: python scripts/bootstrap_install.py --disable-gpu --disable-wsl-audio --skip-model-prefetch.
4	Customize local config: edit the bootstrap-created .env.local when using local model, cache, or provider settings.
5	Validate the bootstrap: .\scripts\bootstrap_validate.bat
6	Run the launcher/readiness check: .\LAUNCH_GOODQ.ps1
7	Start Watchdog, then copy one small media file into the import inbox zone (defaults to %USERPROFILE%\GoodQ_Data\import_inbox): conda run --no-capture-output -n goodq_core python -m cli.watchdog
8	Start the API and inspect proof: conda run --no-capture-output -n goodq_core python -m api.server

---

📺 User Interfaces

GoodQ4All ships with two local operator console variants:

• Classic Operator Console (served at /ui/operator_console_v1/): Exposes the current scope strip, flight deck, proof/evidence status, recurrence reports, and video inventories.
• Retro Memory Explorer (v1.4.7) (served at /ui/retro_console_v1/): A premium cyber-CRT dashboard featuring a four-panel resizable/collapsible layout with floating restore tabs, an entity co-occurrence graph with dynamic zoom and flight transitions, an Inspector panel containing keyframe image/transcript views, and bidirectional timeline checklists.

---

📖 Authoritative Documentation

Start Here

• Guided demo: docs/guides/DEMO.md
• First run: docs/guides/FIRST_RUN.md
• Install: docs/bootstrap/INSTALL_BOOTSTRAP.md
• Clean memory start: docs/guides/CLEAN_MEMORY_START.md
• Public release scope: docs/releases/PUBLIC_SANITIZATION_MANIFEST.md

Technical Details

• Architecture: docs/architecture/SYSTEM_ARCHITECTURE.md
• Memory Storage: docs/architecture/MEMORY_STORAGE.md
• Hybrid Caching: docs/architecture/TURBOQUANT_HYBRID_CACHING.md
• Current Agent State: docs/agent/CURRENT_STATE.md
• RAG Context Pack: docs/GOODQ_RAG_CONTEXT_PACK.md

---

📄 License

MIT. See LICENSE.