agentdatabase 0.1.0__py3-none-any.whl

agentdb/interface/mcp_server.py

@@ -0,0 +1,96 @@
+"""
+AgentDB MCP server — stdio transport (Claude Desktop).
+
+HTTP+SSE transport: same tool definitions, transport="sse",
+X-AgentDB-Key auth middleware, agentdb-mcp-http entry point.
+"""
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from agentdb import AgentDB
+
+mcp = FastMCP("AgentDB")
+_db: Optional[AgentDB] = None
+
+
+def _get_db() -> AgentDB:
+    global _db
+    if _db is None:
+        _db = AgentDB(memory_dir=os.environ.get("AGENTDB_MEMORY_DIR"))
+    return _db
+
+
+@mcp.tool()
+def memory_write(
+    key: str,
+    value: str,
+    origin: str,
+    agent_id: str,
+    session_id: Optional[str] = None,
+    confidence: Optional[float] = None,
+    entities: Optional[list] = None,
+) -> dict:
+    """Write a governed memory record."""
+    record = _get_db().write(
+        key=key,
+        value=value,
+        origin=origin,
+        agent_id=agent_id,
+        session_id=session_id,
+        confidence=confidence,
+        entities=entities or [],
+    )
+    return {"id": record.id, "key": record.key, "origin": str(record.origin)}
+
+
+@mcp.tool()
+def memory_retrieve(
+    query: str,
+    agent_id: str,
+    limit: Optional[int] = None,
+    session_id: Optional[str] = None,
+    budget_tokens: Optional[int] = None,
+) -> dict:
+    """Retrieve governed memory records ranked by multi-signal ranker."""
+    result = _get_db().retrieve(
+        query=query,
+        agent_id=agent_id,
+        limit=limit,
+        session_id=session_id,
+        budget_tokens=budget_tokens,
+    )
+    return {
+        "records": [
+            {"id": r.id, "key": r.key, "value": r.value, "origin": str(r.origin)}
+            for r in result.records
+        ],
+        "conflicts": [str(c) for c in result.conflicts],
+        "override_instructions": result.override_instructions,
+        "token_estimate": result.token_estimate,
+        "truncated": result.truncated,
+    }
+
+
+@mcp.tool()
+def conflict_queue(resolved: bool = False) -> dict:
+    """Return pending conflicts from the governance gateway."""
+    conflicts = _get_db().gateway.conflict_queue(resolved=resolved)
+    return {"conflicts": conflicts, "count": len(conflicts)}
+
+
+@mcp.tool()
+def memory_stats() -> dict:
+    """Return database-wide statistics."""
+    return _get_db().system.agentdb_stats()
+
+
+def main() -> None:
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

agentdb/retrieval/__init__.py

@@ -0,0 +1,3 @@
+from .algorithm import MultiSignalRanker, RankedRecord
+
+__all__ = ["MultiSignalRanker", "RankedRecord"]

agentdb/retrieval/algorithm.py

