Hippocampus CA1 + Subiculum Phase 1 (trisynaptic loop completion)

CHANGELOG.md

@@ -5,6 +5,18 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
 
 ## [Unreleased]
 
+### Added — Hippocampus CA1 + Subiculum Phase 1 (trisynaptic loop completion)
+
+Completes the hippocampal trisynaptic loop. Migration 059 shipped DG +
+CA3; this adds **CA1** (match/mismatch detector) + **Subiculum**
+(hippocampal output bridge to cortex).
+
+- **Migration 071** — 3 tables (`hippocampus_ca1_comparisons`,
+  `hippocampus_ca1_state` single row, `hippocampus_subiculum_outputs`).
+- **`agentmemory.mcp_tools_hippocampus_ca1`** — 4 MCP tools.
+- **9 tests**.
+- **Design proposal** at `docs/proposals/hippocampus_ca1_subiculum.md`.
+
 ### Added — issue #116 Phase 1-A: retrieval pathway log
 
 External architecture memo (issue #116, "Thalamus, Basal Ganglia, and

db/migrations/071_hippocampus_ca1_subiculum.sql

@@ -0,0 +1,61 @@
+-- Migration 071: hippocampus CA1 + Subiculum — Phase 1 schema
+--
+-- Completes the hippocampal trisynaptic loop. Migration 059 shipped
+-- DG (pattern separation) + CA3 (pattern completion); this migration
+-- adds CA1 (match/mismatch detector) + Subiculum (cortical bridge).
+--
+-- Phase 1 is inspection-only / additive. Tables + tools only. Phase 2
+-- hooks CA1 into the existing hippocampus_* pipeline. Phase 3 wires
+-- Subiculum into workspace_broadcasts. Phase 4 enforces.
+--
+-- Rollback:
+--   DROP TABLE IF EXISTS hippocampus_subiculum_outputs;
+--   DROP TABLE IF EXISTS hippocampus_ca1_state;
+--   DROP TABLE IF EXISTS hippocampus_ca1_comparisons;
+--   DELETE FROM schema_version WHERE version = 71;
+--
+-- IDEMPOTENT.
+
+CREATE TABLE IF NOT EXISTS hippocampus_ca1_comparisons (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    compared_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%S', 'now')),
+    agent_id TEXT,
+    memory_id INTEGER,
+    ec_input_hash TEXT,
+    ca3_output_hash TEXT,
+    match_score REAL NOT NULL CHECK(match_score BETWEEN 0.0 AND 1.0),
+    novelty_score REAL NOT NULL CHECK(novelty_score BETWEEN 0.0 AND 1.0),
+    classification TEXT NOT NULL CHECK(classification IN ('match', 'mismatch', 'partial', 'ambiguous')),
+    notes TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_ca1_cmp_recent ON hippocampus_ca1_comparisons(compared_at);
+CREATE INDEX IF NOT EXISTS idx_ca1_cmp_agent ON hippocampus_ca1_comparisons(agent_id, compared_at);
+CREATE INDEX IF NOT EXISTS idx_ca1_cmp_class ON hippocampus_ca1_comparisons(classification, compared_at);
+
+CREATE TABLE IF NOT EXISTS hippocampus_ca1_state (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    recent_match_rate REAL NOT NULL DEFAULT 0.5 CHECK(recent_match_rate BETWEEN 0.0 AND 1.0),
+    recent_novelty_rate REAL NOT NULL DEFAULT 0.5 CHECK(recent_novelty_rate BETWEEN 0.0 AND 1.0),
+    total_comparisons INTEGER NOT NULL DEFAULT 0,
+    last_comparison_at TEXT,
+    updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%S', 'now'))
+);
+INSERT OR IGNORE INTO hippocampus_ca1_state (id) VALUES (1);
+
+CREATE TABLE IF NOT EXISTS hippocampus_subiculum_outputs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    output_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%S', 'now')),
+    agent_id TEXT,
+    memory_id INTEGER,
+    ca1_comparison_id INTEGER,
+    target_channel TEXT NOT NULL CHECK(target_channel IN ('cortex_general', 'workspace_broadcast', 'thalamus_relay', 'other')),
+    output_strength REAL NOT NULL DEFAULT 0.5 CHECK(output_strength BETWEEN 0.0 AND 1.0),
+    notes TEXT,
+    FOREIGN KEY (ca1_comparison_id) REFERENCES hippocampus_ca1_comparisons(id) ON DELETE SET NULL
+);
+CREATE INDEX IF NOT EXISTS idx_sub_outputs_recent ON hippocampus_subiculum_outputs(output_at);
+CREATE INDEX IF NOT EXISTS idx_sub_outputs_target ON hippocampus_subiculum_outputs(target_channel, output_at);
+
+INSERT OR IGNORE INTO schema_version (version, description, applied_at)
+VALUES (71, 'hippocampus CA1 + Subiculum Phase 1: 3 tables completing the trisynaptic loop',
+        strftime('%Y-%m-%dT%H:%M:%S', 'now'));

docs/proposals/hippocampus_ca1_subiculum.md

@@ -0,0 +1,100 @@
+# Proposal: Hippocampal CA1 + Subiculum (completion of the trisynaptic loop)
+
+**Status:** Phase 1 design + implementation, branch `brain-regions-ca1-phase-1`.
+**Author:** Claude Opus 4.7 (overnight chain — 5th region tonight)
+**Date:** 2026-05-20
+**Scope:** Extension of migration 059 (DG+CA3). Completes the hippocampal trisynaptic loop. Phase 1 inspection-only.
+
+---
+
+## TL;DR
+
+Migration 059 shipped Dentate Gyrus (pattern separation) + CA3 (pattern completion). The hippocampal trisynaptic loop is:
+
+```
+Entorhinal Cortex L2 → DG → CA3 → CA1 → Subiculum → Entorhinal Cortex L5 → out
+                                  ↑
+                              missing
+```
+
+CA1 is **computationally key** — it sits between CA3's pattern-completion output and Subiculum's cortical-bridge output. Its function: **compare incoming entorhinal input against CA3's recall output**. Match = familiarity confirmation. Mismatch = novelty detection / prediction error.
+
+Subiculum is the hippocampal output structure. Without it, the hippocampal "memory trace" has no clean way to influence the rest of the brain — it's bottled up in CA3.
+
+In brainctl terms, missing CA1+Subiculum means:
+- No first-class **match/mismatch detector** for memory writes (would CA3's completion match what the entorhinal grid currently sees?)
+- No first-class **hippocampal output channel** (writes just land in `memories` and get picked up by full-text search; biology has the hippocampus actively pushing certain content into cortex via Subiculum→EC deep layers)
+
+Phase 1 ships schema for both subfields + 4 MCP tools. **No behavior change.** Phase 2 hooks CA1 into the existing hippocampus_dg_separate / hippocampus_ca3_complete pipeline. Phase 3 wires Subiculum into workspace_broadcasts. Phase 4 enforces.
+
+## Architectural placement
+
+```
+              ┌──────────── existing ────────────┐
+              │                                  │
+   EC L2 ──→ DG ──→ CA3 (pattern completion)     │
+              │      │                           │
+              │      └──→ CA1 ◀── EC L3 ─────────┤
+              │           ▼      (this PR)       │
+              │      compare → match/mismatch    │
+              │           │                      │
+              │           ▼                      │
+              │      Subiculum                   │
+              │      (this PR)                   │
+              │           │                      │
+              │           ▼                      │
+              │      EC L5/L6 → cortex            │
+              └──────────────────────────────────┘
+```
+
+## Phase 1 schema (migration 071)
+
+```sql
+CREATE TABLE hippocampus_ca1_comparisons (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  compared_at TEXT NOT NULL DEFAULT (...),
+  agent_id TEXT,
+  memory_id INTEGER,                -- the memory under consideration
+  ec_input_hash TEXT,               -- hash of the entorhinal-layer input (what's coming in now)
+  ca3_output_hash TEXT,             -- hash of the CA3 pattern-completion output (what we'd recall)
+  match_score REAL NOT NULL CHECK(match_score BETWEEN 0.0 AND 1.0),
+  novelty_score REAL NOT NULL CHECK(novelty_score BETWEEN 0.0 AND 1.0),
+  classification TEXT NOT NULL CHECK(classification IN ('match', 'mismatch', 'partial', 'ambiguous')),
+  notes TEXT
+);
+
+CREATE TABLE hippocampus_ca1_state (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  recent_match_rate REAL DEFAULT 0.5,      -- EWMA of recent match_score
+  recent_novelty_rate REAL DEFAULT 0.5,    -- EWMA of recent novelty_score
+  total_comparisons INTEGER DEFAULT 0,
+  last_comparison_at TEXT,
+  updated_at TEXT NOT NULL DEFAULT (...)
+);
+
+CREATE TABLE hippocampus_subiculum_outputs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  output_at TEXT NOT NULL DEFAULT (...),
+  agent_id TEXT,
+  memory_id INTEGER,
+  ca1_comparison_id INTEGER REFERENCES hippocampus_ca1_comparisons(id),
+  target_channel TEXT NOT NULL CHECK(target_channel IN ('cortex_general', 'workspace_broadcast', 'thalamus_relay', 'other')),
+  output_strength REAL NOT NULL DEFAULT 0.5 CHECK(output_strength BETWEEN 0.0 AND 1.0),
+  notes TEXT
+);
+```
+
+## Phase 1 MCP tools
+
+- `ca1_compare(memory_id, ec_input_hash, ca3_output_hash, classification)` — record one comparison; computes match_score/novelty_score from hash similarity (Phase 1 uses naive Hamming-distance hash compare; Phase 2 swaps to embedding-cosine)
+- `ca1_status` — current state + last 5 comparisons + 24h aggregate
+- `subiculum_output` — manually record a subiculum output event with target_channel
+- `ca1_subiculum_history(limit, since, agent_id, classification)` — paginated comparison + output history
+
+## DoD
+
+- Migration 071 applies cleanly to /tmp + live (with backup)
+- Single state row + tables exist
+- 4 MCP tools registered + discoverable
+- ≥6 tests passing
+- Branch pushed, PR open, NOT merged to main

src/agentmemory/mcp_server.py

@@ -56,6 +56,7 @@
         mcp_tools_federation,
         mcp_tools_health,
         mcp_tools_hippocampal_subfields,
+        mcp_tools_hippocampus_ca1,
         mcp_tools_immunity,
         mcp_tools_insula,
         mcp_tools_knowledge,
@@ -99,6 +100,7 @@
         mcp_tools_federation,
         mcp_tools_health,
         mcp_tools_hippocampal_subfields,
+        mcp_tools_hippocampus_ca1,
         mcp_tools_immunity,
         mcp_tools_insula,
         mcp_tools_knowledge,