lorekeeper-mcp 2.1.0__py3-none-any.whl

lorekeeper/__main__.py

@@ -0,0 +1,14 @@
+from lorekeeper.config import Settings
+from lorekeeper.logging_setup import configure_logging
+from lorekeeper.server import init_service, mcp
+
+
+def main() -> None:
+    settings = Settings()
+    configure_logging(log_dir=settings.log_dir)
+    init_service(settings)
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

lorekeeper/config.py

@@ -0,0 +1,78 @@
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="LORE_", case_sensitive=False)
+
+    data_dir: Path = Field(default=Path.home() / ".lorekeeper")
+    log_dir: Path = Field(default=Path.home() / ".lorekeeper" / "logs")
+    embedding_model: str = "sentence-transformers/all-MiniLM-L6-v2"
+    vector_store: str = "lancedb"  # "chroma" or "lancedb"
+    duplicate_threshold: float = 0.85
+
+    # Hybrid search weights (must sum to 1.0)
+    w_semantic: float = 0.45
+    w_keyword: float = 0.30
+    w_memory: float = 0.15
+    w_usage: float = 0.10
+
+    # Score delta
+    score_bump_up: float = 0.1
+    score_bump_down: float = 0.05
+    score_min: float = 0.0
+    score_max: float = 10.0
+    soft_delete_confidence_threshold: int = 2
+
+    # EMA
+    confidence_window_size: int = 20
+
+    search_limit: int = 5
+    max_links_per_memory: int = 5
+    max_search_ids: int = 50  # max IDs for lore_search(ids=[...]) — LORE_MAX_SEARCH_IDS
+    max_refine_from_ids: int = 200  # max IDs for refine_from — LORE_MAX_REFINE_FROM_IDS
+    usage_normalisation_cap: int = 100
+    decay_lambda: float = 0.0077  # time-decay λ; 0 disables decay (LORE_DECAY_LAMBDA)
+    new_memory_default_score: float = 5.0  # default score for new memories
+
+    namespace: str = Field(default="shared")  # LORE_NAMESPACE — agent write namespace + read scope
+
+    # Auto-link
+    auto_link_enabled: bool = True
+    auto_link_k: int = 5
+    auto_link_threshold: float = 0.85
+
+    # Link candidate pipeline (LKPR-58)
+    link_top_k: int = Field(default=50, description="Cosine pre-filter: top-K before scoring")
+    link_top_m: int = Field(default=10, description="Max candidates returned by lore_recommend_links")  # noqa: E501
+    link_score_threshold: float = Field(default=0.3, description="Min Stage 1 weighted score to pass")  # noqa: E501
+
+    # Stage 1 scorer weights
+    link_weight_cosine: float = Field(default=0.5)
+    link_weight_bm25: float = Field(default=0.3)
+    link_weight_entity: float = Field(default=0.1)
+    link_weight_temporal: float = Field(default=0.1)
+
+    # Temporal scorer
+    link_temporal_tau_days: float = Field(
+        default=30.0, description="Decay half-life in days for temporal scorer"
+    )
+
+    # spaCy entity overlap scorer
+    link_spacy_model: str = Field(
+        default="en_core_web_sm", description="spaCy model for entity overlap"
+    )
+
+    @property
+    def chroma_path(self) -> Path:
+        return self.data_dir / "chroma"
+
+    @property
+    def lancedb_path(self) -> str:
+        return str(self.data_dir / "lancedb")
+
+    @property
+    def sqlite_path(self) -> Path:
+        return self.data_dir / "lorekeeper.db"

lorekeeper/dashboard/__init__.py

@@ -0,0 +1,40 @@
+import argparse
+import os
+from pathlib import Path
+from typing import Any
+
+import uvicorn
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Lorekeeper Dashboard")
+    parser.add_argument(
+        "--data-dir",
+        type=str,
+        default=None,
+        help="Memory data directory (default: $LORE_DATA_DIR or ~/.lorekeeper)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("LORE_DASH_PORT", "7777")),
+        help="HTTP port (default: 7777, or $LORE_DASH_PORT)",
+    )
+    args = parser.parse_args()
+
+    port = args.port
+    reload = os.environ.get("LORE_DASH_RELOAD", "1").lower() not in ("0", "false", "no")
+
+    # --data-dir sets LORE_DATA_DIR so Settings() picks it up in both
+    # reload and no-reload modes (uvicorn reload spawns a child process).
+    if args.data_dir:
+        os.environ["LORE_DATA_DIR"] = str(Path(args.data_dir).resolve())
+
+    app_ref = "lorekeeper.dashboard.app:app" if reload else _import_app()
+    uvicorn.run(app_ref, host="127.0.0.1", port=port, reload=reload)
+
+
+def _import_app() -> Any:
+    from lorekeeper.dashboard.app import app
+
+    return app

