HIVE

Local-first AI context, memory, retrieval, token-optimization and governed execution platform for large LLM-assisted software projects.

Status

Latest stable release: v1.0.2. HIVE v1.0.3 is the current patch release candidate. It prepares the Windows/install hardening, bounded project discovery, telemetry and Control Center improvements already accepted on protected main.

Target stable release: v1.0.3 (release candidate; not published). See CHANGELOG.md, the candidate release notes, and the published v1.0.2 GitHub Release.

HIVE v1.0.2 remains the currently downloadable stable source distribution until the governed v1.0.3 publisher completes. The internal HIVE V0.1 Foundation baseline remains complete and unchanged; see docs/project-brain/13-CHECKPOINT.md.

Capabilities

The accepted baseline provides, with deterministic test coverage:

• Durable project registry for multiple local projects, with Git branch, HEAD, working-tree state and language-stack inspection.
• Durable task/prompt intake (PDF, TXT, Markdown, structured text) with content-addressed original preservation (SHA-256 + lossless Zstandard) and project-scoped recovery.
• Git-aware incremental repository indexing with stable content identity and Python AST symbol metadata.
• Project-scoped lexical, semantic (PostgreSQL + pgvector) and hybrid RRF retrieval with provider-independent embedding adapters, optional reranking and deterministic lexical fallback.
• Checkpoint-first Context Manager, progressive disclosure (L0–L5), adaptive token budgeting, context fingerprints, delta context and provider/prompt cache adapters over durable memory with provenance and lifecycle.
• Governed autonomous execution with tool gating, staged noncanonical output, the Local Verified Runner, and a concrete bounded OpenAI-compatible HTTP executor transport that is disabled by default until explicitly configured; the MCP core surface remains read-only.
• Telemetry/event bus and the full HIVE Control Center with bounded, provenance-labelled metrics — unknown values are never rendered as zero.
• Local Docker Compose deployment, backup/recovery and secondary-disk persistence with durable PostgreSQL and content-addressed storage.

Exact capability evidence and boundaries live in the canonical Project Brain sources; this README intentionally links instead of duplicating them.

Quick start

Requirements: Docker Desktop on Windows or Docker Engine plus the Compose plugin on Linux, and Git.

Windows (PowerShell):

Copy-Item .env.example .env
docker compose up -d --build
docker compose ps
Invoke-WebRequest http://localhost:8000/api/v1/health
Start-Process http://localhost:3000

Linux:

cp .env.example .env
docker compose up -d --build
docker compose ps
curl --fail http://localhost:8000/api/v1/health
xdg-open http://localhost:3000

The dashboard is served at http://localhost:3000 and the API health endpoint at http://localhost:8000/api/v1/health. The API and dashboard bind to localhost by default; PostgreSQL and Redis stay internal to the Compose network. The Compose migration service applies Alembic migrations before the API starts.

Runtime and storage model

• PostgreSQL (with pgvector) is the canonical durable structured store.
• Redis-compatible cache is a non-canonical hot layer; losing it never destroys canonical project truth.
• HIVE_DATA_ROOT holds durable bind-mounted state and CAS originals under cas/sha256; it defaults to .hive-data for development and is ignored by Git. For secondary storage set it to e.g. D:/HIVE (Windows) or /mnt/hive (Linux).
• HIVE_PROJECTS_ROOT is the single read-only host project directory mounted into the API; project access is constrained to it.
• Git remains the canonical source history; derived artifacts never replace it.

See docs/INSTALLATION.md and docs/project-brain/12-LOCAL-DEPLOYMENT.md.

Repository map

Path	Purpose
backend/	FastAPI core, data layer, execution and retrieval logic, tests
dashboard/	React/TypeScript Control Center
scripts/	Deterministic validation, release, governance and integration tooling
docs/	Installation, operations, release and maintenance documentation
docs/project-brain/	Canonical project decisions and scope
docs/releases/	Versioned release notes and templates
migrations/	Versioned Alembic schema migrations
.github/	CI, release, security automation and templates
.engineering/	Derived engineering policy and release provenance

Validation

python -m pip install -r requirements-dev.txt
python scripts/validate.py

scripts/validate.py runs canonical source verification, deterministic release metadata verification, the release package dry-run, secret scanning, generated map checks, lint, typecheck, backend/dashboard tests, the dashboard build, npm audit and docker compose config --quiet. The same entry point runs in the hosted Validate gate.

Versioning and releases

HIVE uses Semantic Versioning as defined in docs/VERSIONING.md and maintained under docs/MAINTENANCE.md. Release metadata coherence is enforced deterministically by scripts/verify_release_metadata.py.

The release process is documented in docs/RELEASING.md, docs/RELEASE-CHECKLIST.md and docs/UPGRADING.md. Source releases are the only supported distribution channel in this increment.

Open source

HIVE is open source software licensed under the Apache License 2.0, an OSI-approved permissive license. You may use, reproduce, modify and distribute HIVE subject to the license terms. Third-party components and dependencies retain their own licenses.

Contributions are welcome through HIVE's governed branch/PR workflow; see CONTRIBUTING.md before submitting changes. The Claude for Open Source application evidence records HIVE's conservative eligibility and impact evidence without claiming unmeasured adoption.

Security, support, contributions and license

• SECURITY.md — supported line, private reporting, severity expectations.
• SUPPORT.md — support boundary and required reproduction evidence.
• CONTRIBUTING.md — branch/PR and exact-head review workflow.
• AGENTS.md — agent guidance and release/maintenance rules.
• LICENSE — Apache License 2.0, the license governing HIVE's open-source distribution and contributions.

Canonical sources

Start with docs/project-brain/13-CHECKPOINT.md, then consult scope, Definition of Done, architecture, requirements and the decisions ledger. Canonical sources take precedence over this README.