# Hosted OpenBrain / Supabase Implementation Checklist

This checklist converts the migration path into a repeatable implementation order.
It is written for a future hosted OpenBrain/Supabase backend that can replace the
current local `openbrain-bridge` without changing the higher-level Hermes workflow.

## Goals

- Keep the archive as the source of truth.
- Keep provenance attached to every promoted memory.
- Preserve review gating before durable memory becomes visible by default.
- Keep the MCP tool surface stable where possible.
- Make the hosted backend a clean swap-in, not a workflow rewrite.

## Prerequisites

- [x] Local archive is parsed, normalized, chunked, and indexed.
- [x] Reviewed memory artifacts exist.
- [x] Local `openbrain-bridge` is live and tested.
- [x] Hermes has an MCP server configured for the local bridge.
- [ ] Supabase project credentials and project URL are available.
- [ ] OpenBrain base schema is confirmed or imported.
- [ ] MCP hosting target is chosen (hosted endpoint, edge function, or equivalent).

## Phase 1 — Create the hosted backend

- [ ] Create the Supabase project.
- [ ] Confirm PostgreSQL + pgvector support.
- [ ] Create or import the OpenBrain base schema.
- [ ] Verify the canonical `thoughts` table exists.
- [ ] Confirm the backend can store `content`, `embedding`, `metadata`, `created_at`, and `updated_at`.

## Phase 2 — Apply Bert-specific metadata discipline

- [ ] Apply the metadata indexes from `docs/openbrain-bert-supabase-extension.sql`.
- [ ] Create or confirm the helper views:
  - [ ] `bert_memory_candidates`
  - [ ] `bert_approved_memories`
- [ ] Confirm the following metadata keys are supported in the hosted layer:
  - [ ] `memory_type`
  - [ ] `durability`
  - [ ] `confidence`
  - [ ] `sensitivity`
  - [ ] `source`
  - [ ] `source_archive`
  - [ ] `source_conversation_id`
  - [ ] `source_chunk_id`
  - [ ] `source_raw_path`
  - [ ] `source_message_range`
  - [ ] `project`
  - [ ] `topics`
  - [ ] `created_from`
  - [ ] `review_status`
  - [ ] `supersedes`
  - [ ] `expires_at`
- [ ] Confirm the uniqueness / dedup strategy for repeated imports.

## Phase 3 — Import approved memory first

- [ ] Import only the approved memory set first.
- [ ] Preserve provenance on every inserted row.
- [ ] Keep source-only evidence out of the default durable memory surface.
- [ ] Validate the number of imported rows against the approved batch.
- [ ] Confirm the approved items render correctly in the hosted store.

## Phase 4 — Expose the MCP contract

- [ ] Expose a hosted MCP access layer.
- [ ] Keep the tool names aligned with the local bridge where possible.
- [ ] If backend-native tool names differ, create thin aliases.
- [ ] Ensure the hosted layer supports at least:
  - [ ] `status`
  - [ ] `search_archive` or equivalent
  - [ ] `search_approved_memories`
  - [ ] `list_approved_memories`
  - [ ] `get_memory`
  - [ ] `get_source_only`
  - [ ] `get_source_chunk`
  - [ ] `list_review_items`
- [ ] Confirm Hermes can discover the hosted tools.

## Phase 5 — Cut Hermes over cleanly

- [ ] Add the hosted backend as a second MCP server or replacement entry.
- [ ] Keep the local bridge intact during verification.
- [ ] Switch Hermes to the hosted transport only after the hosted tools pass testing.
- [ ] Confirm the active profile points at the hosted endpoint.
- [ ] Document the exact repointing step so it can be repeated later.

## Phase 6 — Verify retrieval quality

- [ ] Search for a known writing-voice item.
- [ ] Search for a known Barely, But Here item.
- [ ] Search for an AI Systems Assessment item.
- [ ] Confirm provenance is displayed correctly.
- [ ] Confirm approved vs source-only boundaries remain distinct.
- [ ] Confirm sensitive items are handled according to the intended policy.
- [ ] Compare search quality with the local bridge reference implementation.

## Phase 7 — Rollback safety

- [ ] Keep the local `openbrain-bridge` config untouched until the hosted backend is proven.
- [ ] Preserve the local archive index and reviewed-memory artifacts.
- [ ] If the hosted backend misbehaves, repoint Hermes back to the local bridge.
- [ ] Verify that rollback restores the previous working state without data loss.

## Phase 8 — Document the repeatable process

- [ ] Record the final hosted setup steps.
- [ ] Record the repointing step.
- [ ] Record the rollback step.
- [ ] Record what was predicted to need tuning vs what actually needed tuning.
- [ ] Record the first-week maintenance cadence.
- [ ] Capture metrics, assessment, and suggestions in the maintenance report template.
- [ ] Update the registry / project ledger with the final hosted backend details.

## Acceptance criteria

The hosted migration is done when:

- the hosted backend answers the same retrieval needs as the local bridge,
- Hermes can use the hosted MCP tools directly,
- provenance survives the import,
- review gating remains intact,
- and the local bridge can be removed or parked without breaking the workflow.

## Repeatability note

This checklist should be treated as a reusable runbook. If the hosted backend is rebuilt later,
follow the same phases in order and use the same verification and rollback criteria.