@dinasor/mnemo-cli 0.0.1

package/scripts/memory/installer/templates/autonomy/reranker.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""
+reranker.py - Score-fusion reranker for Mnemo retrieval.
+
+Combines four signals into a final relevance score:
+  1. Semantic similarity (cosine distance from vector search)
+  2. Authority weight  (memory_type hierarchy)
+  3. Temporal relevance (recency decay for episodic, boost for time queries)
+  4. Entity consistency (bonus when queried entity found in unit's entity_tags)
+
+Output is a sorted list of RankedResult objects ready for context packing.
+"""
+import re
+import time
+import sqlite3
+from dataclasses import dataclass
+from typing import Optional
+
+from autonomy.schema import get_db
+
+# Score fusion weights (must sum to 1.0)
+W_SEMANTIC   = 0.55
+W_AUTHORITY  = 0.25
+W_TEMPORAL   = 0.10
+W_ENTITY     = 0.10
+
+# Temporal decay half-life in days for episodic memory
+EPISODIC_HALF_LIFE_DAYS = 30.0
+
+# Time-sensitive query keywords
+TIME_WORDS = frozenset({
+    "today", "yesterday", "last week", "last month", "recent", "latest",
+    "just", "now", "currently", "this week", "this month",
+})
+
+
+@dataclass
+class RankedResult:
+    ref_path: str
+    content: str
+    source_file: str
+    semantic_score: float
+    authority_score: float
+    temporal_score: float
+    entity_score: float
+    final_score: float
+    memory_type: str
+    route_intent: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "ref_path": self.ref_path,
+            "content": self.content[:500],
+            "final_score": round(self.final_score, 4),
+            "semantic": round(self.semantic_score, 3),
+            "authority": round(self.authority_score, 3),
+            "temporal": round(self.temporal_score, 3),
+            "entity": round(self.entity_score, 3),
+            "memory_type": self.memory_type,
+        }
+
+
+def _temporal_score(time_scope: str, updated_at_ts: Optional[float], query: str) -> float:
+    """Calculate temporal relevance score [0, 1]."""
+    if time_scope == "atemporal":
+        return 0.8  # timeless facts always moderately relevant
+
+    has_time_query = any(tw in query.lower() for tw in TIME_WORDS)
+
+    if time_scope == "recency-sensitive" and updated_at_ts:
+        age_days = (time.time() - updated_at_ts) / 86400.0
+        # Exponential decay: fresh = high score, stale = low
+        import math
+        decay = math.exp(-0.693 * age_days / EPISODIC_HALF_LIFE_DAYS)
+        if has_time_query:
+            return min(decay * 1.5, 1.0)  # extra boost for time queries
+        return decay
+
+    if time_scope == "time-bound":
+        return 0.6  # neutral for general content
+
+    return 0.5
+
+
+def _entity_score(entity_tags_json: str, query: str, db: sqlite3.Connection) -> float:
+    """Calculate entity match bonus [0, 1]."""
+    if not entity_tags_json or entity_tags_json == "[]":
+        return 0.0
+    try:
+        import json
+        entity_ids = json.loads(entity_tags_json)
+    except Exception:
+        return 0.0
+
+    if not entity_ids:
+        return 0.0
+
+    # Get entity names for these IDs
+    placeholders = ",".join("?" * len(entity_ids))
+    rows = db.execute(
+        f"SELECT entity_name FROM entities WHERE entity_id IN ({placeholders})",
+        entity_ids,
+    ).fetchall()
+
+    q_lower = query.lower()
+    for row in rows:
+        name_lower = row["entity_name"].lower()
+        if name_lower in q_lower or any(
+            part in q_lower for part in name_lower.split("_") if len(part) > 3
+        ):
+            return 1.0
+
+    # Alias check
+    alias_rows = db.execute(
+        f"""
+        SELECT alias_text FROM entity_aliases
+        WHERE entity_id IN ({placeholders})
+        """,
+        entity_ids,
+    ).fetchall()
+    for row in alias_rows:
+        if row["alias_text"].lower() in q_lower:
+            return 0.8
+
+    return 0.0
+
+
+class ScoreFusionReranker:
+    def __init__(self, db: Optional[sqlite3.Connection] = None):
+        self.db = db or get_db()
+
+    def rerank(
+        self,
+        query: str,
+        raw_results: list[dict],  # {ref_path, content, source_file, distance, memory_type?, time_scope?, entity_tags?}
+        top_k: int = 5,
+        route_intent: str = "",
+    ) -> list[RankedResult]:
+        """
+        Apply score fusion to raw vector search results.
+        raw_results: each dict must have at least ref_path, content, distance.
+        Returns top_k RankedResult sorted by final_score desc.
+        """
+        from autonomy.ingest_pipeline import AUTHORITY_WEIGHTS, _infer_memory_type, _infer_time_scope
+
+        ranked: list[RankedResult] = []
+
+        for r in raw_results:
+            ref = r.get("ref_path", "")
+            content = r.get("content", "")
+            source_file = r.get("source_file", ref)
+            distance = float(r.get("distance", 0.5))
+
+            # 1. Semantic score from cosine distance
+            semantic_score = max(0.0, 1.0 - distance)
+
+            # 2. Authority
+            mem_type = r.get("memory_type") or _infer_memory_type(ref)
+            authority_score = AUTHORITY_WEIGHTS.get(mem_type, 0.5)
+
+            # Skip vault content (sensitivity guard)
+            if mem_type == "vault":
+                continue
+
+            # 3. Temporal
+            time_scope = r.get("time_scope") or _infer_time_scope(mem_type)
+            updated_at = r.get("updated_at")
+            if updated_at is None:
+                # Look up from DB
+                row = self.db.execute(
+                    "SELECT mu.updated_at FROM memory_units mu WHERE mu.source_ref = ?",
+                    (source_file,),
+                ).fetchone()
+                updated_at = row["updated_at"] if row else None
+            temporal = _temporal_score(time_scope, updated_at, query)
+
+            # 4. Entity
+            entity_tags_json = r.get("entity_tags", "[]")
+            if entity_tags_json is None:
+                unit_row = self.db.execute(
+                    "SELECT entity_tags FROM memory_units WHERE source_ref = ?",
+                    (source_file,),
+                ).fetchone()
+                entity_tags_json = unit_row["entity_tags"] if unit_row else "[]"
+            entity = _entity_score(entity_tags_json, query, self.db)
+
+            # Fusion
+            final_score = (
+                W_SEMANTIC * semantic_score
+                + W_AUTHORITY * authority_score
+                + W_TEMPORAL * temporal
+                + W_ENTITY * entity
+            )
+
+            ranked.append(RankedResult(
+                ref_path=ref,
+                content=content,
+                source_file=source_file,
+                semantic_score=semantic_score,
+                authority_score=authority_score,
+                temporal_score=temporal,
+                entity_score=entity,
+                final_score=final_score,
+                memory_type=mem_type,
+                route_intent=route_intent,
+            ))
+
+        ranked.sort(key=lambda r: r.final_score, reverse=True)
+        return ranked[:top_k]
+
+    def explain(self, result: RankedResult) -> str:
+        """Human-readable explanation of why this result was ranked here."""
+        return (
+            f"[final={result.final_score:.3f}] "
+            f"semantic={result.semantic_score:.3f} "
+            f"authority={result.authority_score:.3f} "
+            f"temporal={result.temporal_score:.3f} "
+            f"entity={result.entity_score:.3f} "
+            f"type={result.memory_type}"
+        )

package/scripts/memory/installer/templates/autonomy/retrieval_router.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+retrieval_router.py - Active retrieval router with intent/topic classification.
+
+Routes queries to appropriate memory classes based on detected intent.
+Falls back to global search when confidence is low.
+
+Memory class routing:
+  - procedural → lessons/ (how to do things, rules)
+  - episodic   → journal/, active-context (recent events, history)
+  - core       → hot-rules.md, memo.md (invariants, ownership)
+  - semantic   → digests/ (summaries, concepts)
+  - global     → all classes (fallback)
+"""
+import re
+import sqlite3
+from dataclasses import dataclass
+from typing import Optional
+
+from autonomy.schema import get_db
+
+# Intent → memory_type routing table
+_INTENT_PATTERNS: list[tuple[str, list[str], str]] = [
+    # (label, patterns, memory_type)
+    ("error", [r"\b(error|crash|fail|bug|exception|broke|broken)\b"], "procedural"),
+    ("lesson", [r"\b(lesson|rule|pattern|pitfall|don.t|avoid|never|always)\b"], "procedural"),
+    ("history", [r"\b(when|yesterday|last\s+week|last\s+month|what\s+happened|journal)\b"], "episodic"),
+    ("recent", [r"\b(recent|latest|today|current\s+session|currently\s+working)\b"], "episodic"),
+    ("ownership", [r"\b(who\s+owns|owner|responsible\s+for|which\s+(file|module|class))\b"], "core"),
+    ("invariant", [r"\b(invariant|constraint|rule|must\s+not|forbidden|allowed)\b"], "core"),
+    ("architecture", [r"\b(architecture|design|structure|module|component)\b"], "semantic"),
+    ("summary", [r"\b(summary|overview|digest|what\s+is|describe)\b"], "semantic"),
+]
+
+CONFIDENCE_THRESHOLD = 0.5
+
+
+@dataclass
+class RouteDecision:
+    intent: str
+    memory_types: list[str]  # ordered by priority
+    confidence: float
+    fallback: bool  # True if routing to global fallback
+
+
+def classify_intent(query: str) -> RouteDecision:
+    """
+    Classify query intent and route to memory class(es).
+    Returns RouteDecision with ordered memory types to search.
+    """
+    q_lower = query.lower()
+    scores: dict[str, float] = {}
+
+    for label, patterns, mem_type in _INTENT_PATTERNS:
+        for pattern in patterns:
+            if re.search(pattern, q_lower, re.IGNORECASE):
+                scores[mem_type] = scores.get(mem_type, 0.0) + 1.0
+
+    if not scores:
+        return RouteDecision(
+            intent="global", memory_types=["core", "procedural", "episodic", "semantic"],
+            confidence=0.0, fallback=True
+        )
+
+    # Normalize
+    total = sum(scores.values())
+    normed = {k: v / total for k, v in scores.items()}
+
+    best_type = max(normed, key=lambda k: normed[k])
+    best_conf = normed[best_type]
+
+    if best_conf < CONFIDENCE_THRESHOLD:
+        # Include all types but prioritize best match
+        all_types = list(normed.keys()) + [t for t in ["core", "procedural", "episodic", "semantic"] if t not in normed]
+        return RouteDecision(intent="mixed", memory_types=all_types, confidence=best_conf, fallback=True)
+
+    # Include secondary routes
+    ordered = sorted(normed, key=lambda k: normed[k], reverse=True)
+    # Always include global fallback types not in primary route
+    for t in ["core", "procedural", "episodic", "semantic"]:
+        if t not in ordered:
+            ordered.append(t)
+
+    return RouteDecision(
+        intent=best_type, memory_types=ordered, confidence=best_conf, fallback=False
+    )
+
+
+class RetrievalRouter:
+    def __init__(self, db: Optional[sqlite3.Connection] = None):
+        self.db = db or get_db()
+
+    def route_query(self, query: str, top_k: int = 5) -> tuple[RouteDecision, list[dict]]:
+        """
+        Route query to appropriate memory classes, return (decision, candidates).
+        Candidates are dict with {ref_path, content, source_ref, memory_type,
+        authority, time_scope, entity_tags}.
+        """
+        decision = classify_intent(query)
+        candidates: list[dict] = []
+
+        # Primary: search by memory_type priority
+        for mem_type in decision.memory_types:
+            rows = self.db.execute(
+                """
+                SELECT mu.unit_id, mu.source_ref, mu.memory_type, mu.authority,
+                       mu.time_scope, mu.entity_tags, mu.sensitivity
+                FROM memory_units mu
+                WHERE mu.memory_type = ? AND mu.sensitivity != 'secret'
+                ORDER BY mu.authority DESC, mu.updated_at DESC
+                LIMIT ?
+                """,
+                (mem_type, top_k),
+            ).fetchall()
+            for row in rows:
+                candidates.append(dict(row))
+            if len(candidates) >= top_k:
+                break
+
+        # Fallback: add any missing from global pool
+        if len(candidates) < top_k:
+            existing_ids = {c["unit_id"] for c in candidates}
+            extra = self.db.execute(
+                """
+                SELECT mu.unit_id, mu.source_ref, mu.memory_type, mu.authority,
+                       mu.time_scope, mu.entity_tags, mu.sensitivity
+                FROM memory_units mu
+                WHERE mu.unit_id NOT IN ({})
+                  AND mu.sensitivity != 'secret'
+                ORDER BY mu.authority DESC, mu.updated_at DESC
+                LIMIT ?
+                """.format(",".join("?" * len(existing_ids)) if existing_ids else "'__none__'"),
+                tuple(existing_ids) + (top_k - len(candidates),) if existing_ids else (top_k - len(candidates),),
+            ).fetchall()
+            for row in extra:
+                candidates.append(dict(row))
+
+        return decision, candidates
+
+    def get_route_metadata(self, query: str) -> dict:
+        """Return routing metadata as dict (for logging/debugging)."""
+        decision = classify_intent(query)
+        return {
+            "intent": decision.intent,
+            "memory_types": decision.memory_types,
+            "confidence": round(decision.confidence, 3),
+            "fallback": decision.fallback,
+        }

package/scripts/memory/installer/templates/autonomy/runner.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""
+runner.py - Mnemo Autonomous Memory Runtime (no-human-in-the-loop).
+
+Triggered by:
+  - Git hooks: post-commit, post-merge, post-checkout
+  - Periodic scheduler tick (--mode schedule)
+  - Direct invocation: python runner.py [--mode {auto|schedule|once}]
+
+Responsibilities:
+  1. Change detection on .mnemo/memory/**/*.md (with .cursor bridge compatibility)
+  2. Ingest and chunk changed files
+  3. Metadata classification + entity resolution
+  4. Fact lifecycle (ADD/UPDATE/DEPRECATE/NOOP)
+  5. Vector index update
+  6. Autonomous journal delta generation
+  7. Lesson promotion from stable signals
+  8. Safety check on retrieval packs
+"""
+import argparse
+import json
+import os
+import signal
+import sys
+import time
+import traceback
+from pathlib import Path
+from datetime import datetime, timezone
+
+# Allow running from scripts/memory/ directory
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE.parent))
+
+from autonomy.schema import get_db
+from autonomy.ingest_pipeline import IngestPipeline
+from autonomy.lifecycle_engine import LifecycleEngine
+from autonomy.entity_resolver import EntityResolver
+
+
+LOCK_PATH: Path | None = None
+STATE_KEY_LAST_RUN = "last_run_ts"
+STATE_KEY_CYCLE = "cycle_count"
+SCHEDULE_INTERVAL_S = int(os.getenv("MNEMO_SCHEDULE_INTERVAL", "300"))  # 5 min default
+MAX_LOCK_AGE_S = 600  # stale lock timeout
+
+
+def resolve_memory_root(repo_root: Path) -> Path:
+    override = os.getenv("MNEMO_MEMORY_ROOT", "").strip()
+    if override:
+        return Path(override).expanduser().resolve()
+
+    candidates = [
+        repo_root / ".mnemo" / "memory",
+        repo_root / ".cursor" / "memory",
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    return candidates[0]
+
+
+def _require_lock_path() -> Path:
+    if LOCK_PATH is None:
+        raise RuntimeError("LOCK_PATH is not initialized")
+    return LOCK_PATH
+
+
+def _acquire_lock() -> bool:
+    lock_path = _require_lock_path()
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    if lock_path.exists():
+        try:
+            mtime = lock_path.stat().st_mtime
+            age = time.time() - mtime
+            if age < MAX_LOCK_AGE_S:
+                return False
+            # Stale lock — remove and proceed
+            lock_path.unlink()
+        except OSError:
+            return False
+    try:
+        lock_path.write_text(str(os.getpid()), encoding="utf-8")
+        return True
+    except OSError:
+        return False
+
+
+def _release_lock() -> None:
+    lock_path = _require_lock_path()
+    try:
+        if lock_path.exists():
+            lock_path.unlink()
+    except OSError:
+        pass
+
+
+def _emit_log(level: str, msg: str) -> None:
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    print(f"[{ts}] [{level}] {msg}", flush=True)
+
+
+def run_once(repo_root: Path) -> dict:
+    """Execute one autonomous memory cycle. Returns summary dict."""
+    summary = {"status": "ok", "ingested": 0, "facts_added": 0, "facts_deprecated": 0, "errors": []}
+
+    db = get_db()
+    ingester = IngestPipeline(db=db, repo_root=repo_root)
+    lifecycle = LifecycleEngine(db=db)
+    resolver = EntityResolver(db=db)
+
+    # 1. Detect changed files
+    changed = ingester.detect_changes()
+    _emit_log("INFO", f"Detected {len(changed)} changed memory files")
+
+    # 2. Ingest each changed file
+    for path in changed:
+        try:
+            units = ingester.ingest_file(path)
+            summary["ingested"] += len(units)
+
+            # 3. Entity resolution per unit
+            for unit in units:
+                resolver.resolve(unit)
+
+            # 4. Fact lifecycle decisions
+            for unit in units:
+                result = lifecycle.process(unit)
+                if result.operation == "ADD":
+                    summary["facts_added"] += 1
+                elif result.operation == "DEPRECATE":
+                    summary["facts_deprecated"] += 1
+
+        except Exception as e:
+            err = f"{path}: {e}"
+            summary["errors"].append(err)
+            _emit_log("ERROR", err)
+
+    # 5. Autonomous journal delta
+    if summary["ingested"] > 0:
+        try:
+            _write_autonomy_journal_delta(repo_root, summary)
+        except Exception as e:
+            _emit_log("WARN", f"Journal delta failed: {e}")
+
+    # 6. Lesson promotion (stable signals → new lessons)
+    try:
+        promoted = lifecycle.promote_lessons(repo_root=repo_root)
+        if promoted:
+            _emit_log("INFO", f"Promoted {len(promoted)} new lessons")
+            summary["lessons_promoted"] = len(promoted)
+    except Exception as e:
+        _emit_log("WARN", f"Lesson promotion failed: {e}")
+
+    # 7. Persist cycle state
+    now_ts = str(time.time())
+    db.execute(
+        "INSERT OR REPLACE INTO autonomy_state(key, value, updated_at) VALUES ('last_run_ts', ?, unixepoch('now'))",
+        (now_ts,),
+    )
+    db.execute(
+        """
+        INSERT INTO autonomy_state(key, value, updated_at) VALUES ('cycle_count', '1', unixepoch('now'))
+        ON CONFLICT(key) DO UPDATE SET
+            value = CAST(CAST(value AS INTEGER) + 1 AS TEXT),
+            updated_at = unixepoch('now')
+        """
+    )
+    db.commit()
+    db.close()
+
+    if summary["errors"]:
+        summary["status"] = "partial"
+    return summary
+
+
+def _write_autonomy_journal_delta(repo_root: Path, summary: dict) -> None:
+    """Write an autonomous journal entry summarizing the cycle."""
+    today = datetime.now().strftime("%Y-%m-%d")
+    month = today[:7]
+    journal_path = resolve_memory_root(repo_root) / "journal" / f"{month}.md"
+    journal_path.parent.mkdir(parents=True, exist_ok=True)
+
+    facts_line = f"{summary['facts_added']} facts added"
+    if summary.get("facts_deprecated"):
+        facts_line += f", {summary['facts_deprecated']} deprecated"
+    if summary.get("lessons_promoted"):
+        facts_line += f", {summary['lessons_promoted']} lessons promoted"
+
+    entry_lines = [
+        f"- [Process][Autonomy] Auto-cycle: ingested {summary['ingested']} units ({facts_line})",
+        f"  - System: Mnemo autonomous runner (no human in loop)",
+    ]
+    if summary.get("errors"):
+        entry_lines.append(f"  - Warnings: {len(summary['errors'])} errors (see runner log)")
+
+    entry = "\n".join(entry_lines)
+    date_heading = f"## {today}"
+
+    if journal_path.exists():
+        text = journal_path.read_text(encoding="utf-8-sig")
+        if f"## {today}" in text and "[Process][Autonomy]" in text:
+            return  # Don't spam: one autonomy entry per day per file
+        if f"## {today}" in text:
+            text = text.rstrip() + "\n\n" + entry + "\n"
+        else:
+            text = text.rstrip() + f"\n\n{date_heading}\n\n{entry}\n"
+        journal_path.write_text(text, encoding="utf-8")
+    else:
+        project = repo_root.name
+        content = f"# Development Journal - {project} ({month})\n\n{date_heading}\n\n{entry}\n"
+        journal_path.write_text(content, encoding="utf-8")
+
+
+def run_schedule(repo_root: Path) -> None:
+    """Run continuously on a fixed interval schedule."""
+    _emit_log("INFO", f"Scheduler started (interval={SCHEDULE_INTERVAL_S}s)")
+
+    def _handle_signal(sig, frame):
+        _emit_log("INFO", "Runner received shutdown signal")
+        _release_lock()
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, _handle_signal)
+    signal.signal(signal.SIGTERM, _handle_signal)
+
+    while True:
+        if _acquire_lock():
+            try:
+                summary = run_once(repo_root)
+                _emit_log("INFO", f"Cycle complete: {json.dumps(summary)}")
+            except Exception:
+                _emit_log("ERROR", traceback.format_exc())
+            finally:
+                _release_lock()
+        else:
+            _emit_log("DEBUG", "Another runner is active; skipping cycle")
+        time.sleep(SCHEDULE_INTERVAL_S)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Mnemo autonomous memory runner")
+    ap.add_argument("--mode", choices=["auto", "schedule", "once"], default="once",
+                    help="auto=once+return, schedule=loop, once=single run")
+    ap.add_argument("--repo", default=str(Path.cwd()), help="Repo root directory")
+    args = ap.parse_args()
+
+    repo_root = Path(args.repo).resolve()
+    os.chdir(repo_root)
+    global LOCK_PATH
+    LOCK_PATH = resolve_memory_root(repo_root) / ".autonomy" / "runner.lock"
+
+    if args.mode == "schedule":
+        run_schedule(repo_root)
+        return 0
+
+    if not _acquire_lock():
+        _emit_log("INFO", "Another runner is active; exiting")
+        return 0
+
+    try:
+        summary = run_once(repo_root)
+        _emit_log("INFO", f"Done: {json.dumps(summary)}")
+        return 0 if summary["status"] != "error" else 1
+    except Exception:
+        _emit_log("ERROR", traceback.format_exc())
+        return 1
+    finally:
+        _release_lock()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())