agentcache-core 0.9.9__py3-none-any.whl

agentcache/core/infer.py

@@ -0,0 +1,142 @@
+"""Type inference, text extraction, and synthetic compression helpers."""
+
+import json
+import re
+from typing import Any, Dict, List, Optional
+
+
+def clip_embed_input(text: str) -> str:
+    EMBED_MAX_CHARS = 16000
+    if len(text) <= EMBED_MAX_CHARS:
+        return text
+    return text[:EMBED_MAX_CHARS]
+
+
+def infer_type(tool_name: Optional[str], hook_type: str) -> str:
+    if hook_type == "post_tool_failure":
+        return "error"
+    if hook_type == "prompt_submit":
+        return "conversation"
+    if hook_type in ("subagent_stop", "task_completed"):
+        return "subagent"
+    if hook_type == "notification":
+        return "notification"
+
+    if not tool_name:
+        return "other"
+
+    n = re.sub(r"([a-z])([A-Z])", r"\1_\2", tool_name)
+    n = re.sub(r"[-\s]+", "_", n).lower()
+
+    def has_word(word: str) -> bool:
+        return (
+            bool(re.search(rf"(^|_){word}(_|$)", n))
+            or n == word
+            or n.endswith(word)
+            or n.startswith(word)
+        )
+
+    if any(has_word(w) for w in ["fetch", "http", "web"]):
+        return "web_fetch"
+    if any(has_word(w) for w in ["grep", "search", "glob", "find"]):
+        return "search"
+    if any(has_word(w) for w in ["bash", "shell", "exec", "run"]):
+        return "command_run"
+    if any(has_word(w) for w in ["edit", "update", "patch", "replace"]):
+        return "file_edit"
+    if any(has_word(w) for w in ["write", "create"]):
+        return "file_write"
+    if any(has_word(w) for w in ["read", "view"]):
+        return "file_read"
+    if any(has_word(w) for w in ["task", "agent"]):
+        return "subagent"
+    return "other"
+
+
+def extract_files(input_data: Any) -> List[str]:
+    if not input_data or not isinstance(input_data, dict):
+        return []
+    out = set()
+    for key in ["file_path", "filepath", "path", "filePath", "file", "pattern"]:
+        v = input_data.get(key)
+        if isinstance(v, str) and 0 < len(v) < 512:
+            out.add(v)
+    return list(out)
+
+
+def stringify_for_narrative(v: Any) -> str:
+    if v is None:
+        return ""
+    if isinstance(v, str):
+        return v
+    try:
+        return json.dumps(v)
+    except Exception:
+        return str(v)
+
+
+def vector_index_add_guarded(
+    obs_id: str, session_id: str, text: str, context: Dict[str, Any]
+) -> bool:
+    from .. import legacy as _legacy
+
+    if _legacy._search_service is None:
+        return False
+    ep = _legacy._search_service.embedding_provider
+    vi = _legacy._search_service.vector
+    if not vi or not ep:
+        return False
+    try:
+        clipped = clip_embed_input(text)
+        embedding = ep.embed(clipped)
+        if len(embedding) != ep.dimensions:
+            print(
+                f"[vector-index] Dimension mismatch: expected {ep.dimensions}, got {len(embedding)}"
+            )
+            return False
+        vi.add(obs_id, session_id, embedding)
+        return True
+    except Exception as e:
+        print(f"[vector-index] Embed failed: {e}")
+        return False
+
+
+def build_synthetic_compression(raw: Dict[str, Any]) -> Dict[str, Any]:
+    tool_name = raw.get("toolName") or raw.get("hookType")
+    input_str = stringify_for_narrative(raw.get("toolInput"))
+    output_str = stringify_for_narrative(raw.get("toolOutput"))
+    prompt_str = raw.get("userPrompt") or ""
+
+    parts = [s for s in [prompt_str, input_str, output_str] if len(s) > 0]
+    narrative = " | ".join(parts)
+    if len(narrative) > 400:
+        narrative = narrative[:399] + "…"
+
+    title = tool_name or "observation"
+    if len(title) > 80:
+        title = title[:79] + "…"
+
+    subtitle = None
+    if input_str:
+        subtitle = input_str
+        if len(subtitle) > 120:
+            subtitle = subtitle[:119] + "…"
+
+    res = {
+        "id": raw["id"],
+        "sessionId": raw["sessionId"],
+        "timestamp": raw["timestamp"],
+        "type": infer_type(raw.get("toolName"), raw["hookType"]),
+        "title": title,
+        "subtitle": subtitle,
+        "facts": [],
+        "narrative": narrative,
+        "concepts": [],
+        "files": extract_files(raw.get("toolInput")),
+        "importance": 5,
+        "confidence": 0.3,
+    }
+    for k in ["modality", "imageData", "agentId"]:
+        if raw.get(k) is not None:
+            res[k] = raw[k]
+    return res

