@simbimbo/memory-ocmemog 0.1.4

package/brain/runtime/memory/promote.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import json
+from typing import Dict, Any
+
+from brain.runtime.instrumentation import emit_event
+from brain.runtime import state_store
+from brain.runtime.memory import provenance, store
+from brain.runtime import config
+
+
+LOGFILE = state_store.reports_dir() / "brain_memory.log.jsonl"
+
+
+def _should_promote(confidence: float, threshold: float | None = None) -> bool:
+    threshold = config.OCMEMOG_PROMOTION_THRESHOLD if threshold is None else threshold
+    return confidence >= float(threshold)
+
+
+def _destination_table(summary: str) -> str:
+    lowered = summary.lower()
+    if "runbook" in lowered or "procedure" in lowered or "steps" in lowered:
+        return "runbooks"
+    if "lesson" in lowered or "postmortem" in lowered or "learned" in lowered:
+        return "lessons"
+    return "knowledge"
+
+
+def promote_candidate(candidate: Dict[str, Any]) -> Dict[str, Any]:
+    emit_event(LOGFILE, "brain_memory_promote_start", status="ok")
+    confidence = float(candidate.get("confidence_score", 0.0))
+    decision = "promote" if _should_promote(confidence) else "reject"
+    candidate_id = str(candidate.get("candidate_id") or "")
+
+    candidate_metadata = provenance.normalize_metadata(candidate.get("metadata", {}), source="promote")
+    candidate_metadata["candidate_id"] = candidate_id
+    candidate_metadata["derived_from_candidate_id"] = candidate_id
+    candidate_metadata["derived_via"] = "promotion"
+
+    conn = store.connect()
+    promotion_id = None
+    destination = _destination_table(str(candidate.get("distilled_summary", "")))
+    if decision == "promote":
+        row = conn.execute(
+            "SELECT id FROM promotions WHERE source=? AND content=?",
+            (str(candidate.get("source_event_id")), candidate.get("distilled_summary", "")),
+        ).fetchone()
+        if not row:
+            cur = conn.execute(
+                """
+                INSERT INTO promotions (
+                    candidate_id, source, confidence, status, decision_reason,
+                    metadata_json, content, schema_version
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    candidate_id,
+                    str(candidate.get("source_event_id")),
+                    confidence,
+                    "promoted",
+                    "confidence_threshold",
+                    json.dumps(candidate_metadata, ensure_ascii=False),
+                    candidate.get("distilled_summary", ""),
+                    store.SCHEMA_VERSION,
+                ),
+            )
+            memory_rec = conn.execute(
+                f"INSERT INTO {destination} (source, confidence, metadata_json, content, schema_version) VALUES (?, ?, ?, ?, ?)",
+                (
+                    str(candidate.get("source_event_id")),
+                    confidence,
+                    json.dumps(candidate_metadata, ensure_ascii=False),
+                    candidate.get("distilled_summary", ""),
+                    store.SCHEMA_VERSION,
+                ),
+            )
+            conn.execute(
+                "UPDATE candidates SET status='promoted', updated_at=datetime('now') WHERE candidate_id=?",
+                (candidate_id,),
+            )
+            conn.execute(
+                "INSERT INTO memory_events (event_type, source, details_json, schema_version) VALUES (?, ?, ?, ?)",
+                (
+                    "candidate_promoted",
+                    str(candidate.get("source_event_id")),
+                    json.dumps({"candidate_id": candidate_id, "promotion_table": destination}),
+                    store.SCHEMA_VERSION,
+                ),
+            )
+            conn.commit()
+            promotion_id = cur.lastrowid
+            memory_id = memory_rec.lastrowid
+        else:
+            promotion_id = row[0]
+            memory_id = None
+        emit_event(LOGFILE, "brain_memory_promote_success", status="ok", destination=destination)
+    else:
+        conn.execute(
+            "UPDATE candidates SET status='rejected', updated_at=datetime('now') WHERE candidate_id=?",
+            (candidate_id,),
+        )
+        conn.execute(
+            "INSERT INTO promotions (candidate_id, source, confidence, status, decision_reason, metadata_json, content, schema_version) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+            (
+                candidate_id,
+                str(candidate.get("source_event_id")),
+                confidence,
+                "rejected",
+                "below_threshold",
+                json.dumps(candidate_metadata, ensure_ascii=False),
+                candidate.get("distilled_summary", ""),
+                store.SCHEMA_VERSION,
+            ),
+        )
+        conn.commit()
+        emit_event(LOGFILE, "brain_memory_promote_rejected", status="ok")
+        memory_id = None
+    conn.close()
+
+    if decision == "promote" and promotion_id is not None:
+        from brain.runtime.memory import reinforcement, vector_index
+
+        promoted_reference = f"{destination}:{memory_id}" if memory_id else ""
+        promotion_updates = {
+            **candidate_metadata,
+            "promotion_id": promotion_id,
+            "derived_from_promotion_id": promotion_id,
+        }
+        if promoted_reference:
+            provenance.update_memory_metadata(promoted_reference, promotion_updates)
+        reinforcement.log_experience(
+            task_id=str(candidate.get("candidate_id") or candidate.get("source_event_id") or ""),
+            outcome="promoted",
+            confidence=confidence,
+            reward_score=confidence,
+            memory_reference=promoted_reference or f"promotions:{promotion_id}",
+            experience_type="promotion",
+            source_module="memory_promote",
+        )
+        emit_event(LOGFILE, "brain_memory_reinforcement_created", status="ok")
+        if memory_id:
+            vector_index.insert_memory(memory_id, candidate.get("distilled_summary", ""), confidence)
+
+    return {"decision": decision, "confidence": confidence, "promotion_id": promotion_id, "destination": destination}
+
+
+def promote_candidate_by_id(candidate_id: str) -> Dict[str, Any]:
+    conn = store.connect()
+    row = conn.execute(
+        """
+        SELECT candidate_id, source_event_id, distilled_summary, verification_points,
+               confidence_score, metadata_json
+        FROM candidates WHERE candidate_id=?
+        """,
+        (candidate_id,),
+    ).fetchone()
+    conn.close()
+    if not row:
+        emit_event(LOGFILE, "brain_memory_promote_error", status="error")
+        return {"decision": "error", "reason": "candidate_not_found"}
+    payload = dict(row)
+    try:
+        payload["metadata"] = json.loads(payload.get("metadata_json") or "{}")
+    except Exception:
+        payload["metadata"] = {}
+    return promote_candidate(payload)
+
+
+def demote_memory(reference: str, reason: str = "low_confidence", new_confidence: float = 0.1) -> Dict[str, Any]:
+    table, sep, raw_id = reference.partition(":")
+    if not sep or not raw_id.isdigit():
+        return {"ok": False, "error": "invalid_reference"}
+    allowed = {"knowledge", "runbooks", "lessons", "directives", "reflections", "tasks"}
+    if table not in allowed:
+        return {"ok": False, "error": "unsupported_table"}
+    conn = store.connect()
+    row = conn.execute(
+        f"SELECT confidence, content, metadata_json FROM {table} WHERE id=?",
+        (int(raw_id),),
+    ).fetchone()
+    if not row:
+        conn.close()
+        return {"ok": False, "error": "not_found"}
+    previous = float(row[0] or 0.0)
+    content = str(row[1] or "")
+    metadata_json = row[2] or "{}"
+
+    # archive into cold storage, then remove from hot table
+    conn.execute(
+        "INSERT INTO cold_storage (source_table, source_id, content, metadata_json, reason, schema_version) VALUES (?, ?, ?, ?, ?, ?)",
+        (table, int(raw_id), content, metadata_json, reason, store.SCHEMA_VERSION),
+    )
+    conn.execute(
+        f"DELETE FROM {table} WHERE id=?",
+        (int(raw_id),),
+    )
+    conn.execute(
+        "INSERT INTO demotions (memory_reference, previous_confidence, new_confidence, reason, schema_version) VALUES (?, ?, ?, ?, ?)",
+        (reference, previous, float(new_confidence), reason, store.SCHEMA_VERSION),
+    )
+    conn.commit()
+    conn.close()
+    emit_event(LOGFILE, "brain_memory_demoted", status="ok", reference=reference)
+    return {"ok": True, "reference": reference, "previous": previous, "new": float(new_confidence), "archived": True}
+
+
+def demote_by_confidence(limit: int = 20, threshold: float | None = None, force: bool = False) -> Dict[str, Any]:
+    threshold = config.OCMEMOG_DEMOTION_THRESHOLD if threshold is None else threshold
+    tables = ("knowledge", "runbooks", "lessons", "directives", "reflections", "tasks")
+    conn = store.connect()
+    rows = []
+    for table in tables:
+        try:
+            rows.extend(
+                conn.execute(
+                    f"SELECT '{table}' AS table_name, id, confidence FROM {table} ORDER BY confidence ASC LIMIT ?",
+                    (limit,),
+                ).fetchall()
+            )
+        except Exception:
+            continue
+    conn.close()
+    # sort by confidence and demote below threshold
+    ranked = sorted(rows, key=lambda r: float(r[2] or 0.0))
+    demoted = []
+    for row in ranked:
+        table = row[0]
+        memory_id = int(row[1])
+        confidence = float(row[2] or 0.0)
+        if confidence >= float(threshold) and not force:
+            continue
+        result = demote_memory(f"{table}:{memory_id}", reason="low_confidence", new_confidence=confidence * 0.5)
+        if result.get("ok"):
+            demoted.append(result)
+        if len(demoted) >= limit:
+            break
+    return {"ok": True, "threshold": float(threshold), "demoted": demoted, "count": len(demoted)}

package/brain/runtime/memory/provenance.py

@@ -0,0 +1,356 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Set
+
+from brain.runtime.memory import memory_links, store
+
+_MEMORY_TABLES = {"knowledge", "reflections", "directives", "tasks", "runbooks", "lessons"}
+_FETCHABLE_TABLES = _MEMORY_TABLES | {"promotions", "experiences", "conversation_turns", "conversation_checkpoints"}
+_SYNTHETIC_PREFIXES = {"conversation", "session", "thread", "message", "label", "transcript"}
+
+
+def _load_json(value: Any, fallback: Any) -> Any:
+    try:
+        return json.loads(value or "")
+    except Exception:
+        return fallback
+
+
+def _dedupe(values: Iterable[str]) -> List[str]:
+    seen: Set[str] = set()
+    items: List[str] = []
+    for value in values:
+        item = str(value or "").strip()
+        if not item or item in seen:
+            continue
+        seen.add(item)
+        items.append(item)
+    return items
+
+
+def _transcript_target(path: str, start_line: Any = None, end_line: Any = None) -> str:
+    suffix = ""
+    try:
+        start = int(start_line) if start_line is not None else None
+    except Exception:
+        start = None
+    try:
+        end = int(end_line) if end_line is not None else None
+    except Exception:
+        end = None
+    if start and end and end >= start:
+        suffix = f"#L{start}-L{end}"
+    elif start:
+        suffix = f"#L{start}"
+    return f"transcript:{path}{suffix}"
+
+
+def normalize_metadata(metadata: Optional[Dict[str, Any]], *, source: Optional[str] = None) -> Dict[str, Any]:
+    raw = dict(metadata or {})
+    existing = raw.get("provenance") if isinstance(raw.get("provenance"), dict) else {}
+
+    source_references = _dedupe(
+        [
+            *(existing.get("source_references") or []),
+            *(raw.get("source_references") or []),
+            existing.get("source_reference") or "",
+            raw.get("source_reference") or "",
+            existing.get("experience_reference") or "",
+            raw.get("experience_reference") or "",
+        ]
+    )
+    source_labels = _dedupe(
+        [
+            *(existing.get("source_labels") or []),
+            *(raw.get("source_labels") or []),
+            existing.get("source_label") or "",
+            raw.get("source_label") or "",
+        ]
+    )
+
+    conversation = dict(existing.get("conversation") or {})
+    for key in ("conversation_id", "session_id", "thread_id", "message_id", "role"):
+        if raw.get(key) is not None and conversation.get(key) is None:
+            conversation[key] = raw.get(key)
+
+    transcript_anchor = dict(existing.get("transcript_anchor") or {})
+    if raw.get("transcript_path") and not transcript_anchor.get("path"):
+        transcript_anchor = {
+            "path": raw.get("transcript_path"),
+            "start_line": raw.get("transcript_offset"),
+            "end_line": raw.get("transcript_end_offset"),
+        }
+
+    provenance: Dict[str, Any] = dict(existing)
+    if source_references:
+        provenance["source_references"] = source_references
+        provenance["source_reference"] = source_references[0]
+    if source_labels:
+        provenance["source_labels"] = source_labels
+    if conversation:
+        provenance["conversation"] = conversation
+    if transcript_anchor.get("path"):
+        provenance["transcript_anchor"] = transcript_anchor
+    if source:
+        provenance.setdefault("origin_source", source)
+
+    for key in (
+        "source_event_id",
+        "task_id",
+        "candidate_id",
+        "promotion_id",
+        "experience_reference",
+        "derived_from_candidate_id",
+        "derived_from_promotion_id",
+        "derived_via",
+        "kind",
+    ):
+        if raw.get(key) is not None and provenance.get(key) is None:
+            provenance[key] = raw.get(key)
+
+    if provenance:
+        raw["provenance"] = provenance
+    if source_references:
+        raw["source_reference"] = source_references[0]
+        raw["source_references"] = source_references
+    if source_labels:
+        raw["source_labels"] = source_labels
+        raw.setdefault("source_label", source_labels[0])
+    return raw
+
+
+def preview_from_metadata(metadata: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    normalized = normalize_metadata(metadata)
+    provenance = normalized.get("provenance") if isinstance(normalized.get("provenance"), dict) else {}
+    return {
+        "source_references": provenance.get("source_references") or [],
+        "source_labels": provenance.get("source_labels") or [],
+        "conversation": provenance.get("conversation") or {},
+        "transcript_anchor": provenance.get("transcript_anchor") or None,
+        "origin_source": provenance.get("origin_source"),
+        "derived_via": provenance.get("derived_via"),
+    }
+
+
+def _link_once(source_reference: str, link_type: str, target_reference: str) -> None:
+    if not source_reference or not target_reference:
+        return
+    existing = memory_links.get_memory_links(source_reference)
+    if any(item.get("link_type") == link_type and item.get("target_reference") == target_reference for item in existing):
+        return
+    memory_links.add_memory_link(source_reference, link_type, target_reference)
+
+
+def apply_links(reference: str, metadata: Optional[Dict[str, Any]]) -> None:
+    normalized = normalize_metadata(metadata)
+    provenance = normalized.get("provenance") if isinstance(normalized.get("provenance"), dict) else {}
+    for source_reference in provenance.get("source_references") or []:
+        _link_once(reference, "derived_from", str(source_reference))
+    for label in provenance.get("source_labels") or []:
+        _link_once(reference, "source_label", f"label:{label}")
+    conversation = provenance.get("conversation") or {}
+    for key, link_type in (
+        ("conversation_id", "conversation"),
+        ("session_id", "session"),
+        ("thread_id", "thread"),
+        ("message_id", "message"),
+    ):
+        value = str(conversation.get(key) or "").strip()
+        if value:
+            _link_once(reference, link_type, f"{link_type}:{value}")
+    transcript = provenance.get("transcript_anchor") or {}
+    if transcript.get("path"):
+        _link_once(
+            reference,
+            "transcript",
+            _transcript_target(
+                str(transcript.get("path")),
+                transcript.get("start_line"),
+                transcript.get("end_line"),
+            ),
+        )
+    if provenance.get("experience_reference"):
+        _link_once(reference, "experience", str(provenance.get("experience_reference")))
+    if provenance.get("derived_from_candidate_id"):
+        _link_once(reference, "candidate", f"candidate:{provenance['derived_from_candidate_id']}")
+    if provenance.get("derived_from_promotion_id"):
+        _link_once(reference, "promotion", f"promotions:{provenance['derived_from_promotion_id']}")
+
+
+def update_memory_metadata(reference: str, updates: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    table, sep, raw_id = reference.partition(":")
+    if not sep or table not in _MEMORY_TABLES or not raw_id.isdigit():
+        return None
+    conn = store.connect()
+    try:
+        row = conn.execute(f"SELECT metadata_json FROM {table} WHERE id = ?", (int(raw_id),)).fetchone()
+        if not row:
+            return None
+        current = _load_json(row["metadata_json"], {})
+        merged = normalize_metadata({**current, **updates})
+        conn.execute(
+            f"UPDATE {table} SET metadata_json = ? WHERE id = ?",
+            (json.dumps(merged, ensure_ascii=False), int(raw_id)),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+    apply_links(reference, merged)
+    return merged
+
+
+def fetch_reference(reference: str) -> Optional[Dict[str, Any]]:
+    prefix, sep, raw_id = reference.partition(":")
+    if not sep or not prefix:
+        return None
+    if prefix in _SYNTHETIC_PREFIXES:
+        payload: Dict[str, Any] = {"reference": reference, "type": prefix, "value": raw_id}
+        if prefix == "transcript":
+            payload["path"] = raw_id
+        return payload
+    if prefix == "candidate":
+        return {"reference": reference, "type": "candidate", "candidate_id": raw_id}
+    if prefix not in _FETCHABLE_TABLES:
+        return None
+
+    conn = store.connect()
+    try:
+        if prefix == "conversation_turns":
+            if not raw_id.isdigit():
+                return None
+            row = conn.execute("SELECT * FROM conversation_turns WHERE id = ?", (int(raw_id),)).fetchone()
+            if not row:
+                return None
+            payload = dict(row)
+            payload["reference"] = reference
+            payload["table"] = prefix
+            payload["id"] = int(raw_id)
+            payload["metadata"] = _load_json(payload.pop("metadata_json", "{}"), {})
+            return payload
+        if prefix == "conversation_checkpoints":
+            if not raw_id.isdigit():
+                return None
+            row = conn.execute("SELECT * FROM conversation_checkpoints WHERE id = ?", (int(raw_id),)).fetchone()
+            if not row:
+                return None
+            payload = dict(row)
+            payload["reference"] = reference
+            payload["table"] = prefix
+            payload["id"] = int(raw_id)
+            payload["metadata"] = _load_json(payload.pop("metadata_json", "{}"), {})
+            payload["open_loops"] = _load_json(payload.pop("open_loops_json", "[]"), [])
+            payload["pending_actions"] = _load_json(payload.pop("pending_actions_json", "[]"), [])
+            return payload
+        if prefix == "experiences":
+            if not raw_id.isdigit():
+                return None
+            row = conn.execute("SELECT * FROM experiences WHERE id = ?", (int(raw_id),)).fetchone()
+            if not row:
+                return None
+            payload = dict(row)
+            payload["reference"] = reference
+            payload["table"] = prefix
+            payload["id"] = int(raw_id)
+            payload["content"] = payload.get("outcome")
+            payload["metadata"] = _load_json(payload.pop("metadata_json", "{}"), {})
+            return payload
+        if prefix == "promotions":
+            if not raw_id.isdigit():
+                return None
+            row = conn.execute("SELECT * FROM promotions WHERE id = ?", (int(raw_id),)).fetchone()
+            if not row:
+                return None
+            payload = dict(row)
+            payload["reference"] = reference
+            payload["table"] = prefix
+            payload["id"] = int(raw_id)
+            payload["metadata"] = _load_json(payload.pop("metadata_json", "{}"), {})
+            return payload
+        if not raw_id.isdigit():
+            return None
+        row = conn.execute(f"SELECT * FROM {prefix} WHERE id = ?", (int(raw_id),)).fetchone()
+        if not row:
+            return None
+        payload = dict(row)
+        payload["reference"] = reference
+        payload["table"] = prefix
+        payload["id"] = int(raw_id)
+        payload["metadata"] = _load_json(payload.pop("metadata_json", "{}"), {})
+        return payload
+    finally:
+        conn.close()
+
+
+def _hydrate_target(reference: str, depth: int, seen: Set[str]) -> Optional[Dict[str, Any]]:
+    if reference in seen:
+        return {"reference": reference, "cycle": True}
+    return hydrate_reference(reference, depth=depth, _seen=seen)
+
+
+def hydrate_reference(reference: str, *, depth: int = 1, _seen: Optional[Set[str]] = None) -> Optional[Dict[str, Any]]:
+    seen = set(_seen or set())
+    if reference in seen:
+        return {"reference": reference, "cycle": True}
+    seen.add(reference)
+    payload = fetch_reference(reference)
+    if payload is None:
+        return None
+
+    metadata = payload.get("metadata") if isinstance(payload.get("metadata"), dict) else {}
+    preview = preview_from_metadata(metadata)
+    links = memory_links.get_memory_links(reference)
+    backlinks = memory_links.get_memory_links_for_target(reference)
+
+    payload["provenance_preview"] = preview
+    payload["links"] = links
+    payload["backlinks"] = backlinks
+    if depth <= 0:
+        return payload
+
+    payload["provenance"] = {
+        "outbound": [
+            {
+                **item,
+                "target": _hydrate_target(str(item.get("target_reference") or ""), depth - 1, seen),
+            }
+            for item in links
+        ],
+        "inbound": [
+            {
+                **item,
+                "source": _hydrate_target(str(item.get("source_reference") or ""), depth - 1, seen),
+            }
+            for item in backlinks
+        ],
+    }
+    return payload
+
+
+def collect_source_references(reference: str, *, depth: int = 2) -> List[str]:
+    pending = [reference]
+    seen: Set[str] = set()
+    collected: List[str] = []
+    remaining = max(0, int(depth))
+    while pending and remaining >= 0:
+        next_round: List[str] = []
+        for current in pending:
+            if current in seen:
+                continue
+            seen.add(current)
+            collected.append(current)
+            row = fetch_reference(current)
+            metadata = row.get("metadata") if isinstance((row or {}).get("metadata"), dict) else {}
+            preview = preview_from_metadata(metadata)
+            for source_ref in preview.get("source_references") or []:
+                if source_ref not in seen:
+                    next_round.append(str(source_ref))
+        pending = next_round
+        remaining -= 1
+    return _dedupe(collected)
+
+
+def source_references_only(reference: str, *, depth: int = 2) -> List[str]:
+    refs = collect_source_references(reference, depth=depth)
+    return refs[1:] if len(refs) > 1 else []

package/brain/runtime/memory/reinforcement.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import Dict, Any
+
+from brain.runtime.instrumentation import emit_event
+from brain.runtime import state_store
+from brain.runtime.memory import store
+
+
+def log_experience(
+    task_id: str,
+    outcome: str,
+    confidence: float,
+    reward_score: float,
+    memory_reference: str,
+    experience_type: str,
+    source_module: str,
+) -> Dict[str, Any]:
+    conn = store.connect()
+    row = conn.execute(
+        "SELECT id FROM experiences WHERE task_id=? AND memory_reference=? AND outcome=?",
+        (task_id, memory_reference, outcome),
+    ).fetchone()
+    if row:
+        conn.close()
+        emit_event(state_store.reports_dir() / "brain_memory.log.jsonl", "brain_memory_experience_duplicate", status="ok")
+        return {"experience_id": row[0], "duplicate": True}
+
+    cur = conn.execute(
+        "INSERT INTO experiences (task_id, outcome, reward_score, confidence, memory_reference, experience_type, source_module, schema_version) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+        (task_id, outcome, reward_score, confidence, memory_reference, experience_type, source_module, store.SCHEMA_VERSION),
+    )
+    conn.commit()
+    conn.close()
+    emit_event(state_store.reports_dir() / "brain_memory.log.jsonl", "brain_memory_experience_logged", status="ok")
+    return {"experience_id": cur.lastrowid, "duplicate": False, "experience_type": experience_type, "source_module": source_module}
+
+
+def log_task_execution(
+    *,
+    task_id: str,
+    task_type: str,
+    agent_id: str,
+    tool_used: str,
+    success: bool,
+    duration_ms: int,
+) -> Dict[str, Any]:
+    outcome_payload = {
+        "task_type": task_type,
+        "agent_id": agent_id,
+        "tool_used": tool_used,
+        "success": bool(success),
+        "duration_ms": duration_ms,
+    }
+    return log_experience(
+        task_id=task_id,
+        outcome=str(outcome_payload),
+        confidence=1.0,
+        reward_score=1.0 if success else 0.0,
+        memory_reference=f"tool:{tool_used}",
+        experience_type="task_execution",
+        source_module="task_engine",
+    )
+
+
+def list_recent_experiences(limit: int = 20) -> Dict[str, int]:
+    conn = store.connect()
+    rows = conn.execute(
+        "SELECT experience_type, COUNT(*) as count FROM experiences GROUP BY experience_type ORDER BY count DESC LIMIT ?",
+        (limit,),
+    ).fetchall()
+    conn.close()
+    return {row[0]: int(row[1]) for row in rows}