lorekeeper/dashboard/__main__.py

@@ -0,0 +1,3 @@
+from lorekeeper.dashboard import main
+
+main()

lorekeeper/dashboard/app.py

@@ -0,0 +1,79 @@
+import subprocess
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+import structlog
+from fastapi import FastAPI
+from fastapi.responses import Response
+from fastapi.staticfiles import StaticFiles
+
+from lorekeeper.dashboard.routes import (
+    backup,
+    config,
+    links,
+    memories,
+    metrics,
+    reflections,
+    search,
+)
+from lorekeeper.server import init_service
+
+log = structlog.get_logger()
+STATIC_DIR = Path(__file__).parent / "static"
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+
+# Computed once at startup — not on every request
+_APP_VERSION: str = "unknown"
+
+
+def _resolve_version() -> str:
+    try:
+        result = subprocess.run(
+            ["git", "describe", "--always", "--dirty", "--tags"],
+            capture_output=True, text=True, cwd=REPO_ROOT, timeout=5,
+        )
+        return result.stdout.strip() or "unknown"
+    except Exception:
+        log.exception("version_resolve_failed")
+        return "unknown"
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    global _APP_VERSION
+    log.info("dashboard_startup")
+    _APP_VERSION = _resolve_version()
+    log.info("version_resolved", version=_APP_VERSION)
+    init_service()
+    log.info("dashboard_ready")
+    yield
+
+
+app = FastAPI(lifespan=lifespan, title="Lorekeeper Dashboard")
+
+# Serve css/, js/ subdirectories as static assets
+app.mount("/css", StaticFiles(directory=STATIC_DIR / "css"), name="css")
+app.mount("/js",  StaticFiles(directory=STATIC_DIR / "js"),  name="js")
+
+
+# ── Serve UI ──────────────────────────────────────────────────────────────────
+
+@app.get("/", include_in_schema=False)
+def index() -> Response:
+    html = (STATIC_DIR / "index.html").read_text(encoding="utf-8")
+    return Response(
+        content=html.replace("{%VERSION%}", _APP_VERSION),
+        media_type="text/html",
+    )
+
+
+# ── Route modules ─────────────────────────────────────────────────────────────
+
+app.include_router(memories.router)
+app.include_router(links.router)
+app.include_router(search.router)
+app.include_router(config.router)
+app.include_router(reflections.router)
+app.include_router(backup.router)
+app.include_router(metrics.router)

lorekeeper/dashboard/routes/backup.py

@@ -0,0 +1,57 @@
+import json
+from datetime import UTC, datetime
+from typing import Any
+
+from fastapi import APIRouter, File, HTTPException, UploadFile
+from fastapi.responses import Response
+
+from lorekeeper.models import Memory
+from lorekeeper.serializers import serialize_memory, serialize_memory_link
+from lorekeeper.server import get_service
+
+router = APIRouter()
+
+
+def _parse_dump(raw: bytes) -> tuple[list[Any], list[Any]]:
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, UnicodeDecodeError) as e:
+        raise HTTPException(status_code=422, detail=f"Invalid JSON: {e}") from e
+    if not isinstance(data.get("memories"), list) or not isinstance(data.get("links"), list):
+        raise HTTPException(status_code=422, detail='File must have "memories" and "links" arrays')
+    return data["memories"], data["links"]
+
+
+@router.get("/api/export")
+def export_dump(include_deleted: bool = False) -> Response:
+    svc = get_service()
+    now = datetime.now(UTC)
+    memories = [
+        serialize_memory(Memory(**dict(r)))
+        for r in svc.memories.all_memory_rows(include_deleted=include_deleted)
+    ]
+    links = [serialize_memory_link(lnk) for lnk in svc.links.all_links()]
+    payload = {
+        "version": "2",
+        "exported_at": now.isoformat(),
+        "memories": memories,
+        "links": links,
+    }
+    filename = f"lorekeeper-{now.strftime('%Y-%m-%d')}.json"
+    return Response(
+        content=json.dumps(payload, indent=2),
+        media_type="application/json",
+        headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+    )
+
+
+@router.post("/api/import/preview")
+async def import_preview(file: UploadFile = File(...)) -> dict[str, Any]:
+    memories, links = _parse_dump(await file.read())
+    return get_service().import_dump(memories, links, dry_run=True)
+
+
+@router.post("/api/import/confirm")
+async def import_confirm(file: UploadFile = File(...)) -> dict[str, Any]:
+    memories, links = _parse_dump(await file.read())
+    return get_service().import_dump(memories, links, dry_run=False)