@@ -0,0 +1,207 @@
+"""
+Multi-signal memory ranking algorithm.
+
+This is the algorithmic core of AgentDB. It is not the marketing lead —
+it is what makes the database worth using.
+
+Signals (weights are starting defaults, all configurable):
+  provenance  (0.35) — human_approved > provider_ingested > agent_inferred
+                        Novel: trust level as a first-class ranking factor.
+  recency     (0.25) — exponential decay from last_retrieved (falling back
+                        to created_at for a record never retrieved),
+                        modulated by retrieval frequency. Frequently-
+                        retrieved memories decay slower.
+  confidence  (0.25) — direct passthrough of record.confidence (0-1).
+  causal      (0.15) — how often was this memory retrieved before
+                        successful task completions? Phase 2
+                        approximation: retrieval_count weighted by
+                        recency. Full WAL-correlation in Phase 4.
+
+Semantic signal (cosine similarity against query embedding) is added in
+Phase 3 when embeddings are active. Until then, semantic weight is 0 and
+the remaining four signals carry full weight.
+"""
+
+import math
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Optional
+
+from ..core.models import MemoryRecord, Origin
+
+
+@dataclass
+class RankedRecord:
+    record: MemoryRecord
+    composite_score: float
+    signal_breakdown: dict
+    conflict_flag: bool
+    staleness_warning: bool
+
+
+_PROVENANCE_SCORES = {
+    Origin.HUMAN_APPROVED: 1.0,
+    Origin.PROVIDER_INGESTED: 0.6,
+    Origin.AGENT_INFERRED: 0.3,
+}
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _aware(dt: datetime) -> datetime:
+    return dt if dt.tzinfo is not None else dt.replace(tzinfo=timezone.utc)
+
+
+class MultiSignalRanker:
+    """
+    All weights must sum to 1.0.
+    semantic_weight is 0.0 until Phase 3 activates embeddings.
+    """
+
+    def __init__(
+        self,
+        weight_provenance: float = 0.35,
+        weight_recency: float = 0.25,
+        weight_confidence: float = 0.25,
+        weight_causal: float = 0.15,
+        weight_semantic: float = 0.0,  # activated in Phase 3
+        weight_workspace: float = 0.0,  # Jaccard overlap with session working dirs
+        recency_lambda: float = 0.01,  # decay rate; 0.01 ~= half-life 69 days
+        staleness_days: int = 90,
+        provenance_scores: Optional[dict] = None,
+    ):
+        total = (
+            weight_provenance + weight_recency + weight_confidence
+            + weight_causal + weight_semantic + weight_workspace
+        )
+        if abs(total - 1.0) > 1e-6:
+            raise ValueError(f"Signal weights must sum to 1.0, got {total}")
+        self.w_provenance = weight_provenance
+        self.w_recency = weight_recency
+        self.w_confidence = weight_confidence
+        self.w_causal = weight_causal
+        self.w_semantic = weight_semantic
+        self.w_workspace = weight_workspace
+        self._lambda = recency_lambda
+        self._staleness_days = staleness_days
+        self._provenance = provenance_scores or _PROVENANCE_SCORES
+
+    def rank(
+        self,
+        query: str,
+        candidates: list,
+        agent_id: str,
+        query_embedding: Optional[list] = None,
+        session_id: Optional[str] = None,
+        session_working_dirs: Optional[list] = None,
+    ) -> list:
+        if not candidates:
+            return []
+
+        now = _utcnow()
+        results = []
+        for record in candidates:
+            prov = self._provenance_score(record)
+            rec = self._recency_score(record, now)
+            conf = record.confidence
+            causal = self._causal_score(record, now)
+            embedding = getattr(record, "embedding", None)
+            sem = (
+                self._semantic_score(query_embedding, embedding)
+                if query_embedding and embedding else 0.0
+            )
+            workspace = self._workspace_score(record, session_working_dirs)
+
+            composite = (
+                self.w_provenance * prov
+                + self.w_recency * rec
+                + self.w_confidence * conf
+                + self.w_causal * causal
+                + self.w_semantic * sem
+                + self.w_workspace * workspace
+            )
+
+            ref_time = self._reference_time(record)
+            days_since = (now - ref_time).total_seconds() / 86400
+            results.append(RankedRecord(
+                record=record,
+                composite_score=round(min(max(composite, 0.0), 1.0), 6),
+                signal_breakdown={
+                    "provenance": round(prov, 4),
+                    "recency": round(rec, 4),
+                    "confidence": round(conf, 4),
+                    "causal": round(causal, 4),
+                    "semantic": round(sem, 4),
+                    "workspace": round(workspace, 4),
+                },
+                conflict_flag=bool(getattr(record, "conflict_id", None)),
+                staleness_warning=days_since > self._staleness_days,
+            ))
+
+        results.sort(key=lambda x: x.composite_score, reverse=True)
+        return results
+
+    def _reference_time(self, record: MemoryRecord) -> datetime:
+        ref = getattr(record, "last_retrieved", None) or record.created_at
+        return _aware(ref)
+
+    def _provenance_score(self, record: MemoryRecord) -> float:
+        return self._provenance.get(record.origin, 0.3)
+
+    def _recency_score(self, record: MemoryRecord, now: datetime) -> float:
+        """
+        Exponential decay from last_retrieved (or created_at if never
+        retrieved). Frequently-retrieved memories decay slower:
+          score = exp(-lambda * days) * (1 + log(retrieval_count + 1) * 0.1)
+        Capped at 1.0.
+        """
+        ref_time = self._reference_time(record)
+        days = max((now - ref_time).total_seconds() / 86400, 0)
+        base = math.exp(-self._lambda * days)
+        freq_boost = 1.0 + math.log(record.retrieval_count + 1) * 0.1
+        return min(base * freq_boost, 1.0)
+
+    def _causal_score(self, record: MemoryRecord, now: datetime) -> float:
+        """
+        Phase 2 approximation: retrieval frequency weighted by recency.
+        High retrieval_count + recent last_retrieved = high causal
+        relevance. Full WAL-derived correlation deferred to Phase 4.
+        """
+        if record.retrieval_count == 0:
+            return 0.0
+        freq_score = min(math.log(record.retrieval_count + 1) / math.log(101), 1.0)
+        recency_weight = self._recency_score(record, now)
+        return freq_score * recency_weight
+
+    def _workspace_score(
+        self, record: "MemoryRecord", session_working_dirs: Optional[list]
+    ) -> float:
+        """Jaccard similarity between record's working_dirs and session's working_dirs.
+
+        Returns 0.5 (neutral) when either side has no data, so legacy records
+        are not penalized and sessions with no working_dirs don't distort scores.
+        """
+        rec_dirs = set(getattr(record, "working_dirs", []) or [])
+        sess_dirs = set(session_working_dirs or [])
+        if not rec_dirs or not sess_dirs:
+            return 0.5
+        intersection = rec_dirs & sess_dirs
+        union = rec_dirs | sess_dirs
+        return len(intersection) / len(union)
+
+    def _semantic_score(self, query_embedding: list, record_embedding: list) -> float:
+        """Cosine similarity. Uses numpy if available, falls back to pure
+        Python otherwise."""
+        try:
+            import numpy as np
+            a = np.array(query_embedding)
+            b = np.array(record_embedding)
+            denom = np.linalg.norm(a) * np.linalg.norm(b)
+            return float(np.dot(a, b) / denom) if denom > 0 else 0.0
+        except ImportError:
+            dot = sum(x * y for x, y in zip(query_embedding, record_embedding))
+            mag_a = math.sqrt(sum(x * x for x in query_embedding))
+            mag_b = math.sqrt(sum(x * x for x in record_embedding))
+            return max(dot / (mag_a * mag_b), 0.0) if mag_a and mag_b else 0.0

