lean-memory-console 0.2.0__py3-none-any.whl

lean_memory_console/routes/mcp.py

@@ -0,0 +1,186 @@
+"""Docker-mode streamable-HTTP MCP mount (/mcp) with bearer auth.
+
+The wrapper FastMCP is built stateless (json_response) so its Starlette app
+mounts into FastAPI without needing to own the server process. A thin ASGI
+wrapper enforces ``Authorization: Bearer <api_key>`` before delegating; full
+MCP-over-HTTP round-trips are exercised in the manual E2E (and, since the review,
+in a two-request automated test).
+
+Two SDK-1.28.1 decisions, both disclosed:
+
+1. Session-manager lifecycle — LIFESPAN ONLY.
+   ``streamable_http_app().handle_request`` raises
+   ``RuntimeError("Task group is not initialized. Make sure to use run().")``
+   until ``StreamableHTTPSessionManager.run()`` has been entered — even in
+   stateless mode. ``run()`` may be entered EXACTLY ONCE per instance: it sets
+   ``_has_started`` permanently and raises on a second call, and on exit it
+   resets ``_task_group`` to ``None`` (verified in the installed SDK at
+   ``mcp/server/streamable_http_manager.py``). A per-request self-start is
+   therefore broken beyond the first request. We expose ``session_manager`` and
+   the console's app lifespan (``app.create_app``) enters ``run()`` once for the
+   process lifetime. Consequence: tests that hit ``/mcp`` MUST drive the lifespan
+   — use ``with TestClient(app) as client:`` (a bare ``TestClient(app)`` does not
+   run the lifespan and would 500 on the first authenticated request).
+
+2. Transport security — DNS-rebinding protection ENABLED with a loopback
+   default allow-list, extendable via ``LM_MCP_ALLOWED_HOSTS``.
+   FastMCP validates Host and Origin headers to defeat DNS rebinding. The SDK
+   couples both checks behind a single ``enable_dns_rebinding_protection`` flag
+   and offers no host wildcard — only exact matches and ``base:*`` port patterns
+   (see ``mcp/server/transport_security.py``). We enable protection and enumerate
+   the loopback host/origin values a legitimate local client presents. This gives
+   real Origin restriction (a cross-site Origin → 403) while the bearer gate in
+   front remains the primary access control.
+
+   The shipped ``deploy/docker-compose.yml`` publishes 8377 directly (no reverse
+   proxy in the stack), so a container reached over the LAN presents a Host like
+   ``192.168.1.10:8377`` or ``myserver:8377`` that the loopback default does not
+   cover — it would 421. Remote-host deployments therefore set
+   ``LM_MCP_ALLOWED_HOSTS`` (comma-separated host patterns, e.g.
+   ``192.168.1.10:*,myserver:*``, parsed in ``config.py``); those patterns are
+   ADDED to the loopback defaults here. Origins stay restricted to loopback. We
+   extend rather than disable the flag, because disabling it also disables the
+   Origin check — losing the one control that matters for a browser-originated
+   DNS-rebinding attack. The bearer gate remains the primary control regardless.
+"""
+
+from __future__ import annotations
+
+import secrets
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+from mcp.server.transport_security import TransportSecuritySettings
+
+from ..config import ConsoleConfig
+from ..engine import EngineGateway
+from ..mcp_tools import register_maintenance_tools
+
+# Loopback host/origin default allow-list for the inner MCP transport-security
+# check. Host entries use the SDK's exact + ``base:*`` port-wildcard matching;
+# there is no host wildcard, so remote deployments extend this list via
+# LM_MCP_ALLOWED_HOSTS (see the module docstring, decision 2).
+_DEFAULT_ALLOWED_HOSTS = [
+    "127.0.0.1",
+    "127.0.0.1:*",
+    "localhost",
+    "localhost:*",
+    "[::1]",
+    "[::1]:*",
+]
+_ALLOWED_ORIGINS = [
+    "http://127.0.0.1",
+    "http://127.0.0.1:*",
+    "http://localhost",
+    "http://localhost:*",
+]
+
+
+def _build_http_mcp(
+    gateway: EngineGateway, extra_allowed_hosts: list[str] | None = None
+) -> FastMCP:
+    # Loopback defaults + any operator-supplied patterns (LM_MCP_ALLOWED_HOSTS),
+    # de-duplicated while preserving order.
+    allowed_hosts = list(_DEFAULT_ALLOWED_HOSTS)
+    for host in extra_allowed_hosts or []:
+        if host not in allowed_hosts:
+            allowed_hosts.append(host)
+    mcp = FastMCP(
+        "lean-memory-console",
+        stateless_http=True,
+        json_response=True,
+        streamable_http_path="/",
+        transport_security=TransportSecuritySettings(
+            enable_dns_rebinding_protection=True,
+            allowed_hosts=allowed_hosts,
+            allowed_origins=_ALLOWED_ORIGINS,
+        ),
+    )
+
+    @mcp.tool()
+    async def memory_add(
+        namespace: str,
+        text: str,
+        source: str = "user",
+        t_ref: int | None = None,
+    ) -> dict[str, Any]:
+        """Ingest text into the namespace's memory (HTTP wrapper)."""
+        res = await gateway.add(namespace, text, source=source, t_ref=t_ref)
+        return {
+            "fact_ids": res.fact_ids,
+            "superseded_count": res.superseded_count,
+        }
+
+    @mcp.tool()
+    async def memory_search(
+        namespace: str, query: str, k: int = 5
+    ) -> dict[str, Any]:
+        """Search a namespace's memory (HTTP wrapper); always latest-only."""
+        res = await gateway.search(
+            namespace, query, k=k, latest_only=True, origin="agent"
+        )
+        return {
+            "hits": [
+                {"fact_text": h["fact_text"], "final_score": h["final_score"]}
+                for h in res.hits
+            ]
+        }
+
+    # The same four maintenance tools as the stdio surfaces (§6.3). No review prompt
+    # here — MCP prompts are a stdio-client capability; HTTP clients use the tools.
+    register_maintenance_tools(mcp, gateway)
+
+    return mcp
+
+
+def build_mcp_mount(gateway: EngineGateway, config: ConsoleConfig):
+    """Return an ASGI app: bearer gate -> streamable-HTTP MCP app.
+
+    Mount at "/mcp"; the inner MCP app serves at its own root "/" once mounted
+    (FastMCP's ``streamable_http_path`` is "/" so it resolves at exactly the
+    mount point). The returned app exposes ``session_manager``; the caller MUST
+    enter its ``run()`` in the app lifespan (see module docstring, decision 1) —
+    there is no per-request fallback, because ``run()`` is once-only per instance.
+    """
+    mcp = _build_http_mcp(gateway, config.mcp_allowed_hosts)
+    inner = mcp.streamable_http_app()
+    session_manager = mcp.session_manager  # initializes it on the inner app
+    # None when no api_key is configured, so the constant-time compare below
+    # always fails (compare_digest is skipped for a None expected value).
+    expected = f"Bearer {config.api_key}" if config.api_key else None
+
+    async def gated(scope, receive, send):
+        if scope["type"] != "http":
+            await inner(scope, receive, send)
+            return
+        headers = dict(scope.get("headers") or [])
+        auth = headers.get(b"authorization", b"").decode()
+        # Constant-time bearer compare; both sides must be non-None strings.
+        if expected is None or not secrets.compare_digest(auth, expected):
+            await _send_401(send)
+            return
+        await inner(scope, receive, send)
+
+    # Exposed so create_app can drive the once-only session manager via the app
+    # lifespan (the only supported start path).
+    gated.session_manager = session_manager
+    return gated
+
+
+async def _send_401(send):
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 401,
+            "headers": [
+                (b"content-type", b"application/json"),
+                (b"referrer-policy", b"no-referrer"),
+            ],
+        }
+    )
+    await send(
+        {
+            "type": "http.response.body",
+            "body": b'{"detail":"unauthorized"}',
+        }
+    )

