data-lore-hive

# Hive prototype: evidence-gated answers from small local models

A research prototype that asks a small local LLM questions about local documents and **only releases an answer when independent checks agree with the source**. Otherwise it withholds the answer and records why. Everything is append-only and kept as evidence, including failures.

It runs on a single machine with the Python standard library. The optional model mode uses [Ollama](https://ollama.com) on loopback. There are no third-party Python dependencies.

> **Status:** prototype. The measurements below are small, fixed-seed regression runs on one model family. They are not a reliability benchmark. See [Stated limits](#stated-limits) before relying on any of this.

## What it does

The unit of work is a **cookie**: a short-lived worker process with a single role. Cookies never share conversation state. They communicate only through an append-only SQLite event log.

1. **Learner / ingest** stores a source document's text, path and SHA-256 as an immutable snapshot.
2. **Solver** gets keyword-retrieved excerpts and must return either an answer with an **exact quote** or an explicit *not found*.
3. **Support cookie** is a separate process that sees only the question and the quote, never the solver's answer. It must independently answer or abstain.
4. **Deterministic gates** release the answer only when all of these hold:
   - the quote exists verbatim in a snapshot
   - the source file still hashes to that snapshot (freshness)
   - the answer is anchored in the quote
   - solver and support agree
   - for policy tables, condition and outcome come from the *same row*
   - every model response matched a strict JSON schema

   A failure in any gate withholds the answer. The system never falls back to a probabilistic override.
5. **Not found** is not trusted on the solver's word. Absence must be confirmed independently before it is stored as a finding.

Query outcomes: `supported_answer`, `not_found_in_source`, `needs_review` (answer withheld), `unsupported_output`, and `stale_source`.

Survivability work adds one-way replication of the event log to a storage-only replica, tiered retention, and verified restore. It also adds recreation of source files from stored snapshots, so a second machine can answer from a recovered checkpoint while the primary is offline.

Signed code releases extend this to the code itself. Every new master commit is backed up to the replica as an unsigned candidate, but only a release signed with a human-held key can become the approved version. A second signature, the **recovery-tested pin**, marks a release that has actually been recovered and run on another machine with the primary switched off.

[`agent-memory/`](agent-memory/README.md) is a separate, self-contained pipeline. It turns your own Telegram JSON chat export into cited memory for your local agent: secrets are masked, a model proposes dated records in two attributed voices, code verifies every quote word for word, a second model audits each record, and you approve what is exported.

## Architecture

```
            ┌───────────── append-only SQLite event log (triggers block UPDATE/DELETE) ─────────────┐
 ingest ──► │ source snapshots · claims · model calls (raw bytes) · verdicts · findings · lore      │
            └──────▲────────────────▲────────────────────▲─────────────────────▲──────────────────┘
                   │                │                    │                     │
             solver cookie    support cookie     relevance cookie      deterministic gates
            (excerpts only)  (question+quote)   (snapshot, no answer)  (quote/hash/anchor/row)
                   └──── each a separate process; same local model via ollama_local.py ────┘

 replication.py ──(SSH forced-command, push/fetch/status only)──► storage-only replica ─► retention.py
 source_recovery.py / cross_machine_recovery.py: restore DB + recreate sources on another host
 code_sync.py ──(upload-only SSH account)──► code_publisher.py on replica: unsigned candidates, signed releases, signed pin
 recovery_drill.py (other host, primary off): verify signed release ─► restore memory ─► tests + model trials ─► sealed evidence
```

| Module | Role |
|---|---|
| `hive.py` | Event store, the three-cookie arithmetic demo, and verdict policy (`verified` / `disputed` / `needs_review`) |
| `knowledge.py` | Source ingest, keyword retrieval, the `ask` pipeline, freshness checks, findings |
| `support_cookie.py`, `relevance_cookie.py` | Independent second-opinion requests with deliberately restricted context |
| `policy_tables.py`, `policy_slots.py`, `policy_binding.py`, `policy_relevance.py` | Narrow parser for policy tables and If/When prose, plus conservative binding of a question to a rule |
| `version_comparison.py` | Structured, fail-closed comparison for minimum-version questions |
| `lore.py` | Snapshot-bound interpretation records with list/inspect/revoke/affected. **Promotion to authority is disabled** (`EXPERIMENTAL_PROMOTION = False`) |
| `ollama_local.py`, `ollama_preflight.py` | Loopback-only Ollama adapter with bounded context, output and timeout, plus schema/version preflight |
| `replication.py`, `retention.py`, `sync_agent.py`, `recovery_server.py` | One-way snapshot replication with hash-chained manifests, receiver-side retention, macOS launchd sync and watchdog, and a read-only recovery endpoint |
| `source_recovery.py`, `cross_machine_recovery.py` | Recreate sources from snapshots without trusting stored paths, and drive a recovery drill |
| `code_release.py`, `code_builder.py`, `code_publisher.py`, `code_transport.py`, `code_sync.py` | Signed code releases: Git-bundle candidates, `ssh-keygen -Y` signed manifests with monotonic sequence numbers, a publisher service on the replica, a restricted upload/read transport, and the sync hook that backs up each new master commit |
| `install_code_publisher.py`, `build_code_installer.py`, `rollback_code_publisher.py`, `prepare_mac_code_sync.py` | One-time publisher installer and its rollback (both refuse to run on any host not named `replica-host`), plus staging of the client-side update. None of them installs anything when imported or tested |
| `build_recovery_drill.py`, `recovery_drill.py`, `recovery_drill_worker.py` | Recovery drill for signed releases: a frozen baseline, a runner that checks tool hashes before importing anything, and a worker that runs only from the verified checkout. It produces a sealed evidence index that a pin can be signed over |
| `evaluate*.py`, `measure_rerun.py`, `replay_policy_measurement.py` | Evaluators. Each run goes to a fresh directory and saves all results, including failures. Replay re-scores preserved model bytes offline |

## Running it

Requires Python 3.10 or newer. The test suite has been run on 3.14.

```bash
python3 -m unittest discover          # full offline suite, no model or network needed
python3 hive.py demo                  # scripted: "360 litres — verified", exit 0
python3 hive.py demo --inject-error   # scripted: "361 litres — disputed", exit 2 (intentional)
```

Model mode needs Ollama running at `127.0.0.1:11434` with a model already pulled. Nothing is downloaded by this code.

```bash
python3 hive.py demo --model gemma4:e4b
python3 knowledge.py --db mem.sqlite3 ingest PROTOTYPE-NOTES.md
python3 knowledge.py --db mem.sqlite3 ask "What happens when the model calculation disagrees?" --model gemma4:e4b --seed 11 --temperature 0.2
python3 evaluate.py --model gemma4:e4b
```

Demo state is written to `state/` unless you pass `--state-dir`. Databases are git-ignored.

Replication and recovery (`replication.py`, `install_mac_sync.py`, `sync_agent.py`) expect a client config and an SSH key that you provide, and a receiver host that you set up. The signed-code modules additionally need your own release-signing key, an `allowed_signers` file and a pinned replica host key; none are shipped. The host-specific memory-replica installers used in the original deployment, the generated signed-code install kits, and all drill evidence are **not** included; see [REDACTIONS.md](REDACTIONS.md). [SURVIVABILITY.md](SURVIVABILITY.md) and [SOURCE-RECOVERY.md](SOURCE-RECOVERY.md) describe the protocol and its checks.

## Use with Claude Code / Claude Desktop (MCP)

[`plugins/verified-memory-mcp/`](plugins/verified-memory-mcp/README.md) is a local, read-only stdio MCP server. It exposes two tools, `verified_memory_search` and `verified_memory_get`, over a checksum-verified memory pack such as the ones `agent-memory/` exports. It needs Node 22 or newer and is not published to npm, so you build it from this checkout:

```bash
cd plugins/verified-memory-mcp
npm ci --ignore-scripts && npm run build && npm test
```

Register it with Claude Code. The paths are placeholders, so replace them with absolute paths:

```bash
claude mcp add verified-memory -- /absolute/path/to/node --experimental-permission \
  --allow-fs-read=/absolute/path/to/hive-public/plugins/verified-memory-mcp \
  /absolute/path/to/hive-public/plugins/verified-memory-mcp/dist/index.js
```

For Claude Desktop, use the `mcpServers` example in the [plugin README](plugins/verified-memory-mcp/README.md#claude-desktop-configuration-example). With no `--pack`, the server serves the bundled fictional sample, so asking it to search for "pottery" should return record `M-sample-2` with its quote and source message ID. The checksum check proves the pack wasn't altered, not that its contents are true. See the plugin's README and [VALIDATION.md](plugins/verified-memory-mcp/VALIDATION.md) for its limits.

## Measured results

Setup for these runs:

- Model: `gemma4:e4b` on Ollama 0.32.14
- Seeds: 11, 29 and 47, at temperature 0.2
- Hardware: 16 GB Apple M1 Pro

**Latest production configuration (2026-09-30)**, from [POLICY-RELEVANCE-SAFETY.md](POLICY-RELEVANCE-SAFETY.md) with raw responses in `safety-records-2026-09-30/`:

| Suite | Trials | Correct / answerable | Co