agentcache/core/kv_scopes.py

@@ -0,0 +1,86 @@
+"""
+KV scope key registry.
+
+Single source of truth for every SQLite scope string used in the system.
+Import this module wherever a KV scope key is needed — routes, stores, workers.
+"""
+
+
+class KV:
+    # ---- Folder memory scopes ----
+
+    # Global index of all (folder_path, agent_id) pairs known to the system.
+    # Key = "{safe_folder_path}:{agent_id}", value = FolderIndexEntry dict.
+    folders = "mem:folders"
+
+    # Lookup index for O(1) observation hydration.
+    # Scope = "mem:obs_lookup", Key = obs_id, Value = {"folderPath": ..., "agentId": ...}
+    obs_lookup = "mem:obs_lookup"
+
+    @staticmethod
+    def folder_obs(folder_path: str, agent_id: str) -> str:
+        """Per-(folder, agent) observations scope.
+        Key = obs_id, value = FolderObservation dict.
+        """
+        safe_path = folder_path.replace("\\", "/").strip("/")
+        safe_agent = agent_id.strip()
+        return f"mem:folder:{safe_path}:{safe_agent}"
+
+    @staticmethod
+    def folder_meta(folder_path: str, agent_id: str) -> str:
+        """Per-(folder, agent) metadata scope.
+        Key = "meta", value = FolderMeta dict (obsCount, lastUpdated, summary).
+        """
+        safe_path = folder_path.replace("\\", "/").strip("/")
+        safe_agent = agent_id.strip()
+        return f"mem:foldermeta:{safe_path}:{safe_agent}"
+
+    @staticmethod
+    def obs_dedup(folder_path: str, agent_id: str) -> str:
+        """Deduplication index scope for (folder, agent) pairs.
+        Key = SHA-256 fingerprint hex of normalized text.
+        Value = {"obsId": str, "timestamp": str}
+        """
+        safe_path = folder_path.replace("\\", "/").strip("/")
+        safe_agent = agent_id.strip()
+        return f"mem:obs_dedup:{safe_path}:{safe_agent}"
+
+    # ---- Global / shared scopes ----
+
+    # Long-term memories.
+    memories = "mem:memories"
+
+    # BM25 index shards.
+    bm25Index = "mem:index:bm25"
+
+    # Audit log.
+    audit = "mem:audit"
+
+    # Graph edges.
+    relations = "mem:relations"
+
+    # ---- Legacy scopes (read-only; kept for migration and backward compat) ----
+
+    # Legacy session store.
+    sessions = "mem:sessions"
+
+    @staticmethod
+    def observations(session_id: str) -> str:
+        """Legacy per-session observations scope."""
+        return f"mem:obs:{session_id}"
+
+    # Lessons — confidence-scored learning entries.
+    lessons = "mem:lessons"
+
+    # Legacy summary / profile / slot / image-ref scopes.
+    summaries = "mem:summaries"
+    profiles = "mem:profiles"
+    slots = "mem:slots"
+    imageRefs = "mem:image-refs"
+
+    # Global (cross-project) pinned slots.
+    globalSlots = "mem:global-slots"
+
+    # Semantic and procedural memory scopes (used by consolidate).
+    semantic = "mem:semantic"
+    procedural = "mem:procedural"

agentcache/core/lessons.py