lorekeeper/dashboard/routes/config.py

@@ -0,0 +1,97 @@
+import types
+from typing import Any, Union, get_args, get_origin
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from lorekeeper.server import get_service
+
+router = APIRouter()
+
+_READONLY_KEYS = {"data_dir", "embedding_model"}
+
+
+def _unwrap_optional(tp: Any) -> Any:
+    """Unwrap Optional[T] / Union[T, None] | T | None to T."""
+    origin = get_origin(tp)
+    if origin is Union or origin is types.UnionType:
+        args = get_args(tp)
+        non_none = [a for a in args if a is not type(None)]
+        return non_none[0] if len(non_none) == 1 else tp
+    return tp
+
+
+@router.get("/api/config")
+def get_config() -> dict[str, Any]:
+    s = get_service().settings
+    overridden_keys = set(get_service().config.get_overrides().keys())
+    return {
+        "data_dir": str(s.data_dir),
+        "embedding_model": s.embedding_model,
+        "duplicate_threshold": s.duplicate_threshold,
+        "w_semantic": s.w_semantic,
+        "w_keyword": s.w_keyword,
+        "w_memory": s.w_memory,
+        "w_usage": s.w_usage,
+        "score_bump_up": s.score_bump_up,
+        "score_bump_down": s.score_bump_down,
+        "score_min": s.score_min,
+        "score_max": s.score_max,
+        "soft_delete_confidence_threshold": s.soft_delete_confidence_threshold,
+        "confidence_window_size": s.confidence_window_size,
+        "search_limit": s.search_limit,
+        "max_links_per_memory": s.max_links_per_memory,
+        "usage_normalisation_cap": s.usage_normalisation_cap,
+        "decay_lambda": s.decay_lambda,
+        "new_memory_default_score": s.new_memory_default_score,
+        "auto_link_enabled": s.auto_link_enabled,
+        "auto_link_k": s.auto_link_k,
+        "auto_link_threshold": s.auto_link_threshold,
+        "_overridden_keys": sorted(overridden_keys),
+    }
+
+
+class ConfigUpdate(BaseModel):
+    duplicate_threshold: float | None = None
+    w_semantic: float | None = None
+    w_keyword: float | None = None
+    w_memory: float | None = None
+    w_usage: float | None = None
+    score_bump_up: float | None = None
+    score_bump_down: float | None = None
+    score_min: float | None = None
+    score_max: float | None = None
+    soft_delete_confidence_threshold: int | None = None
+    confidence_window_size: int | None = None
+    search_limit: int | None = None
+    max_links_per_memory: int | None = None
+    usage_normalisation_cap: int | None = None
+    decay_lambda: float | None = None
+    new_memory_default_score: float | None = None
+    auto_link_enabled: bool | None = None
+    auto_link_k: int | None = None
+    auto_link_threshold: float | None = None
+
+
+@router.patch("/api/config")
+def update_config(body: ConfigUpdate) -> dict[str, bool]:
+    """Update config overrides with type validation.
+    Read-only keys (data_dir, embedding_model) are silently skipped.
+    Returns 422 with detail on type mismatch.
+    """
+    _TYPE_MAP = {k: _unwrap_optional(v.annotation) for k, v in ConfigUpdate.model_fields.items()}
+    svc = get_service()
+    s = svc.settings
+    for key, value in body.model_dump(exclude_none=True).items():
+        if key in _READONLY_KEYS:
+            continue
+        expected = _TYPE_MAP.get(key)
+        if expected is not None and not isinstance(value, expected):
+            raise HTTPException(
+                status_code=422,
+                detail=f"Config '{key}' expects {expected.__name__}, got {type(value).__name__}",
+            )
+        setattr(s, key, value)
+        svc.config.set_override(key, value)
+    svc.commit()
+    return {"ok": True}

lorekeeper/dashboard/routes/links.py

