feat(checkpoint-split): route checkpoints to dedicated collection (phases A–C)

Implements the structural fix promoted by the 2026-04-25 Cat 9 A/B
(632 vs 3 tokens per query): Stop-hook auto-save checkpoint diary
entries no longer share an index with content drawers.

Phase A — scaffolding (no behavior change):
- _SESSION_RECOVERY_COLLECTION constant + get_session_recovery_collection()
  in palace.py, mirroring get_collection's shape (cosine + thread-pin).
- New tests/test_session_recovery.py: 3 tests covering constant, metadata,
  multi-collection coexistence on one palace.

Phase B — write routing (the behavior change):
- tool_diary_write routes topic in _CHECKPOINT_TOPICS to the recovery
  collection; everything else stays in the main collection.
- _get_session_recovery_collection() in mcp_server.py with parallel cache.
- conftest._reset_mcp_cache resets the new cache between tests.
- 4 tests in TestCheckpointRouting — checkpoint→recovery, auto-save→recovery,
  general→main, search regression (checkpoints structurally invisible to
  mempalace_search now, not merely post-filtered).

Phase C — new read path:
- tool_session_recovery_read reads from the recovery collection only,
  with optional filters: session_id, agent, since, until, wing, limit.
- session_id added as optional metadata field on tool_diary_write so
  recovery reads can filter by Claude Code session.
- Defensive None-metadata handling per the MemPalace#999 / MemPalace#1094 / MemPalace#1201 family.
- Registered in TOOLS dict + documented in website/reference/mcp-tools.md
  (test_no_undocumented_tools regression caught the missing doc; fixed).
- 5 tests in TestSessionRecoveryRead — empty case, session_id filter,
  agent filter, limit, None-metadata defense.

Phases D (migration of existing checkpoints out of main collection) and
E (palace-daemon startup integration) explicitly deferred — multi-day
work, gated on a separate go-ahead.

Full suite 1360/1360 pass; 106 benchmark/stress deselected per default.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jphein

mempalace/mcp_server.py

@@ -59,7 +59,8 @@
 from .version import __version__  # noqa: E402
 from .backends.chroma import ChromaBackend, ChromaCollection, _pin_hnsw_threads  # noqa: E402
 from .query_sanitizer import sanitize_query  # noqa: E402