@@ -0,0 +1,242 @@
+"""Lessons learned — save, recall, reinforce, decay."""
+
+import datetime
+from typing import Any, Dict
+
+from ..db import StateKV
+from ..storage.paths import fingerprint_id
+from .audit_log import safe_audit
+from .config import commit_if_enabled, get_agent_id
+from .kv_scopes import KV
+from .privacy import strip_private_data
+
+
+def reinforce_lesson(lesson: Dict[str, Any]) -> None:
+    now = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
+    lesson["reinforcements"] = lesson.get("reinforcements", 0) + 1
+    conf = lesson.get("confidence", 0.5)
+    lesson["confidence"] = min(1.0, conf + 0.1 * (1 - conf))
+    lesson["lastReinforcedAt"] = now
+    lesson["updatedAt"] = now
+
+
+def lesson_save(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
+    content = data.get("content")
+    if not content or not content.strip():
+        return {"success": False, "error": "content is required"}
+    content = strip_private_data(content)
+    context_str = strip_private_data(data.get("context") or "")
+
+    agent_id = data.get("agentId") or get_agent_id()
+    fp = fingerprint_id("lsn", content)
+    existing = kv.get(KV.lessons, fp)
+
+    if existing and not existing.get("deleted"):
+        reinforce_lesson(existing)
+        if context_str and not existing.get("context"):
+            existing["context"] = context_str
+        kv.set(KV.lessons, existing["id"], existing)
+        safe_audit(kv, "lesson_strengthen", "mem::lesson-save", [existing["id"]])
+
+        commit_if_enabled(
+            kv, f"Strengthen lesson: {existing.get('content', '')[:60]}", agent_id
+        )
+
+        return {"success": True, "action": "strengthened", "lesson": existing}
+
+    confidence = data.get("confidence")
+    if not isinstance(confidence, (int, float)) or confidence < 0 or confidence > 1:
+        confidence = 0.5
+
+    now = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
+    lesson = {
+        "id": fp,
+        "content": content.strip(),
+        "context": context_str.strip(),
+        "confidence": confidence,
+        "reinforcements": 0,
+        "source": data.get("source") or "manual",
+        "sourceIds": data.get("sourceIds") or [],
+        "project": data.get("project"),
+        "tags": data.get("tags") or [],
+        "createdAt": now,
+        "updatedAt": now,
+        "decayRate": 0.05,
+    }
+    kv.set(KV.lessons, lesson["id"], lesson)
+    safe_audit(kv, "lesson_save", "mem::lesson-save", [lesson["id"]])
+
+    commit_if_enabled(kv, f"Create lesson: {lesson['content'][:60]}", agent_id)
+
+    return {"success": True, "action": "created", "lesson": lesson}
+
+
+def lesson_list(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
+    limit = data.get("limit") or 50
+    min_confidence = data.get("minConfidence") or 0.0
+    all_lessons = kv.list(KV.lessons)
+
+    lessons = [
+        les
+        for les in all_lessons
+        if not les.get("deleted") and les.get("confidence", 0.5) >= min_confidence
+    ]
+
+    project = data.get("project")
+    if project:
+        lessons = [les for les in lessons if les.get("project") == project]
+    source = data.get("source")
+    if source:
+        lessons = [les for les in lessons if les.get("source") == source]
+
+    lessons.sort(key=lambda x: x.get("confidence", 0.5), reverse=True)
+    return {"success": True, "lessons": lessons[:limit]}
+
+
+def lesson_recall(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
+    query = data.get("query")
+    if not query or not query.strip():
+        return {"success": False, "error": "query is required"}
+
+    query_lower = query.lower()
+    min_confidence = data.get("minConfidence") or 0.1
+    limit = data.get("limit") or 10
+
+    all_lessons = kv.list(KV.lessons)
+    lessons = [
+        les
+        for les in all_lessons
+        if not les.get("deleted") and les.get("confidence", 0.5) >= min_confidence
+    ]
+
+    project = data.get("project")
+    if project:
+        lessons = [les for les in lessons if les.get("project") == project]
+
+    scored = []
+    terms = [t for t in query_lower.split() if len(t) > 1]
+
+    for les in lessons:
+        text = f"{les.get('content', '')} {les.get('context', '')} {' '.join(les.get('tags') or [])}".lower()
+        match_count = sum(1 for t in terms if t in text)
+        if match_count == 0:
+            continue
+
+        relevance = match_count / len(terms)
+        baseline = les.get("lastReinforcedAt") or les.get("createdAt")
+        import dateutil.parser
+
+        dt = dateutil.parser.parse(baseline)
+        days = (
+            datetime.datetime.now(datetime.timezone.utc)
+            - dt.replace(tzinfo=datetime.timezone.utc)
+        ).total_seconds() / (3600 * 24)
+        recency_boost = 1 / (1 + days * 0.01)
+        score = les.get("confidence", 0.5) * relevance * recency_boost
+        scored.append({"lesson": les, "score": score})
+
+    scored.sort(key=lambda x: x["score"], reverse=True)
+    results = []
+    for s in scored[:limit]:
+        item = dict(s["lesson"])
+        item["score"] = round(s["score"], 3)
+        results.append(item)
+
+    safe_audit(
+        kv,
+        "lesson_recall",
+        "mem::lesson-recall",
+        [],
+        {"query": query, "resultCount": len(results)},
+    )
+    return {"success": True, "lessons": results}
+
+
+def lesson_strengthen(kv: StateKV, lesson_id: str) -> Dict[str, Any]:
+    lesson = kv.get(KV.lessons, lesson_id)
+    if not lesson or lesson.get("deleted"):
+        return {"success": False, "error": "lesson not found"}
+
+    reinforce_lesson(lesson)
+    kv.set(KV.lessons, lesson["id"], lesson)
+    safe_audit(kv, "lesson_strengthen", "mem::lesson-strengthen", [lesson["id"]])
+
+    commit_if_enabled(
+        kv, f"Strengthen lesson: {lesson.get('content', '')[:60]}", get_agent_id()
+    )
+
+    return {"success": True, "lesson": lesson}
+
+
+def lesson_decay_sweep(kv: StateKV) -> Dict[str, Any]:
+    all_lessons = kv.list(KV.lessons)
+    decayed = 0
+    soft_deleted = 0
+    now = datetime.datetime.now(datetime.timezone.utc)
+    timestamp = now.isoformat().replace("+00:00", "Z")
+
+    for les in all_lessons:
+        if les.get("deleted"):
+            continue
+        baseline_str = (
+            les.get("lastDecayedAt") or les.get("lastReinforcedAt") or les["createdAt"]
+        )
+        import dateutil.parser
+
+        dt = dateutil.parser.parse(baseline_str)
+        weeks = (now - dt.replace(tzinfo=datetime.timezone.utc)).total_seconds() / (
+            3600 * 24 * 7
+        )
+        if weeks < 1.0:
+            continue
+
+        decay = les.get("decayRate", 0.05) * weeks
+        new_conf = max(0.05, les.get("confidence", 0.5) - decay)
+
+        if new_conf != les.get("confidence"):
+            before = les.get("confidence", 0.5)
+            les["confidence"] = round(new_conf, 3)
+            les["lastDecayedAt"] = timestamp
+            les["updatedAt"] = timestamp
+
+            if les["confidence"] <= 0.1 and les.get("reinforcements", 0) == 0:
+                les["deleted"] = True
+                soft_deleted += 1
+            else:
+                decayed += 1
+
+            kv.set(KV.lessons, les["id"], les)
+            safe_audit(
+                kv,
+                "lesson_strengthen",
+                "mem::lesson-decay-sweep",
+                [les["id"]],
+                {
+                    "action": "soft-delete" if les.get("deleted") else "decay",
+                    "actor": "system",
+                    "reason": "decay-sweep",
+                    "before": {"confidence": before, "deleted": False},
+                    "after": {
+                        "confidence": les["confidence"],
+                        "deleted": bool(les.get("deleted")),
+                    },
+                },
+            )
+
+    if decayed > 0 or soft_deleted > 0:
+        commit_if_enabled(
+            kv,
+            f"Lesson decay sweep: decayed {decayed}, soft-deleted {soft_deleted}",
+            "system",
+        )
+
+    return {
+        "success": True,
+        "decayed": decayed,
+        "softDeleted": soft_deleted,
+        "total": len(all_lessons),
+    }