@@ -0,0 +1,68 @@
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from lorekeeper.models import RelationType
+from lorekeeper.serializers import serialize_memory_link
+from lorekeeper.server import get_service
+
+router = APIRouter()
+
+
+class LinkCreate(BaseModel):
+    source_memory_id: str
+    target_memory_id: str
+    relation_type: RelationType
+    reason: str
+    score: float = 1.0
+
+
+@router.get("/api/links")
+def list_all_links(include_deleted: bool = False) -> list[dict[str, Any]]:
+    svc = get_service()
+    links = svc.links.all_links()
+    all_rows = svc.memories.all_memory_rows(include_deleted=True)
+    title_map = {r["id"]: r["title"] for r in all_rows}
+    deleted_ids = {r["id"] for r in all_rows if r["soft_deleted"]}
+    if not include_deleted:
+        links = [
+            lnk for lnk in links
+            if lnk.source_memory_id not in deleted_ids and lnk.target_memory_id not in deleted_ids
+        ]
+    return [
+        {
+            **serialize_memory_link(lnk),
+            "source_title": title_map.get(lnk.source_memory_id, lnk.source_memory_id[:12] + "…"),
+            "target_title": title_map.get(lnk.target_memory_id, lnk.target_memory_id[:12] + "…"),
+        }
+        for lnk in links
+    ]
+
+
+@router.post("/api/links", status_code=201)
+def create_link(body: LinkCreate) -> dict[str, Any]:
+    svc = get_service()
+    if svc.memories.get_memory_row(body.source_memory_id) is None:
+        raise HTTPException(status_code=404, detail="Source memory not found")
+    if svc.memories.get_memory_row(body.target_memory_id) is None:
+        raise HTTPException(status_code=404, detail="Target memory not found")
+    link = svc.links.insert_link(
+        source_memory_id=body.source_memory_id,
+        target_memory_id=body.target_memory_id,
+        relation_type=body.relation_type,
+        reason=body.reason,
+        score=body.score,
+    )
+    svc.commit()
+    return serialize_memory_link(link)
+
+
+@router.delete("/api/links/{link_id}")
+def delete_link(link_id: str) -> dict[str, bool]:
+    svc = get_service()
+    if svc.links.get_link(link_id) is None:
+        raise HTTPException(status_code=404, detail="Link not found")
+    svc.links.delete_link(link_id)
+    svc.commit()
+    return {"ok": True}

lorekeeper/dashboard/routes/memories.py

@@ -0,0 +1,70 @@
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from lorekeeper.models import Memory
+from lorekeeper.serializers import serialize_memory, serialize_memory_link
+from lorekeeper.server import get_service
+
+router = APIRouter()
+
+
+@router.get("/api/memories")
+def list_memories(include_deleted: bool = False) -> list[dict[str, Any]]:
+    svc = get_service()
+    rows = svc.memories.all_memory_rows(include_deleted=include_deleted)
+    link_counts: dict[str, int] = {}
+    for lnk in svc.links.all_links():
+        link_counts[lnk.source_memory_id] = link_counts.get(lnk.source_memory_id, 0) + 1
+        link_counts[lnk.target_memory_id] = link_counts.get(lnk.target_memory_id, 0) + 1
+    result = []
+    for r in rows:
+        mem = serialize_memory(Memory(**r))
+        mem["link_count"] = link_counts.get(r["id"], 0)
+        result.append(mem)
+    return result
+
+
+@router.get("/api/memories/{memory_id}")
+def get_memory(memory_id: str) -> dict[str, Any]:
+    svc = get_service()
+    row = svc.memories.get_memory_row(memory_id)
+    if row is None:
+        raise HTTPException(status_code=404, detail="Memory not found")
+    links = svc.links.links_for_memory(memory_id)
+    return {
+        "memory": serialize_memory(Memory(**dict(row))),
+        "links": [serialize_memory_link(lnk) for lnk in links],
+    }
+
+
+class MemoryUpdate(BaseModel):
+    title: str | None = None
+    description: str | None = None
+    content: str | None = None
+    score: float | None = None
+    soft_deleted: bool | None = None
+
+
+@router.patch("/api/memories/{memory_id}")
+def update_memory(memory_id: str, body: MemoryUpdate) -> dict[str, bool]:
+    svc = get_service()
+    if svc.memories.get_memory_row(memory_id) is None:
+        raise HTTPException(status_code=404, detail="Memory not found")
+    fields = body.model_dump(exclude_none=True)
+    if "soft_deleted" in fields:
+        fields["soft_deleted"] = int(fields["soft_deleted"])
+    svc.memories.update_memory_fields(memory_id, **fields)
+    svc.commit()
+    return {"ok": True}
+
+
+@router.delete("/api/memories/{memory_id}")
+def delete_memory(memory_id: str) -> dict[str, bool]:
+    svc = get_service()
+    if svc.memories.get_memory_row(memory_id) is None:
+        raise HTTPException(status_code=404, detail="Memory not found")
+    svc.memories.delete_memory_row(memory_id)
+    svc.commit()
+    return {"ok": True}