-from .searcher import search_memories  # noqa: E402
+from .searcher import _CHECKPOINT_TOPICS, search_memories  # noqa: E402
+from .palace import _SESSION_RECOVERY_COLLECTION  # noqa: E402
 from .palace_graph import (  # noqa: E402
     traverse,
     find_tunnels,
@@ -105,6 +106,7 @@ def _parse_args():
 
 _client_cache = None
 _collection_cache = None
+_recovery_collection_cache = None
 _palace_db_inode = 0  # inode of chroma.sqlite3 at cache time
 _palace_db_mtime = 0.0  # mtime of chroma.sqlite3 at cache time
 
@@ -174,6 +176,7 @@ def _get_client():
     global \
         _client_cache, \
         _collection_cache, \
+        _recovery_collection_cache, \
         _palace_db_inode, \
         _palace_db_mtime, \
         _metadata_cache, \
@@ -204,6 +207,7 @@ def _get_client():
     if _client_cache is None or inode_changed or mtime_changed:
         _client_cache = ChromaBackend.make_client(_config.palace_path)
         _collection_cache = None
+        _recovery_collection_cache = None
         _metadata_cache = None
         _metadata_cache_time = 0
         _palace_db_inode = current_inode
@@ -243,6 +247,37 @@ def _get_collection(create=False):
         return None
 
 
+def _get_session_recovery_collection(create=False):
+    """Return the session-recovery collection, caching between calls.
+
+    Stop-hook checkpoint diary entries route here instead of the main
+    ``mempalace_drawers`` collection so they don't dominate
+    ``mempalace_search`` results. Mirrors :func:`_get_collection`'s
+    shape (same client cache, same ``_pin_hnsw_threads`` retrofit).
+    """
+    global _recovery_collection_cache
+    try:
+        client = _get_client()
+        if create:
+            raw = client.get_or_create_collection(
+                _SESSION_RECOVERY_COLLECTION,
+                metadata={"hnsw:space": "cosine", "hnsw:num_threads": 1},
+            )
+            _pin_hnsw_threads(raw)
+            _recovery_collection_cache = ChromaCollection(
+                raw, palace_path=_config.palace_path
+            )
+        elif _recovery_collection_cache is None:
+            raw = client.get_collection(_SESSION_RECOVERY_COLLECTION)
+            _pin_hnsw_threads(raw)
+            _recovery_collection_cache = ChromaCollection(
+                raw, palace_path=_config.palace_path
+            )
+        return _recovery_collection_cache
+    except Exception:
+        return None
+
+
 def _no_palace():
     return {
         "error": "No palace found",
@@ -932,13 +967,25 @@ def tool_kg_stats():
 # ==================== AGENT DIARY ====================
 
 
-def tool_diary_write(agent_name: str, entry: str, topic: str = "general", wing: str = ""):
+def tool_diary_write(
+    agent_name: str,
+    entry: str,
+    topic: str = "general",
+    wing: str = "",
+    session_id: str = "",
+):
     """
     Write a diary entry for this agent. Entries are timestamped and
     accumulate over time in a diary room.
 
     This is the agent's personal journal — observations, thoughts,
     what it worked on, what it noticed, what it thinks matters.
+
+    When ``topic`` is a checkpoint topic (``checkpoint`` / ``auto-save``)
+    the entry is routed to the dedicated ``mempalace_session_recovery``
+    collection so it doesn't dominate ``mempalace_search`` results.
+    Pass ``session_id`` to enable filtering checkpoints by session via
+    ``mempalace_session_recovery_read``.
     """
     try:
         agent_name = sanitize_name(agent_name, "agent_name")
@@ -951,7 +998,13 @@ def tool_diary_write(agent_name: str, entry: str, topic: str = "general", wing:
     else:
         wing = f"wing_{agent_name.lower().replace(' ', '_')}"
     room = "diary"
-    col = _get_collection(create=True)
+    # Stop-hook auto-save checkpoint entries land in the dedicated
+    # session-recovery collection so they don't dominate vector ranking
+    # in mempalace_search. Read via mempalace_session_recovery_read.
+    if topic in _CHECKPOINT_TOPICS:
+        col = _get_session_recovery_collection(create=True)
+    else:
+        col = _get_collection(create=True)
     if not col:
         return _no_palace()
 
@@ -976,21 +1029,22 @@ def tool_diary_write(agent_name: str, entry: str, topic: str = "general", wing:
         # semantic search quality. For now, store raw AAAK in metadata so it's
         # preserved, and keep the document as-is for embedding (even though
         # compressed AAAK degrades embedding quality).
+        meta = {
+            "wing": wing,
+            "room": room,
+            "hall": "hall_diary",
+            "topic": topic,
+            "type": "diary_entry",
+            "agent": agent_name,
+            "filed_at": now.isoformat(),
+            "date": now.strftime("%Y-%m-%d"),
+        }
+        if session_id:
+            meta["session_id"] = session_id
         col.add(
             ids=[entry_id],
             documents=[entry],
-            metadatas=[
-                {
-                    "wing": wing,
-                    "room": room,
-                    "hall": "hall_diary",
-                    "topic": topic,
-                    "type": "diary_entry",
-                    "agent": agent_name,
-                    "filed_at": now.isoformat(),
-                    "date": now.strftime("%Y-%m-%d"),
-                }
-            ],
+            metadatas=[meta],
         )
         logger.info(f"Diary entry: {entry_id} → {wing}/diary/{topic}")
         return {
@@ -1069,6 +1123,102 @@ def tool_diary_read(agent_name: str, last_n: int = 10, wing: str = ""):
         return {"error": "Failed to read diary entries"}
 
 
+def tool_session_recovery_read(
+    session_id: str = "",
+    agent: str = "",
+    since: str = "",
+    until: str = "",
+    wing: str = "",
+    limit: int = 50,
+):
+    """
+    Read Stop-hook auto-save checkpoint entries from the dedicated
+    ``mempalace_session_recovery`` collection. Used for session
+    recovery, hook auditing, and "what was I doing 2 hours ago" lookup.
+
+    All filters are optional — empty string / zero means "no filter":
+
+    - ``session_id``: only entries written under this Claude Code session
+    - ``agent``: only entries from this agent (typically ``session-hook``)
+    - ``since`` / ``until``: ISO date strings, inclusive bounds on filed_at
+    - ``wing``: only entries from this project wing
+    - ``limit``: maximum number of entries to return (default 50, max 500)
+
+    Entries are returned sorted by ``filed_at`` descending (newest first).
+    """
+    try:
+        if agent:
+            agent = sanitize_name(agent, "agent")
+        if wing:
+            wing = sanitize_name(wing)
+    except ValueError as e:
+        return {"error": str(e), "entries": [], "total": 0}
+
+    limit = max(1, min(int(limit), 500))
+    col = _get_session_recovery_collection()
+    if not col:
+        # Recovery collection has never been created — no checkpoints
+        # have been written yet via the new routing. Return empty rather
+        # than erroring; caller's most likely interpretation is "no
+        # session-recovery data exists yet".
+        return {"entries": [], "total": 0}
+
+    # Build metadata where-clause from non-empty filters. ChromaDB needs
+    # a single condition or an explicit $and — we assemble accordingly.
+    conditions = []
+    if session_id:
+        conditions.append({"session_id": session_id})
+    if agent:
+        conditions.append({"agent": agent})
+    if wing:
+        conditions.append({"wing": wing})
+
+    where = None
+    if len(conditions) == 1:
+        where = conditions[0]
+    elif len(conditions) > 1:
+        where = {"$and": conditions}
+
+    try:
+        kwargs = {"include": ["documents", "metadatas"], "limit": 10000}
+        if where is not None:
+            kwargs["where"] = where
+        results = col.get(**kwargs)
+    except Exception:
+        logger.exception("session_recovery_read failed")
+        return {"error": "Failed to read recovery entries", "entries": [], "total": 0}
+
+    if not results.get("ids"):
+        return {"entries": [], "total": 0}
+
+    entries = []
+    for doc, meta in zip(results["documents"], results["metadatas"]):
+        # Defensive: ChromaDB may return None metadata for legacy /
+        # partial-write drawers (cf. #999, #1094, #1201). Coerce to {}.
+        meta = meta or {}
+        filed_at = meta.get("filed_at", "") or ""
+        if since and filed_at and filed_at < since:
+            continue
+        if until and filed_at and filed_at > until:
+            continue
+        entries.append(
+            {
+                "date": meta.get("date", ""),
+                "timestamp": filed_at,
+                "topic": meta.get("topic", ""),
+                "agent": meta.get("agent", ""),
+                "wing": meta.get("wing", ""),
+                "session_id": meta.get("session_id", ""),
+                "content": doc,
+            }
+        )
+
+    entries.sort(key=lambda x: x["timestamp"], reverse=True)
+    entries = entries[:limit]
+
+    return {"entries": entries, "total": len(entries)}
+
+
 def tool_hook_settings(silent_save: bool = None, desktop_toast: bool = None):
     """
     Get or set hook behavior settings.
@@ -1564,6 +1714,46 @@ def tool_reconnect():
         },
         "handler": tool_diary_read,
     },
+    "mempalace_session_recovery_read": {
+        "description": (
+            "Read Stop-hook auto-save checkpoint entries from the dedicated "
+            "session-recovery collection. Use for session recovery, hook "
+            "auditing, or 'what was I doing 2 hours ago' lookup. Filters are "
+            "all optional; empty string / 0 means 'no filter'. Returns "
+            "entries newest-first."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "session_id": {
+                    "type": "string",
+                    "description": "Filter by Claude Code session id.",
+                },
+                "agent": {
+                    "type": "string",
+                    "description": "Filter by agent name (typically 'session-hook').",
+                },
+                "since": {
+                    "type": "string",
+                    "description": "ISO datetime string — entries strictly newer than this.",
+                },
+                "until": {
+                    "type": "string",
+                    "description": "ISO datetime string — entries strictly older than this.",
+                },
+                "wing": {
+                    "type": "string",
+                    "description": "Filter by project wing.",
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Max entries to return (default 50, max 500).",
+                },
+            },
+            "required": [],
+        },
+        "handler": tool_session_recovery_read,
+    },
     "mempalace_hook_settings": {
         "description": (
             "Get or set hook behavior. silent_save: True = save directly "

mempalace/palace.py

@@ -71,6 +71,23 @@ def get_closets_collection(palace_path: str, create: bool = True):
     return get_collection(palace_path, collection_name="mempalace_closets", create=create)
 
 
+# Stop-hook auto-save checkpoint diary entries are routed to this
+# dedicated collection so they don't dominate ``mempalace_search``
+# results in the main ``mempalace_drawers`` collection. Read via the
+# ``mempalace_session_recovery_read`` MCP tool. See
+# ``docs/superpowers/specs/2026-04-25-checkpoint-collection-split.md``.
+_SESSION_RECOVERY_COLLECTION = "mempalace_session_recovery"
+
+
+def get_session_recovery_collection(palace_path: str, create: bool = True):
+    """Get the session-recovery collection — Stop-hook checkpoint storage."""
+    return get_collection(
+        palace_path,
+        collection_name=_SESSION_RECOVERY_COLLECTION,
+        create=create,
+    )
+
+
 CLOSET_CHAR_LIMIT = 1500  # fill closet until ~1500 chars, then start a new one
 CLOSET_EXTRACT_WINDOW = 5000  # how many chars of source content to scan for entities/topics
 

tests/conftest.py

@@ -44,6 +44,7 @@ def _clear_cache():
 
             mcp_server._client_cache = None
             mcp_server._collection_cache = None
+            mcp_server._recovery_collection_cache = None
         except (ImportError, AttributeError):
             pass