seren-memory 1.9.1__py3-none-any.whl

seren_memory/__init__.py

@@ -0,0 +1,25 @@
+"""
+SerenMemory - three-tier LLM memory with consolidation.
+
+The Halls of Memory: ShortTerm (working), NearTerm (open loops), LongTerm
+(consolidated). A small "consolidator" model does the dream-work of
+promoting what matters and letting the rest go.
+
+Standalone. Bring your own LLM (any OpenAI-compatible endpoint). Configure
+a couple of values and you've got a memory system that matters.
+"""
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+# Version flows from the git tag via setuptools-scm (written to _version.py
+# at build time and recorded in the installed package's metadata). No manual
+# bump, no sed step. The fallback only fires in a bare source checkout that
+# was never installed; do `pip install -e .` to resolve it.
+try:
+    __version__: str = _pkg_version("seren-memory")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev"
+
+from .app import create_app  # noqa: F401,E402
+from .config import load_config, MemoryConfig  # noqa: F401,E402

seren_memory/__main__.py

@@ -0,0 +1,42 @@
+"""
+Entry point: python -m seren_memory [--config path]
+
+Boots the FastAPI app with uvicorn using the resolved config.
+"""
+from __future__ import annotations
+
+import argparse
+
+import uvicorn
+
+from .app import create_app
+from .config import load_config
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="seren_memory",
+        description="SerenMemory - three-tier LLM memory with consolidation.")
+    parser.add_argument(
+        "--config", "-c", default=None,
+        help="Path to seren-memory.yaml (default: ./seren-memory.yaml or "
+             "$SEREN_MEMORY_CONFIG, falling back to built-in defaults).")
+    args = parser.parse_args()
+
+    cfg = load_config(args.config)
+    app = create_app(cfg)
+
+    print(f"[seren-memory] listening on {cfg.server.host}:{cfg.server.port}")
+    print(f"[seren-memory] auth: "
+          f"{'enabled' if cfg.server.bearer_token else 'DISABLED (no token)'}")
+
+    uvicorn.run(
+        app,
+        host=cfg.server.host,
+        port=cfg.server.port,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    main()

seren_memory/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.9.1'
+__version_tuple__ = version_tuple = (1, 9, 1)
+
+__commit_id__ = commit_id = None

seren_memory/app.py

@@ -0,0 +1,548 @@
+"""
+seren_memory.app
+════════════════════════════════════════════════════════════════════════
+
+The FastAPI application. Wires the store, routes, optional bearer auth, and
+the background consolidation loop.
+
+ENDPOINTS:
+    GET  /                      - service info + tier counts
+    GET  /health                - liveness
+    POST /short                 - add working memory       (free write)
+    GET  /short                 - list                     (debug)
+    DELETE /short/{id}          - remove                   (free)
+    POST /near                  - add open loop            (free write)
+    GET  /near                  - list                     (debug)
+    POST /near/{id}/complete    - mark intent done
+    DELETE /near/{id}           - abandon intent           (free)
+    GET  /long                  - list                     (read-open)
+    POST /long/{id}/forget      - flag for consolidator    (the Lacuna gate)
+    POST /search                - unified ranked recall
+    GET  /consolidator/status   - last run, recent runs, counts, config
+    POST /consolidate/run       - trigger consolidation now (manual / external mode)
+    POST /consolidate/wake      - restart the background loop if it died (thread mode)
+    POST /brief                 - submit a daily brief (steers consolidation)
+    GET  /brief                 - list recent briefs (debug / viewer)
+    POST /short/{id}/preserve   - mark for verbatim promotion (next cycle)
+    POST /short/{id}/promote    - immediate verbatim promotion (skip cycle)
+    GET  /drafts                - list consolidator drafts (model review queue)
+    GET  /drafts/{id}/chain     - all attempts for a cluster (for comparison)
+    POST /drafts/{id}/approve   - commit draft to long-term, archive shorts
+    POST /drafts/{id}/reject    - send critique; triggers redraft or requires_selection
+    POST /drafts/{id}/select    - commit best attempt when chain is requires_selection
+"""
+from __future__ import annotations
+
+import asyncio
+import hmac
+import time
+from contextlib import asynccontextmanager, AsyncExitStack
+from typing import Optional
+
+from fastapi import FastAPI, Body, Request, HTTPException
+from fastapi.responses import JSONResponse, FileResponse
+
+from .config import MemoryConfig, load_config
+from .collections import MemoryStore
+from .consolidator import Consolidator
+from .models.schemas import DailyBrief
+from .routes import short as short_routes
+from .routes import near as near_routes
+from .routes import long as long_routes
+from .routes import search as search_routes
+
+
+# Single source of truth for the version we report. Prefer the actually-
+# installed wheel's metadata (the setuptools-scm value baked at build time);
+# fall back to the package __version__ for an editable/dev checkout where the
+# dist metadata may be absent or stale. This kills the old drift where app.py
+# hardcoded a literal that the release process never touched.
+try:
+    from importlib.metadata import version as _pkg_version, PackageNotFoundError
+    try:
+        APP_VERSION = _pkg_version("seren-memory")
+    except PackageNotFoundError:
+        from . import __version__ as APP_VERSION
+except Exception:  # noqa: BLE001 - never let version lookup break startup
+    APP_VERSION = "0+unknown"
+
+
+def create_app(config: MemoryConfig | None = None, embedding_function=None,
+               _allow_store_reset: bool = False) -> FastAPI:
+    cfg = config or load_config()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        # -- Startup --
+        store = MemoryStore(cfg, embedding_function=embedding_function,
+                            _allow_reset=_allow_store_reset)
+        app.state.store = store
+        app.state.config = cfg
+        app.state.consolidator = Consolidator(store, cfg)
+        print(f"[seren-memory] store ready at {cfg.resolved_persist_dir()}")
+        print(f"[seren-memory] tiers: {store.counts()}")
+
+        # -- Optional MCP server --
+        # Mounted ONLY if the [mcp] extras are installed. The import is
+        # inside the try block so a missing `mcp` package falls back to
+        # pure-HTTP mode without crashing startup. One install option
+        # (`pip install seren-memory[mcp]`) enables the MCP route at /mcp
+        # alongside the existing HTTP API - same process, same port, same
+        # config, one sec-approval surface.
+        try:
+            from .mcp.server import mount_mcp_routes
+            mcp_server = mount_mcp_routes(app)
+        except ImportError as exc:
+            # `mcp` package not installed - pure HTTP mode. Quiet by
+            # design: this is the default install path, not an error.
+            mcp_server = None
+            print(f"[seren-memory] MCP extras not installed; HTTP-only mode ({exc})")
+        except Exception as exc:  # noqa: BLE001
+            # SDK installed but mount failed (version drift, transport
+            # mismatch, etc.) - log loudly but don't crash the service.
+            # HTTP API stays up; operator can investigate.
+            mcp_server = None
+            print(f"[seren-memory] MCP mount failed: {exc!r} - continuing without MCP")
+
+        # Background consolidation loop (thread mode only). External mode
+        # expects something to POST /consolidate/run on a schedule instead.
+        stop_event = None
+        if cfg.consolidator.enabled and cfg.consolidator.mode == "thread":
+            stop_event = asyncio.Event()
+            app.state._stop_event = stop_event
+
+            async def consolidation_loop():
+                interval = cfg.consolidator.interval_seconds
+                print(f"[seren-memory] consolidation loop active (every {interval}s)")
+                # Warmup delay so first run doesn't collide with startup.
+                try:
+                    await asyncio.wait_for(stop_event.wait(), timeout=60)
+                    return  # stopped during warmup
+                except asyncio.TimeoutError:
+                    pass
+                while not stop_event.is_set():
+                    try:
+                        # Run the (synchronous) consolidation off the event loop.
+                        await asyncio.to_thread(app.state.consolidator.run_once)
+                    except Exception as e:  # noqa: BLE001
+                        from .consolidator.service import ConsolidatorBusy
+                        if isinstance(e, ConsolidatorBusy):
+                            print(f"[seren-memory] scheduled tick skipped: {e}")
+                        else:
+                            print(f"[seren-memory] consolidation error: {e}")
+                    try:
+                        await asyncio.wait_for(stop_event.wait(), timeout=interval)
+                    except asyncio.TimeoutError:
+                        pass
+
+            def _start_loop():
+                t = asyncio.create_task(consolidation_loop())
+                app.state._consolidation_task = t
+                return t
+
+            _start_loop()
+            # Expose the loop starter for the wake endpoint.
+            app.state._start_consolidation_loop = _start_loop
+
+        # -- Run the MCP session manager's task group (Bug 2 fix) --
+        # The streamable-HTTP transport keeps its anyio task group alive in
+        # session_manager.run(); without entering it here every MCP request
+        # 500s with "Task group is not initialized". A mounted sub-app's own
+        # lifespan does NOT fire under Starlette, so this is the only place
+        # it can live. AsyncExitStack makes HTTP-only mode (mcp_server is
+        # None) a clean no-op - we enter nothing and just yield.
+        async with AsyncExitStack() as _mcp_stack:
+            session_manager = getattr(mcp_server, "session_manager", None)
+            if session_manager is not None:
+                await _mcp_stack.enter_async_context(session_manager.run())
+                print("[seren-memory] MCP session manager running")
+            yield
+
+        # -- Shutdown --
+        if stop_event is not None:
+            stop_event.set()
+            task = getattr(app.state, "_consolidation_task", None)
+            if task:
+                try:
+                    await task
+                except Exception:  # noqa: BLE001
+                    pass
+        # Release the ChromaDB client so SQLite handles are closed cleanly.
+        try:
+            app.state.store.close()
+        except Exception:  # noqa: BLE001
+            pass
+        print("[seren-memory] shut down")
+
+    app = FastAPI(
+        title="SerenMemory",
+        description="Three-tier LLM memory with consolidation. The Halls of Memory.",
+        version=APP_VERSION,
+        lifespan=lifespan,
+    )
+
+    # -- Optional bearer auth --
+    # Same trusted-LAN posture as the rest of Seren: if a token is set,
+    # enforce it on everything except / and /health. If empty, no auth.
+    @app.middleware("http")
+    async def bearer_auth(request: Request, call_next):
+        token = cfg.server.bearer_token
+        if token:
+            # /viewer serves the HTML shell - it must be public so the page
+            # loads even when a token is set. The viewer's own JS fetch calls
+            # hit the API routes (/short, /long, /drafts, etc.) which ARE
+            # protected, so the data is still gated behind the token.
+            public = request.url.path in ("/", "/health", "/viewer")
+            if not public:
+                auth = request.headers.get("authorization", "")
+                # Constant-time compare so the 401 path doesn't leak how many
+                # leading bytes of the token matched (stdlib hmac, same as the
+                # agent's auth). Encode to bytes so non-ASCII can't raise.
+                expected = f"Bearer {token}"
+                if not hmac.compare_digest(auth.encode("utf-8"),
+                                           expected.encode("utf-8")):
+                    return JSONResponse({"error": "unauthorized"}, status_code=401)
+        return await call_next(request)
+
+    # -- Info routes --
+    @app.get("/")
+    async def root(request: Request):
+        store = request.app.state.store
+        return {
+            "service": "SerenMemory",
+            "version": APP_VERSION,
+            "tiers": store.counts(),
+            "consolidator": {
+                "enabled": cfg.consolidator.enabled,
+                "mode": cfg.consolidator.mode,
+                "interval_seconds": cfg.consolidator.interval_seconds,
+            },
+        }
+
+    @app.get("/health")
+    async def health():
+        return {"ok": True, "ts": time.time()}
+
+    # -- The Halls viewer --
+    # Serves the introspection UI same-origin. This isn't just a debug tool -
+    # it's the window into the consolidator: are memories clustering sensibly,
+    # is near-term filling with stale loops, did a fact actually supersede the
+    # old one. Serving it FROM the memory service (rather than opening the
+    # file:// directly) also kills the CORS problem - the viewer's fetch calls
+    # are same-origin, so the browser doesn't block them.
+    @app.get("/viewer")
+    async def viewer():
+        # halls.html ships INSIDE the package (seren_memory/viewer/halls.html)
+        # so it travels with the wheel - Path(__file__).parent is the package
+        # dir whether running from a dev checkout or an installed site-packages.
+        from pathlib import Path
+        pkg_dir = Path(__file__).resolve().parent
+        candidates = [
+            pkg_dir / "viewer" / "halls.html",          # in-package (installed + dev)
+            pkg_dir.parent / "viewer" / "halls.html",    # repo-root (older dev layout)
+        ]
+        html_path = next((p for p in candidates if p.is_file()), None)
+        if html_path is None:
+            return JSONResponse(
+                {"error": "viewer not found",
+                 "hint": "halls.html missing from the package; reinstall or grab it from the repo"},
+                status_code=404)
+        return FileResponse(html_path, media_type="text/html")
+
+    # -- Consolidator operational status --
+    @app.get("/consolidator/status")
+    async def consolidator_status(request: Request):
+        """Operational snapshot: when did the consolidator last run, how did
+        it go, what's the current cluster state. Backs the MCP
+        get_consolidator_status tool and the Halls viewer's operational
+        panel. last_run is null if the consolidator has never run on this
+        deployment.
+        """
+        store = request.app.state.store
+        return {
+            "last_run": store.get_latest_run(),
+            "recent_runs": store.get_recent_runs(limit=10),
+            "latest_brief": store.get_latest_brief(),
+            "counts": store.counts(),
+            "config": {
+                "enabled": cfg.consolidator.enabled,
+                "mode": cfg.consolidator.mode,
+                "interval_seconds": cfg.consolidator.interval_seconds,
+            },
+        }
+
+    # -- Brief submission --
+    @app.post("/brief")
+    async def submit_brief(request: Request, brief: DailyBrief = Body(...)):
+        """Submit a daily brief. The main model calls this at the end of a
+        cycle. The consolidator reads the latest brief to steer its next
+        run. The brief is also itself a long-term candidate (a record of
+        'what we worked on')."""
+        store = request.app.state.store
+        saved = store.add_brief(brief)
+        return {"ok": True, "id": saved.id}
+
+    @app.get("/brief")
+    async def list_briefs(request: Request, limit: int = 20):
+        """List the most recent briefs, newest first. Backs the Halls
+        viewer's brief panel - lets you see steering history alongside
+        the tier collections."""
+        store = request.app.state.store
+        rows = store.get_recent_briefs(limit=limit)
+        return {"entries": rows, "count": len(rows)}
+
+    # -- Consolidator drafts (model review queue) --
+    @app.get("/drafts")
+    async def list_drafts(request: Request, limit: int = 20,
+                          status: Optional[str] = None):
+        """List consolidator drafts. Defaults to all statuses, newest first;
+        pass status=pending for the active review queue, approved/rejected
+        for history, or requires_selection when the redraft budget ran out.
+
+        Each draft carries source_short_ids (the cluster evidence), attempt
+        (1-based position in its redraft chain), cluster_id (shared across
+        all attempts for one cluster), and previous_draft_ids so the model
+        can compare the full chain before selecting.
+        """
+        store = request.app.state.store
+        rows = store.get_recent_drafts(limit=limit, status=status)
+        return {"entries": rows, "count": len(rows)}
+
+    @app.get("/drafts/{draft_id}/chain")
+    async def get_draft_chain(request: Request, draft_id: str):
+        """Return all synthesis attempts for the same cluster as draft_id,
+        ordered by attempt number (ascending). Use this to compare every
+        draft in a chain before selecting the best one via /select.
+        Returns 404 if draft_id is not found.
+        """
+        store = request.app.state.store
+        row = store._get_draft_row(draft_id)
+        if not row:
+            raise HTTPException(404, f"no draft '{draft_id}'")
+        cluster_id = row["metadata"].get("cluster_id", draft_id)
+        chain = store.get_drafts_by_cluster(cluster_id)
+        return {"cluster_id": cluster_id, "attempts": chain, "count": len(chain)}
+
+    @app.post("/drafts/{draft_id}/approve")
+    async def approve_draft(request: Request, draft_id: str,
+                            body: Optional[dict] = Body(None)):
+        """Approve a pending draft. Commits the synthesis to long-term and
+        archives the source shorts to pruned. Optional 'note' in body is
+        recorded with the approval.
+
+        Returns 404 if draft missing, 409 if already reviewed.
+        """
+        store = request.app.state.store
+        note = (body or {}).get("note")
+        result = store.approve_draft(draft_id, note=note)
+        if result is None:
+            existing = store._get_draft_row(draft_id)
+            if not existing:
+                raise HTTPException(404, f"no draft '{draft_id}'")
+            raise HTTPException(409,
+                f"draft '{draft_id}' already {existing['metadata'].get('status')}")
+        return {
+            "ok": True,
+            "draft_id": draft_id,
+            "long_term_id": result["long_term_id"],
+            "shorts_archived": result["shorts_archived"],
+        }
+
+    @app.post("/drafts/{draft_id}/reject")
+    async def reject_draft(request: Request, draft_id: str, body: dict = Body(...)):
+        """Reject a pending draft with a critique. The consolidator will
+        produce a new synthesis incorporating the critique (up to
+        max_redraft_attempts total tries). Once the limit is exhausted the
+        chain flips to requires_selection and the model must POST /select.
+
+        Body: {"critique": "<why this synthesis is wrong/incomplete>"}
+        Legacy key 'reason' is accepted as an alias.
+
+        Returns 400 if no critique, 404 if draft missing, 409 if already
+        reviewed. Response includes action ('redrafted' or
+        'requires_selection') and, when redrafting, the new draft_id.
+        """
+        critique = (body or {}).get("critique") or (body or {}).get("reason", "")
+        critique = critique.strip() if critique else ""
+        if not critique:
+            raise HTTPException(400, "a 'critique' is required to reject a draft")
+        store = request.app.state.store
+        cluster_meta = store.reject_draft(draft_id, critique)
+        if cluster_meta is None:
+            existing = store._get_draft_row(draft_id)
+            if not existing:
+                raise HTTPException(404, f"no draft '{draft_id}'")
+            raise HTTPException(409,
+                f"draft '{draft_id}' already {existing['metadata'].get('status')}")
+
+        # Trigger redraft (or flip to requires_selection) on the consolidator.
+        consolidator = request.app.state.consolidator
+        redraft_result = await asyncio.to_thread(
+            consolidator.redraft_cluster,
+            cluster_id=cluster_meta["cluster_id"],
+            rejected_draft_id=draft_id,
+            critique=critique,
+            attempt=cluster_meta["attempt"],
+            source_short_ids=cluster_meta["source_short_ids"],
+            brief_id_used=cluster_meta["brief_id_used"],
+            topic=cluster_meta["topic"],
+            evidence_count=cluster_meta["evidence_count"],
+        )
+        if redraft_result is None:
+            return {
+                "ok": True, "draft_id": draft_id,
+                "action": "rejected", "critique": critique,
+                "warning": "redraft synthesis failed; cluster stays in pool",
+            }
+        return {
+            "ok": True,
+            "draft_id": draft_id,
+            "action": redraft_result["action"],
+            "critique": critique,
+            "new_draft_id": redraft_result.get("draft_id"),
+            "attempt": redraft_result["attempt"],
+        }
+
+    @app.post("/drafts/{draft_id}/select")
+    async def select_draft(request: Request, draft_id: str,
+                           body: Optional[dict] = Body(None)):
+        """Commit the best attempt from a requires_selection chain to
+        long-term. The selected draft is approved and all sibling attempts
+        are marked rejected. Source shorts are archived to pruned.
+
+        Body (optional):
+            {
+              "edited_content": "<revised text to commit instead of the draft>",
+              "note": "<freeform note on the selection>"
+            }
+
+        edited_content is the editor's safety valve: when all redraft
+        attempts are unsatisfactory, the editor picks the best of the chain
+        and can revise it before commit. If edited_content is omitted (or
+        None), the draft commits as-is. The original draft's content is
+        preserved on the draft row (and copied into the long-term entry's
+        extra dict) so the audit trail stays intact - we can always answer
+        "what did the consolidator originally synthesize" even after edit.
+
+        Edit is only available on this path (not on approve), which keeps
+        the iteration loop discipline: if you want to tweak during the loop,
+        reject with a critique and let the consolidator re-synthesize. Edit
+        is the terminal-state release valve, not a shortcut.
+
+        Call GET /drafts/{id}/chain first to compare all attempts, then
+        POST /select on the one judged best (optionally with edits).
+
+        Returns 400 if edited_content is provided as blank/whitespace,
+        404 if draft missing, 409 if not in requires_selection state.
+        Response includes 'edited' (bool) and 'edit_delta_chars' (int) so
+        the operator can see the magnitude of any revision at a glance.
+        """
+        body = body or {}
+        edited_content = body.get("edited_content")
+        note = body.get("note")
+
+        # Empty edits are a bug, not "no edit". Reject explicitly so the
+        # editor can't accidentally commit a blank long-term entry.
+        if edited_content is not None:
+            if not isinstance(edited_content, str) or not edited_content.strip():
+                raise HTTPException(
+                    400,
+                    "edited_content must be a non-empty string; omit the field "
+                    "to commit the draft as-is")
+
+        store = request.app.state.store
+        result = store.select_draft(draft_id, note=note,
+                                    edited_content=edited_content)
+        if result is None:
+            existing = store._get_draft_row(draft_id)
+            if not existing:
+                raise HTTPException(404, f"no draft '{draft_id}'")
+            status = existing["metadata"].get("status")
+            raise HTTPException(409,
+                f"draft '{draft_id}' is '{status}', not requires_selection")
+        return {
+            "ok": True,
+            "draft_id": draft_id,
+            "long_term_id": result["long_term_id"],
+            "shorts_archived": result["shorts_archived"],
+            "edited": result["edited"],
+            "edit_delta_chars": result["edit_delta_chars"],
+        }
+
+    # -- Short-term agency endpoints (preserve_verbatim + promote_memory) --
+    @app.post("/short/{entry_id}/preserve")
+    async def preserve_short_verbatim(request: Request, entry_id: str):
+        """Mark a short-term entry to be promoted VERBATIM (no synthesis,
+        no fusion) on the next consolidator cycle. Also pins it so it
+        survives aging until the cycle runs. Returns 404 if not found."""
+        store = request.app.state.store
+        ok = store.update_short_metadata(entry_id, {"verbatim": True, "pinned": True})
+        if not ok:
+            raise HTTPException(
+                status_code=404,
+                detail=f"short-term entry '{entry_id}' not found")
+        return {"ok": True, "id": entry_id, "verbatim": True, "pinned": True}
+
+    @app.post("/short/{entry_id}/promote")
+    async def promote_short_immediately(request: Request, entry_id: str):
+        """Immediately move a short-term entry to long-term verbatim,
+        bypassing the consolidator cycle entirely. The 'I know this is
+        durable, don't make me wait' override. Returns 404 if not found."""
+        store = request.app.state.store
+        long_id = store.promote_short_to_long(entry_id)
+        if long_id is None:
+            raise HTTPException(
+                status_code=404,
+                detail=f"short-term entry '{entry_id}' not found")
+        return {"ok": True, "long_term_id": long_id, "removed_short_id": entry_id}
+
+    # -- Manual consolidation trigger + wake --
+    @app.post("/consolidate/run")
+    async def consolidate_now(request: Request):
+        """Run a consolidation pass right now. Used in 'external' mode (a
+        cron/systemd timer POSTs here) or for manual testing. Runs the
+        synchronous consolidation in a thread so we don't block the loop.
+
+        Returns 409 if a scheduled run is already in progress.
+        """
+        from .consolidator.service import ConsolidatorBusy
+        try:
+            report = await asyncio.to_thread(
+                request.app.state.consolidator.run_once)
+        except ConsolidatorBusy as exc:
+            raise HTTPException(status_code=409, detail=str(exc))
+        return {"ok": True, "report": report}
+
+    @app.post("/consolidate/wake")
+    async def wake_consolidator(request: Request):
+        """Restart the background consolidation loop if it has died or is not
+        running. No-op when mode is 'external' (there is no loop to wake).
+        Returns 'already_running' if the task is still alive, 'woken' if it
+        was restarted, or 'not_applicable' in external mode.
+        """
+        cfg = request.app.state.config
+        if not cfg.consolidator.enabled or cfg.consolidator.mode != "thread":
+            return {"ok": True, "status": "not_applicable",
+                    "detail": "consolidator is in external mode; POST /consolidate/run to trigger"}
+
+        task: Optional[asyncio.Task] = getattr(request.app.state,
+                                               "_consolidation_task", None)
+        if task is not None and not task.done():
+            return {"ok": True, "status": "already_running"}
+
+        starter = getattr(request.app.state, "_start_consolidation_loop", None)
+        if starter is None:
+            return {"ok": False, "status": "error",
+                    "detail": "loop starter not available; restart the service"}
+
+        starter()
+        return {"ok": True, "status": "woken",
+                "detail": "background consolidation loop restarted"}
+
+    # -- Tier routes --
+    app.include_router(short_routes.router)
+    app.include_router(near_routes.router)
+    app.include_router(long_routes.router)
+    app.include_router(search_routes.router)
+
+    return app