lean_memory_console/routes/review.py

@@ -0,0 +1,115 @@
+"""/views/*/review + /views/*/maintenance — the maintenance review-path router.
+
+Every route proxies a single ``EngineGateway`` maintenance method (WP10a): the
+engine is never opened directly here. Existence + reserved-namespace guarding is
+identical to the read-path router (``_ns_db``), so a review call against a
+nonexistent namespace 404s rather than creating the ``.db`` as a side effect.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from ..config import is_reserved_namespace, ns_db_path
+
+
+class DecideBody(BaseModel):
+    decision: str
+    edited_text: str | None = None
+
+
+class PromoteBody(BaseModel):
+    fact_id: str
+
+
+class RunBody(BaseModel):
+    apply: bool = False
+
+
+# The lifecycle CAS reports a re-decided proposal as an outcome, not an
+# exception (lifecycle.py:_already_decided) — surface those as 409 so the UI can
+# refresh the row, with the informative body passed through verbatim.
+_ALREADY_DECIDED = frozenset({"already_decided", "already_applied"})
+
+
+def _ns_db(request: Request, namespace: str):
+    if is_reserved_namespace(namespace):
+        raise HTTPException(status_code=404, detail="unknown namespace")
+    config = request.app.state.config
+    path = ns_db_path(config.data_root, namespace)
+    if not path.exists():
+        raise HTTPException(status_code=404, detail="unknown namespace")
+    return path
+
+
+def build_review_router() -> APIRouter:
+    # Imported here (not at module top) to break the app<->routes import cycle,
+    # exactly as build_views_router does: app.py imports this builder last, so
+    # require_auth is already defined by the time create_app calls it.
+    from ..app import require_auth
+
+    router = APIRouter(prefix="/views")
+
+    @router.get(
+        "/{namespace}/review/queue", dependencies=[Depends(require_auth)]
+    )
+    async def review_queue(
+        request: Request,
+        namespace: str,
+        kind: str | None = None,
+        limit: int = 20,
+    ):
+        _ns_db(request, namespace)
+        gateway = request.app.state.gateway
+        return await gateway.review_queue(namespace, kind=kind, limit=limit)
+
+    @router.post(
+        "/{namespace}/review/{proposal_id}/decide",
+        dependencies=[Depends(require_auth)],
+    )
+    async def decide(
+        request: Request,
+        namespace: str,
+        proposal_id: str,
+        body: DecideBody,
+    ):
+        _ns_db(request, namespace)
+        gateway = request.app.state.gateway
+        result = await gateway.decide(
+            namespace, proposal_id, body.decision,
+            edited_text=body.edited_text,
+        )
+        if result.get("outcome") in _ALREADY_DECIDED:
+            return JSONResponse(result, status_code=409)
+        return result
+
+    @router.post(
+        "/{namespace}/review/promote", dependencies=[Depends(require_auth)]
+    )
+    async def promote(request: Request, namespace: str, body: PromoteBody):
+        _ns_db(request, namespace)
+        gateway = request.app.state.gateway
+        return await gateway.promote(namespace, body.fact_id)
+
+    @router.get(
+        "/{namespace}/maintenance/status",
+        dependencies=[Depends(require_auth)],
+    )
+    async def maintenance_status(request: Request, namespace: str):
+        _ns_db(request, namespace)
+        gateway = request.app.state.gateway
+        return await gateway.maintenance_status(namespace)
+
+    @router.post(
+        "/{namespace}/maintenance/run", dependencies=[Depends(require_auth)]
+    )
+    async def maintenance_run(
+        request: Request, namespace: str, body: RunBody
+    ):
+        _ns_db(request, namespace)
+        gateway = request.app.state.gateway
+        return await gateway.maintain(namespace, apply=body.apply)
+
+    return router

lean_memory_console/routes/views.py

@@ -0,0 +1,153 @@
+"""/views/* — the human read-path router."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel, Field
+
+from ..config import is_reserved_namespace, ns_db_path
+from .. import inspect_sql
+
+
+class TestSearchBody(BaseModel):
+    query: str
+    k: int = Field(default=5, ge=1, le=200)
+
+
+def _ns_db(request: Request, namespace: str):
+    if is_reserved_namespace(namespace):
+        raise HTTPException(status_code=404, detail="unknown namespace")
+    config = request.app.state.config
+    path = ns_db_path(config.data_root, namespace)
+    if not path.exists():
+        raise HTTPException(status_code=404, detail="unknown namespace")
+    return path
+
+
+def build_views_router() -> APIRouter:
+    # Imported here (not at module top) to break the app<->views import cycle:
+    # app.py imports build_views_router as its last import, so require_auth is
+    # already defined by the time this function runs (create_app calls it).
+    from ..app import require_auth
+
+    router = APIRouter(prefix="/views")
+
+    @router.get("/whoami")
+    def whoami(request: Request):
+        config = request.app.state.config
+        from ..app import _is_authenticated
+        from ..engine import resolved_models_mode
+
+        auth = "bearer" if config.mode == "docker" else "token"
+        return {
+            "mode": config.mode,
+            "auth": auth,
+            "authenticated": _is_authenticated(request, config),
+            "data_root": str(config.data_root),
+            # Resolved retrieval-backend mode ("real"|"stub"), NOT the raw env:
+            # "stub" whenever the built Memory uses deterministic offline
+            # scores, so the UI can warn that semantic scores are stub-generated.
+            "models": resolved_models_mode(config),
+        }
+
+    @router.get("/namespaces", dependencies=[Depends(require_auth)])
+    def namespaces(request: Request):
+        config = request.app.state.config
+        event_log = request.app.state.event_log
+        return inspect_sql.list_namespaces(config.data_root, event_log)
+
+    @router.get("/{namespace}/facts", dependencies=[Depends(require_auth)])
+    def facts(
+        request: Request,
+        namespace: str,
+        latest_only: bool = True,
+        predicate: str | None = None,
+        entity: str | None = None,
+        min_salience: float | None = None,
+        q: str | None = None,
+        page: int = 1,
+        page_size: int = 50,
+    ):
+        path = _ns_db(request, namespace)
+        return inspect_sql.list_facts(
+            path,
+            latest_only=latest_only,
+            predicate=predicate,
+            entity=entity,
+            min_salience=min_salience,
+            q=q,
+            page=page,
+            page_size=page_size,
+        )
+
+    @router.get(
+        "/{namespace}/facts/{fact_id}", dependencies=[Depends(require_auth)]
+    )
+    def fact_detail(request: Request, namespace: str, fact_id: str):
+        path = _ns_db(request, namespace)
+        fact = inspect_sql.get_fact(path, fact_id)
+        if fact is None:
+            raise HTTPException(status_code=404, detail="unknown fact")
+        return fact
+
+    @router.get("/{namespace}/episodes", dependencies=[Depends(require_auth)])
+    def episodes(
+        request: Request, namespace: str, page: int = 1, page_size: int = 50
+    ):
+        path = _ns_db(request, namespace)
+        return inspect_sql.list_episodes(path, page=page, page_size=page_size)
+
+    @router.get(
+        "/{namespace}/episodes/{episode_id}",
+        dependencies=[Depends(require_auth)],
+    )
+    def episode_detail(request: Request, namespace: str, episode_id: str):
+        path = _ns_db(request, namespace)
+        ep = inspect_sql.get_episode(path, episode_id)
+        if ep is None:
+            raise HTTPException(status_code=404, detail="unknown episode")
+        return ep
+
+    @router.get("/{namespace}/entities", dependencies=[Depends(require_auth)])
+    def entities(
+        request: Request, namespace: str, page: int = 1, page_size: int = 50
+    ):
+        path = _ns_db(request, namespace)
+        return inspect_sql.list_entities(path, page=page, page_size=page_size)
+
+    @router.get("/{namespace}/events", dependencies=[Depends(require_auth)])
+    def events(
+        request: Request,
+        namespace: str,
+        kind: str | None = None,
+        page: int = 1,
+        page_size: int = 50,
+    ):
+        if kind is not None and kind not in ("add", "search"):
+            raise HTTPException(status_code=422, detail="invalid kind")
+        # events live in the sidecar, not a namespace .db — no _ns_db guard,
+        # but reserved namespaces are still rejected.
+        if is_reserved_namespace(namespace):
+            raise HTTPException(status_code=404, detail="unknown namespace")
+        event_log = request.app.state.event_log
+        return event_log.list_events(
+            namespace, kind=kind, page=page, page_size=page_size
+        )
+
+    @router.post(
+        "/{namespace}/test-search", dependencies=[Depends(require_auth)]
+    )
+    async def test_search(
+        request: Request, namespace: str, body: TestSearchBody
+    ):
+        # Guard existence (and reserved) exactly like _ns_db: a search against a
+        # nonexistent namespace must 404, NOT create the .db file as a side
+        # effect of the engine opening it.
+        _ns_db(request, namespace)
+        gateway = request.app.state.gateway
+        result = await gateway.search(
+            namespace, body.query, k=body.k, latest_only=True, origin="ui"
+        )
+        return {"hits": result.hits, "duration_ms": result.duration_ms}
+
+    return router

lean_memory_console-0.2.0.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: lean-memory-console
+Version: 0.2.0
+Summary: Agent-first read-only verification console for lean-memory
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115
+Requires-Dist: lean-memory
+Requires-Dist: mcp>=1.0
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: anyio>=4; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml; extra == 'dev'

lean_memory_console-0.2.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+lean_memory_console/__init__.py,sha256=Jg18i1Ur9fTFAdcvJgPwgDeXWxn8Wuywbeh1UmQ6qwI,97
+lean_memory_console/app.py,sha256=_PQPt0FcjleWmlT-m6ncLkIOpvupF8Hjs51LJ_5tFUc,6033
+lean_memory_console/cli.py,sha256=WBykbiX7aM2Mw1aXr4BFT4kUPfyzgl8UbQzPfOr1LA0,4864
+lean_memory_console/config.py,sha256=F1VlsSVpMV5HUPBw6Mq_tPsZYGRLIHNGZbK0qqyVfs0,4269
+lean_memory_console/engine.py,sha256=NHdDUc7h29ubijIK7oQ9WwDO3NKBX91MXTlsNLjLxTo,15001
+lean_memory_console/events.py,sha256=8huPjL4SZ2F1KqiEEat1-RV6U8TDzjFh5SDT9E_Hbjk,5027
+lean_memory_console/inspect_sql.py,sha256=TFnln9CnCxKIz4jCOQzhVGFiC8ikonXZxPXHwpSVqUk,11446
+lean_memory_console/mcp_tools.py,sha256=ecdr1SJqkfJJ2E4iIc-nC1ly5MWiv_n-mm7EH28762w,6985
+lean_memory_console/observe_mcp.py,sha256=mR5RfxBSParlfrtwNQjCg_afWLsOqK2ZA5k-StDynWs,2380
+lean_memory_console/deploy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lean_memory_console/routes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lean_memory_console/routes/data.py,sha256=lzneIzjohQpG5kOET0Ex108w83Lo4Xkt_SuICN3rt2U,1620
+lean_memory_console/routes/mcp.py,sha256=E_w98Ttp9umZoXX1bBrZuSu8MG0x8t6IXH23Cp_E9Ys,7686
+lean_memory_console/routes/review.py,sha256=V0byVoRhXCSetWkYGpwjsSdH2BOzi2V-oyOOh9-Lgnc,3828
+lean_memory_console/routes/views.py,sha256=AtqiBctCJoaXHRiVTChx0RIF08GEHjF7kB5QqsTZ0Ec,5664
+lean_memory_console/deploy/docker-compose.yml,sha256=DnRlp3KHRqXq2OZKTWptU7lOk6GiPPMzdnuEciT7-cw,1393
+lean_memory_console-0.2.0.dist-info/METADATA,sha256=cbn0cdmj28n0_K0Hi5PqcOwy1IrAM1wDd9E5zq_GtEY,447
+lean_memory_console-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+lean_memory_console-0.2.0.dist-info/entry_points.txt,sha256=Cs0A0akgNoDIfi7y5nZTd94zkSCXgNWhqyl5YF4H2Ow,69
+lean_memory_console-0.2.0.dist-info/RECORD,,

lean_memory_console-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

lean_memory_console-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lean-memory-console = lean_memory_console.cli:main