Local Knowledge Hub

Local Knowledge Hub gives Codex, Antigravity, and Antigravity IDE one project-isolated local knowledge layer. It indexes project files locally, keeps controlled long-term memory, and optionally provides Onyx and private SearXNG web search.

It does not synchronize or modify native chat databases.

Requirements

Windows

• 64-bit Windows 10 or Windows 11
• Windows PowerShell 5.1 or PowerShell 7
• 64-bit Python 3.11 or newer
• For Onyx and web search: Docker Desktop with Linux containers
• At least 10GB RAM is recommended when running Onyx

macOS

• macOS 13 or newer
• Python 3.11 or newer
• For Onyx and web search: Docker Desktop, or Homebrew docker + colima
• At least 10GB RAM is recommended when running Onyx

Install

Clone the repository or download the platform archive from GitHub Releases.

Windows one-click install

Download LocalKnowledgeHub-Setup-1.3.2.exe and double-click it. The setup wizard lets you choose between the complete installation and the core-only installation. It installs for the current user and does not require administrator privileges. The Enable automatic updates (recommended) option is selected by default and may be cleared before installation.

The executable is currently unsigned, so Windows SmartScreen may show an unknown-publisher warning. Verify its SHA-256 file from the same GitHub Release before running it.

Portable alternative: extract local-knowledge-hub-windows-1.3.2.zip and double-click Install-Local-Knowledge-Hub.cmd, or open PowerShell and run:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

The default location is:

%LOCALAPPDATA%\LocalKnowledgeHub

Core-only installation without Onyx or SearXNG:

.\install.ps1 -WithoutServices

macOS install

./install.sh

Core-only installation without Onyx or SearXNG:

./install.sh --without-services

The default macOS location is ~/.local/share/local-knowledge-hub.

After installation, restart Codex, Antigravity, and Antigravity IDE. New tasks automatically retrieve relevant local project context; no special prompt is required.

Version 1.3.2 restores the macOS automatic-update LaunchAgent at login and on its daily schedule, reports the built-in global supplement as global instead of as a user collection, and requires complete evidence-backed arguments for memory updates, moves, and deletion. Context retrieval now stays on the fast lexical path until the local embedding model has completed its first real inference, avoiding multi-second foreground stalls during background warmup.

Version 1.3.1 bounds each project to 25,000 documents and 300,000 chunks by default, keeps manifests and top-level areas fairly represented, and prevents an existing oversized index from growing until it is explicitly reviewed. Usage telemetry no longer blocks foreground retrieval behind indexing transactions, and indexing commits smaller batches. Index pruning and SQLite compaction are dry-run by default and require exact, explicit confirmation. Index and backup jobs run once at login as well as on their normal schedules, while the service watchdog repairs stale maintenance serially. Health checks use lightweight probes, and automatic memory capture requires one complete, evidence-backed argument set instead of retrying partial calls.

Version 1.3.0 adds verified self-updates. A per-user daily task checks GitHub's stable latest Release, compares semantic versions, downloads only the asset for the current platform, verifies its SHA-256 digest, and preserves the existing data, service mode, and update preference during installation. Automatic updates are on for new installations but remain user-controlled.

Version 1.2.3 treats healthy Onyx and SearXNG HTTP endpoints as authoritative, so the watchdog no longer runs docker info every minute or starts a recovery cycle because of a transient Docker CLI timeout. MCP audits distinguish Codex, Antigravity, and Antigravity IDE from safe parent-process markers without storing command arguments or CSRF tokens. Project status now identifies zero-document and missing-path registrations. project-quality-review is dry-run by default and can remove only explicitly named metadata records; it never deletes project directories. An explicit, previously unknown workspace path is now registered even when it is a non-Git document project; inferred Antigravity paths remain Git-only. PDF indexing extracts bounded text through Poppler or the cross-platform pypdf fallback, keeps titles for scans and oversized files, and adds a project-scoped substring fallback for unsegmented Chinese search terms.

Version 1.2.2 validates automatic memory from the user's original evidence only. Questions, transient UI feedback, and implementation requests are rejected, and an assistant-generated title cannot promote project memory into a global scope. Existing noisy automatic memories can be reviewed and reversibly demoted to candidates. WAL checkpoints now run with short busy timeouts, while backup pruning remains a dry run until an operator explicitly applies the exact target list.

Version 1.2.1 also reviews the user's own messages at task completion for explicit, durable project decisions, facts, constraints, and runbooks. Eligible items are captured automatically in the current project; ordinary requests, implementation results, transient debugging, and inferred information are not stored as memory. Generated test.log files are excluded from indexing, and empty global or memory scopes are skipped before full-text or embedding work begins.

Project hints may be a slug, display name, workspace path, or a longer human label containing a unique project name. Ambiguous or unknown hints fail closed and never fall through to another project. Context lookup uses a project-partitioned full-text index and returns its lexical fast path immediately while the optional embedding model warms in the background. Web search retries through SearXNG's default engines and a conservatively simplified query when configured engines return no usable results. The knowledge_context tool schema requires workspace_path, preventing IDE clients from silently issuing an unscoped query when the MCP process itself was started from /. If Antigravity omits the field anyway, the gateway reads only the most recently user-active conversation's local workspace metadata, requires a unique recent match, and resolves that path without reading conversation content. A new Git workspace inferred this way is registered and indexed automatically; an explicit absolute workspace path may also create a non-Git document project. Stale or ambiguous inferred activity still fails closed.