agentdb/skills/__init__.py

@@ -0,0 +1,3 @@
+from .skill_store import SkillStore, SkillStoreError
+
+__all__ = ["SkillStore", "SkillStoreError"]

agentdb/skills/skill_store.py

@@ -0,0 +1,351 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from contextlib import contextmanager
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from ..core.models import Skill
+
+
+class SkillStoreError(Exception):
+    pass
+
+
+class SkillConflict(SkillStoreError):
+    """Raised when update() is called while multiple active versions exist.
+
+    Resolve or archive the existing active versions before adding a new one.
+    """
+    pass
+
+
+_CREATE_SKILLS_TABLE = """
+CREATE TABLE IF NOT EXISTS skills (
+    id TEXT NOT NULL,
+    name TEXT NOT NULL,
+    content TEXT NOT NULL,
+    authored_by TEXT NOT NULL,
+    scope TEXT NOT NULL,
+    version TEXT NOT NULL,
+    archived INTEGER NOT NULL DEFAULT 0,
+    health_score REAL NOT NULL DEFAULT 1.0,
+    health_score_reasons TEXT NOT NULL DEFAULT '[]',
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    last_retrieved TEXT,
+    parent_skill_id TEXT,
+    PRIMARY KEY (id, version)
+)
+"""
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _row_to_skill(row: sqlite3.Row) -> Skill:
+    return Skill(
+        id=row["id"],
+        name=row["name"],
+        content=row["content"],
+        authored_by=row["authored_by"],
+        scope=json.loads(row["scope"]),
+        version=row["version"],
+        archived=bool(row["archived"]),
+        health_score=row["health_score"],
+        health_score_reasons=json.loads(row["health_score_reasons"]),
+        created_at=datetime.fromisoformat(row["created_at"]),
+        updated_at=datetime.fromisoformat(row["updated_at"]),
+        last_retrieved=datetime.fromisoformat(row["last_retrieved"]) if row["last_retrieved"] else None,
+        parent_skill_id=row["parent_skill_id"],
+    )
+
+
+def _compute_health(skill: Skill) -> tuple[float, list[str]]:
+    """Compute health score based on staleness since last retrieval (or
+    creation, for a skill that has never been retrieved)."""
+    now = _utcnow()
+    reference = skill.last_retrieved or skill.created_at
+    if reference.tzinfo is None:
+        reference = reference.replace(tzinfo=timezone.utc)
+    age_days = (now - reference).days
+    health_score = 1.0
+    reasons: list[str] = []
+    if age_days > 30:
+        # Decay formula: steeper than linear to ensure > 45 days gives health < 0.6
+        # max(0.1, 1.0 - (age_days - 30) * 0.03)
+        health_score = max(0.1, 1.0 - (age_days - 30) * 0.03)
+        reasons.append("staleness")
+    return health_score, reasons
+
+
+class SkillStore:
+    def __init__(
+        self,
+        db_path: Any,
+        on_stale_crossing: Optional[Callable[[str], None]] = None,
+    ) -> None:
+        self._db_path = Path(db_path)
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        self.on_stale_crossing = on_stale_crossing
+        with self._connect() as conn:
+            conn.execute(_CREATE_SKILLS_TABLE)
+
+    @contextmanager
+    def _connect(self):
+        conn = sqlite3.connect(str(self._db_path))
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA journal_mode=WAL")
+        try:
+            yield conn
+            conn.commit()
+        except Exception:
+            conn.rollback()
+            raise
+        finally:
+            conn.close()
+
+    def create(self, skill: Skill) -> Skill:
+        if skill.authored_by != "human":
+            raise SkillStoreError(
+                f"Skills may only be authored by humans, got '{skill.authored_by}'"
+            )
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO skills
+                    (id, name, content, authored_by, scope, version, archived,
+                     health_score, health_score_reasons, created_at, updated_at,
+                     last_retrieved, parent_skill_id)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    skill.id,
+                    skill.name,
+                    skill.content,
+                    skill.authored_by,
+                    json.dumps(skill.scope),
+                    skill.version,
+                    int(skill.archived),
+                    skill.health_score,
+                    json.dumps(skill.health_score_reasons),
+                    skill.created_at.isoformat(),
+                    skill.updated_at.isoformat(),
+                    skill.last_retrieved.isoformat() if skill.last_retrieved else None,
+                    skill.parent_skill_id,
+                ),
+            )
+        return skill
+
+    def get(self, skill_id: str) -> Optional[Skill]:
+        """
+        Returns the latest non-archived version of the skill.
+        Falls back to oldest non-archived if all newer versions are archived.
+        """
+        with self._connect() as conn:
+            # Get all non-archived versions, ordered newest first
+            rows = conn.execute(
+                """
+                SELECT * FROM skills
+                WHERE id = ? AND archived = 0
+                ORDER BY created_at DESC
+                """,
+                (skill_id,),
+            ).fetchall()
+
+        if not rows:
+            return None
+
+        # Return the first (newest) non-archived row
+        skill = _row_to_skill(rows[0])
+        return skill
+
+    def update(self, skill_id: str, content: str, new_version: str) -> Skill:
+        """
+        Create a new version of the skill with parent_skill_id=skill_id.
+        Raises SkillConflict if more than one active version already exists.
+        The count check and INSERT run in the same transaction to avoid a
+        TOCTOU window between the guard and the write.
+        """
+        original = self.get(skill_id)
+        if original is None:
+            raise SkillStoreError(f"Skill '{skill_id}' not found")
+
+        now = _utcnow()
+        new_skill = Skill(
+            id=skill_id,
+            name=original.name,
+            content=content,
+            authored_by=original.authored_by,
+            scope=original.scope,
+            version=new_version,
+            archived=False,
+            health_score=1.0,
+            health_score_reasons=[],
+            created_at=now,
+            updated_at=now,
+            last_retrieved=None,
+            parent_skill_id=skill_id,
+        )
+        with self._connect() as conn:
+            count = conn.execute(
+                "SELECT COUNT(*) FROM skills WHERE id = ? AND archived = 0",
+                (skill_id,),
+            ).fetchone()[0]
+            if count > 1:
+                raise SkillConflict(
+                    f"Skill '{skill_id}' has unresolved active versions — "
+                    f"archive or reconcile existing versions before updating"
+                )
+            conn.execute(
+                """
+                INSERT INTO skills
+                    (id, name, content, authored_by, scope, version, archived,
+                     health_score, health_score_reasons, created_at, updated_at,
+                     last_retrieved, parent_skill_id)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    new_skill.id,
+                    new_skill.name,
+                    new_skill.content,
+                    new_skill.authored_by,
+                    json.dumps(new_skill.scope),
+                    new_skill.version,
+                    int(new_skill.archived),
+                    new_skill.health_score,
+                    json.dumps(new_skill.health_score_reasons),
+                    new_skill.created_at.isoformat(),
+                    new_skill.updated_at.isoformat(),
+                    None,
+                    new_skill.parent_skill_id,
+                ),
+            )
+        return new_skill
+
+    def get_for_agent(self, agent_id: str) -> list[Skill]:
+        """
+        Returns non-archived skills where agent_id is in scope.
+        Computes health_score based on staleness. Fires on_stale_crossing
+        callback exactly once when health first crosses below 0.6.
+        """
+        with self._connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT * FROM skills WHERE archived = 0
+                ORDER BY created_at DESC
+                """
+            ).fetchall()
+
+        results: list[Skill] = []
+        seen_ids: set[str] = set()
+        for row in rows:
+            skill = _row_to_skill(row)
+            if skill.id in seen_ids:
+                continue
+            if agent_id not in skill.scope:
+                continue
+            seen_ids.add(skill.id)
+
+            stored_health = skill.health_score  # from DB — reflects last persisted score
+            new_health, reasons = _compute_health(skill)
+            skill.health_score = new_health
+            skill.health_score_reasons = reasons
+
+            # Detect first-time crossing below 0.6: persist so it won't re-fire
+            if stored_health >= 0.6 and new_health < 0.6:
+                self._persist_health_score(skill.id, skill.version, new_health)
+                if self.on_stale_crossing is not None:
+                    self.on_stale_crossing(skill.id)
+
+            results.append(skill)
+
+        return results
+
+    def mark_retrieved(self, skill_id: str) -> None:
+        now = _utcnow().isoformat()
+        with self._connect() as conn:
+            conn.execute(
+                """
+                UPDATE skills SET last_retrieved = ?
+                WHERE id = ? AND archived = 0
+                """,
+                (now, skill_id),
+            )
+
+    def _persist_health_score(self, skill_id: str, version: str, health_score: float) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                "UPDATE skills SET health_score = ? WHERE id = ? AND version = ?",
+                (health_score, skill_id, version),
+            )
+
+    def archive(self, skill_id: str, version: str) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                UPDATE skills SET archived = 1
+                WHERE id = ? AND version = ?
+                """,
+                (skill_id, version),
+            )
+
+    def list_all_active_ids(self) -> list[str]:
+        """Return composite IDs 'id:version' for all non-archived skills."""
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT id, version FROM skills WHERE archived = 0"
+            ).fetchall()
+        return [f"{row['id']}:{row['version']}" for row in rows]
+
+    def list_stale(self, agent_id: str, days: int = 30) -> list[Skill]:
+        """Returns non-archived skills for agent_id that are older than `days`."""
+        skills = self.get_for_agent(agent_id)
+        now = _utcnow()
+        stale = []
+        for skill in skills:
+            created_at = skill.created_at
+            if created_at.tzinfo is None:
+                created_at = created_at.replace(tzinfo=timezone.utc)
+            age_days = (now - created_at).days
+            if age_days > days:
+                stale.append(skill)
+        return stale
+
+    def search(self, query: str, agent_id: Optional[str] = None) -> list[Skill]:
+        """Case-insensitive keyword search across skill name and content.
+
+        If agent_id is given, only returns skills where agent_id is in scope.
+        Returns [] for an empty query.
+        """
+        words = [w.lower() for w in query.split() if w]
+        if not words:
+            return []
+
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT * FROM skills WHERE archived = 0 ORDER BY created_at DESC"
+            ).fetchall()
+
+        seen_ids: set[str] = set()
+        results: list[Skill] = []
+        for row in rows:
+            skill = _row_to_skill(row)
+            if skill.id in seen_ids:
+                continue
+            if agent_id is not None and agent_id not in skill.scope:
+                continue
+            name_lower = skill.name.lower()
+            content_lower = skill.content.lower()
+            for word in words:
+                if word in name_lower or word in content_lower:
+                    seen_ids.add(skill.id)
+                    new_health, reasons = _compute_health(skill)
+                    skill.health_score = new_health
+                    skill.health_score_reasons = reasons
+                    results.append(skill)
+                    break
+        return results