# Hosted OpenBrain / Supabase Migration Path

## Goal

Swap the current local `openbrain-bridge` MCP server for a hosted OpenBrain/Supabase backend without changing the higher-level Hermes workflow.

The migration should preserve:
- the archive as source of truth
- provenance on every promoted memory
- review-gated approval before durable memory is exposed
- a stable MCP tool surface wherever possible

## Current state

### Live today
- Hermes MCP server: `openbrain-bridge`
- Transport: stdio
- Implementation: `mcp/openbrain_bridge.py`
- Backing data:
  - `index/archive.db`
  - `approved-memory/install-batch-proposed.jsonl`
  - `approved-memory/source-only-index.jsonl`
- Search and fetch are working locally.

### Why this matters
The local bridge proved the retrieval contract:
- archive search works
- approved memory lookup works
- source-only evidence lookup works
- Hermes can see the tools

That means the hosted backend can be treated as a backend swap, not a workflow redesign.

## Target hosted shape

Use the OpenBrain-style hosted stack as the shared durable memory substrate:
- Supabase project
- PostgreSQL + pgvector
- `thoughts` table as the core store
- JSONB metadata indexes for Bert-specific fields
- MCP access layer exposed via hosted endpoint or edge function

## Schema discipline

The hosted backend should preserve the metadata discipline already defined in the architecture doc and SQL extension:

Required metadata examples:
- `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`

Recommended views:
- `bert_memory_candidates`
- `bert_approved_memories`

Recommended helper indexes:
- memory type
- review status
- project
- source
- source chunk id
- sensitivity

## Migration phases

### Phase 1 — Schema and project creation
1. Create the Supabase project.
2. Create or import the OpenBrain base schema.
3. Apply the Bert-specific metadata indexes and views from:
   - `docs/openbrain-bert-supabase-extension.sql`
4. Confirm the `thoughts` table is the canonical memory store.

### Phase 2 — Data import
1. Import only reviewed/approved memory first.
2. Keep source-only evidence outside the durable memory surface unless explicitly needed.
3. Preserve provenance fields for every row.
4. Ensure repeated imports are idempotent via source fingerprinting or a unique source key.

### Phase 3 — MCP compatibility layer
1. Expose MCP tools against the hosted backend.
2. Keep the tool names as close as possible to the current bridge contract:
   - `status`
   - `search_archive` or hosted equivalent
   - `search_approved_memories`
   - `list_approved_memories`
   - `get_memory`
   - `get_source_only`
   - `get_source_chunk`
   - `list_review_items`
3. If the hosted backend uses different internal names, build thin aliases so Hermes does not need a workflow rewrite.

### Phase 4 — Hermes cutover
1. Replace the Hermes MCP server entry from the local command to the hosted URL or hosted MCP transport.
2. Keep the local bridge available as fallback until the hosted backend passes all tests.
3. Verify Hermes sees the same core memory affordances.

### Phase 5 — Verification
Verify all of the following before decommissioning the local bridge:
- search returns the expected approved items
- source provenance is intact
- approved vs source-only boundaries remain clear
- review-gated items do not leak into approved memory
- retrieval quality is acceptable for the common queries we care about

## Rollback plan

If the hosted path misbehaves:
1. keep the local bridge config intact
2. revert the Hermes MCP entry to `openbrain-bridge`
3. continue working from the local archive-backed surface while the hosted layer is corrected

## Success criteria

The migration is successful when:
- the hosted backend answers the same core retrieval needs as the local bridge
- the local bridge can be disabled without losing the workflow
- the memory review/pruning/tuning cycle continues to work against the hosted layer
- Hermes can access memory without requiring archive files to be loaded into prompt context

## Decision

**Do not remove the local bridge until the hosted system has been verified.**
The local bridge is the safety rail and the reference implementation.