Commands

Windows PowerShell:

& "$env:LOCALAPPDATA\LocalKnowledgeHub\bin\khub.cmd" status
& "$env:LOCALAPPDATA\LocalKnowledgeHub\bin\knowledge-hub-doctor.cmd"
& "$env:LOCALAPPDATA\LocalKnowledgeHub\bin\khub.cmd" web-search "latest MCP specification"
& "$env:LOCALAPPDATA\LocalKnowledgeHub\bin\knowledge-hub-update.cmd" status
& "$env:LOCALAPPDATA\LocalKnowledgeHub\bin\knowledge-hub-update.cmd" check
& "$env:LOCALAPPDATA\LocalKnowledgeHub\bin\knowledge-hub-update.cmd" install
& "$env:LOCALAPPDATA\LocalKnowledgeHub\bin\knowledge-hub-update.cmd" set-auto off
& "$env:LOCALAPPDATA\LocalKnowledgeHub\bin\knowledge-hub-update.cmd" set-auto on

macOS:

~/.local/share/local-knowledge-hub/bin/khub status
~/.local/share/local-knowledge-hub/bin/knowledge-hub-doctor
~/.local/share/local-knowledge-hub/bin/khub web-search 'latest MCP specification'
~/.local/share/local-knowledge-hub/bin/knowledge-hub-update status
~/.local/share/local-knowledge-hub/bin/knowledge-hub-update check
~/.local/share/local-knowledge-hub/bin/knowledge-hub-update install
~/.local/share/local-knowledge-hub/bin/knowledge-hub-update set-auto off
~/.local/share/local-knowledge-hub/bin/knowledge-hub-update set-auto on

Onyx is available at http://127.0.0.1:3000. On first use, create the first account using the generated credentials under data/config/admin.env in the installation directory. Do not share this file.

Automatic maintenance

• Windows uses per-user Task Scheduler jobs for service health, 30-minute incremental indexing, daily backups, and daily verified updates.

• The always-running service watchdog also checks index and critical-backup freshness once per minute. If the operating-system scheduler misses work, it serially dispatches a critical backup first and indexing next. Default stale thresholds are two hours for indexing and 26 hours for backups; maintenance.py health reports both without running a blocking full-database integrity scan.

• Zero-document project review is non-destructive by default:

  python app/src/maintenance.py project-quality-review --minimum-age-days 7

  Existing project paths require both --allow-existing-zero-docs and an exact --project <slug> together with --apply. Only the knowledge-hub registration is removed; the local directory and its files are never touched.

• macOS uses per-user LaunchAgents for the same jobs. Index and backup agents also run once at login before their normal interval/calendar schedules. Turning automatic updates off keeps the local job installed but makes it exit before any network request, so it can be re-enabled without reinstalling.

• Existing Codex and Antigravity MCP configuration is preserved; only the managed local-knowledge entry is added or updated.

• Git projects—and collection folders containing multiple Git repositories—use content-sensitive working-tree fingerprints, so unchanged projects avoid repeated full file walks. A full verification scan still runs at least once every 24 hours.

• Project index budgets default to 25,000 documents, 300,000 chunks, and 4,096 chunks per document. Review them with python app/src/maintenance.py index-budget-review. Applying a review requires both an exact --project <slug> and --apply; a critical backup is created first and project source files are never deleted. Run compact-index for a dry-run disk-space check. Actual compaction additionally requires --apply --confirm-clients-stopped after all three clients are closed.

• Daily scheduled backups preserve project registration, collections, long-term memories, history, embeddings, and audit records while omitting rebuildable file indexes and web caches. Existing full backups are retained separately; maintenance.py backup --mode full remains available for manual snapshots.

• MCP initialization and tool calls are recorded locally with client name, success state, and duration. Tool arguments and project contents are not written to the usage audit.

• Codex automation rules are stored in ~/.codex/AGENTS.md; Antigravity rules are stored in the official ~/.gemini/GEMINI.md location. Older managed Antigravity rules are migrated without removing unrelated user instructions.

Upgrade

Automatic updates are enabled by default. Use knowledge-hub-update status to inspect the setting, set-auto off|on to change it, check to check without installing, and install to update immediately. The updater accepts only the stable GitHub latest Release, restricts downloads to GitHub asset hosts, and requires a matching SHA-256 digest from Release metadata or the companion checksum asset. Manual installation remains supported: extract a newer release and run the platform installer again. Application files and the virtual environment are updated; the data directory and generated secrets are retained.

Uninstall

Windows:

.\uninstall.ps1
.\uninstall.ps1 -PurgeData

macOS:

./uninstall.sh
./uninstall.sh --purge-data

The normal uninstall keeps the knowledge database and backups. The purge option removes local data and Docker volumes as well.

Privacy boundary

• Project databases, memories, embeddings, web caches, credentials, and backups stay under the local data directory.
• Project retrieval is isolated by project or explicit collection.
• Web content is marked untrusted and is never automatically promoted to durable memory.
• The distribution contains no publisher project data or credentials.

License

Local Knowledge Hub integration code is source-available under the PolyForm Noncommercial License 1.0.0. Personal, research, educational, charitable, and other noncommercial use is permitted under that license. Commercial use requires separate permission from the licensor.

This is a noncommercial source-available license, not an OSI-approved open source license. The included Onyx deployment material remains under Onyx's own license; see app/vendor/onyx/LICENSE. Other dependencies retain their own licenses; see THIRD_PARTY_NOTICES.md.