lorekeeper/dashboard/routes/metrics.py

@@ -0,0 +1,32 @@
+from typing import Any
+
+from fastapi import APIRouter
+
+from lorekeeper.server import get_service
+
+router = APIRouter()
+
+
+@router.get("/api/metrics")
+def get_metrics(hours: int = 24) -> dict[str, Any]:
+    """Return per-minute API call counts bucketed by tool, for the last `hours` hours."""
+    store = get_service().metrics
+    rows = store.get_metrics(hours=hours)
+    buckets: list[str] = []
+    tools: set[str] = set()
+    data: dict[str, dict[str, int]] = {}
+    for row in rows:
+        bucket = row["minute_bucket"]
+        tool = row["tool_name"]
+        count = row["count"]
+        tools.add(tool)
+        if bucket not in data:
+            data[bucket] = {}
+            buckets.append(bucket)
+        data[bucket][tool] = count
+    return {
+        "hours": hours,
+        "buckets": buckets,
+        "tools": sorted(tools),
+        "data": data,
+    }

lorekeeper/dashboard/routes/reflections.py

@@ -0,0 +1,52 @@
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+
+from lorekeeper.serializers import serialize_reflection, serialize_session
+from lorekeeper.server import get_service
+
+router = APIRouter()
+
+
+@router.get("/api/reflections")
+def list_reflections() -> list[dict[str, Any]]:
+    store = get_service().reflections
+    return [serialize_reflection(dict(r)) for r in store.all_reflections()]
+
+
+@router.get("/api/reflections/{reflection_id}")
+def get_reflection_detail(reflection_id: str) -> dict[str, Any]:
+    store = get_service().reflections
+    row = store.get_reflection(reflection_id)
+    if row is None:
+        raise HTTPException(status_code=404, detail="Reflection not found")
+    sessions = store.sessions_for_reflection(reflection_id)
+    return {
+        "reflection": serialize_reflection(dict(row)),
+        "sessions": [serialize_session(dict(s)) for s in sessions],
+    }
+
+
+@router.get("/api/sessions")
+def list_sessions(with_content: bool = True) -> list[dict[str, Any]]:
+    store = get_service().reflections
+    rows = store.sessions_with_content() if with_content else store.all_sessions()
+    return [serialize_session(dict(s)) for s in rows]
+
+
+@router.get("/api/sessions/{session_id}")
+def get_session_detail(session_id: str) -> dict[str, Any]:
+    store = get_service().reflections
+    row = store.get_session(session_id)
+    if row is None:
+        raise HTTPException(status_code=404, detail="Session not found")
+    reflection = None
+    if row["reflection_id"]:
+        ref_row = store.get_reflection(row["reflection_id"])
+        if ref_row:
+            reflection = {
+                "id": ref_row["id"],
+                "created_at": ref_row["created_at"],
+                "summary": ref_row["summary"],
+            }
+    return {"session": serialize_session(dict(row)), "reflection": reflection}

lorekeeper/dashboard/routes/search.py

@@ -0,0 +1,33 @@
+from typing import Any
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+from lorekeeper.serializers import serialize_search_result
+from lorekeeper.server import get_service
+
+router = APIRouter()
+
+
+class SearchRequest(BaseModel):
+    query: str
+    limit: int = 5
+    min_score: float = 0.1
+
+
+@router.post("/api/search")
+def search(body: SearchRequest) -> list[dict[str, Any]]:
+    results = get_service().search(
+        body.query, limit=body.limit, min_score=body.min_score, include_links=False
+    )
+    return [
+        serialize_search_result(
+            r,
+            truncate_content=300,
+            exclude_memory_fields={"created_at", "updated_at", "confidence", "confidence_count"},
+            exclude_relevance_fields={"decay_factor"},
+            round_relevance=4,
+            include_links=False,
+        )
+        for r in results
+    ]