agentdatabase 0.1.0__py3-none-any.whl

agentdb/adapters/hermes.py

@@ -0,0 +1,247 @@
+"""
+AgentDBHermesProvider — Hermes MemoryProvider adapter.
+
+Implements Hermes's MemoryProvider ABC on top of GatewayAdapter so that
+any Hermes agent can use AgentDB as its governed external memory backend.
+Direct in-process import; no sidecar, no HTTP.
+
+Principle 12 compliance:
+  12a hooks (real-time, synchronous): prefetch, sync_turn, on_turn_start,
+      on_memory_write, handle_tool_call, system_prompt_block
+  12b hooks (async/decoupled): on_session_end, on_pre_compress, on_delegation
+
+Limitation: on_memory_write cannot veto Hermes-native writes — it fires
+after the write has already landed in Hermes's own store. AgentDB governance
+covers AgentDB's own records only, not Hermes-native storage.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+try:
+    from agent.memory_provider import MemoryProvider  # real Hermes install
+except ImportError:
+    # Hermes not installed — stub ABC so tests run without it
+    from abc import ABC, abstractmethod
+
+    class MemoryProvider(ABC):  # type: ignore[no-redef]
+        @abstractmethod
+        def initialize(self, session_id: str, **kwargs) -> None: ...
+        @abstractmethod
+        def system_prompt_block(self) -> str: ...
+        @abstractmethod
+        def prefetch(self, query: str, *, session_id: str) -> list: ...
+        def queue_prefetch(self, query: str, *, session_id: str) -> None: ...
+        @abstractmethod
+        def sync_turn(self, user: str, asst: str, *, session_id: str) -> None: ...
+        def get_tool_schemas(self) -> list: ...
+        def handle_tool_call(self, name: str, args: dict, *, session_id: str): ...
+        def shutdown(self) -> None: ...
+        def on_turn_start(self, turn: int, message: str, **kwargs) -> None: ...
+        def on_session_end(self, messages: list) -> None: ...
+        def on_session_switch(self, new_session_id: str, **kwargs) -> None: ...
+        def on_pre_compress(self, messages: list) -> str: ...
+        def on_memory_write(self, action: str, target: str, content: str, metadata: dict) -> None: ...
+        def on_delegation(self, task: str, result: str, **kwargs) -> None: ...
+        def backup_paths(self) -> list[str]: ...
+
+
+from agentdb.gateway.adapter import GatewayAdapter
+
+if TYPE_CHECKING:
+    from agentdb import AgentDB
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class AgentDBHermesProvider(MemoryProvider, GatewayAdapter):
+    """
+    Hermes MemoryProvider backed by AgentDB.
+
+    Usage:
+        db = AgentDB(db_path="agentdb.sqlite")
+        provider = AgentDBHermesProvider(db=db, agent_id="coder")
+        # Register with Hermes MemoryManager, then let Hermes call hooks.
+    """
+
+    def __init__(self, db: "AgentDB", agent_id: str) -> None:
+        GatewayAdapter.__init__(self, db, agent_id, profile=db.config_for(agent_id)["name"])
+        self._session_id: str = ""
+
+    # ------------------------------------------------------------------
+    # Phase 1 — core governed memory loop (Principle 12a)
+    # ------------------------------------------------------------------
+
+    def initialize(self, session_id: str, **kwargs) -> None:
+        """Store session_id, wire conflict handler, dispatch conversation_started."""
+        self._session_id = session_id
+        self.gateway.subscribe("conflict_detected", self._on_conflict)
+        self.gateway.dispatch("conversation_started", session_id=session_id)
+
+    def prefetch(self, query: str, *, session_id: str) -> list:
+        """Return governed records ranked for this query. [12a]"""
+        result = self._db.retrieve(query, agent_id=self._agent_id, session_id=session_id)
+        return result.records
+
+    def sync_turn(self, user: str, asst: str, *, session_id: str) -> None:
+        """Persist assistant reply as a governed episodic record. [12a]"""
+        if asst:
+            self._db.write(
+                key=f"memory/hermes/{self._agent_id}/{session_id}/turn",
+                value=asst,
+                origin="agent_inferred",
+                agent_id=self._agent_id,
+                session_id=session_id,
+            )
+
+    def on_turn_start(self, turn: int, message: str, **kwargs) -> None:
+        """Dispatch reconciliation trigger at the start of each turn. [12a]"""
+        self.gateway.dispatch(
+            "conversation_started",
+            session_id=self._session_id,
+            turn=turn,
+        )
+
+    # ------------------------------------------------------------------
+    # system_prompt_block [12a]
+    # ------------------------------------------------------------------
+
+    def system_prompt_block(self) -> str:
+        """
+        Inject governed skills into Hermes's system prompt.
+
+        Returns a '## Governed Skills' section if any skills exist for this
+        agent; empty string otherwise.
+        """
+        skills = self._db.skills.get_for_agent(self._agent_id)
+        if not skills:
+            return ""
+        lines = ["## Governed Skills"]
+        for skill in skills:
+            warning = ""
+            if skill.health_score < 0.6:
+                warning = f" [STALE — health_score={skill.health_score:.2f}]"
+            lines.append(f"### {skill.name}{warning}")
+            lines.append(skill.content)
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------------
+    # Remaining hooks
+    # ------------------------------------------------------------------
+
+    def queue_prefetch(self, query: str, *, session_id: str) -> None:
+        """No-op — AgentDB retrieval is always a live query; nothing to pre-warm."""
+
+    def get_tool_schemas(self) -> list:
+        """No tool schemas exposed — AgentDB governance is transparent to the LLM."""
+        return []
+
+    def handle_tool_call(self, name: str, args: dict, *, session_id: str) -> Any:
+        """Route memory tool calls to db.read() or db.retrieve(). [12a]"""
+        if name == "memory_get":
+            key = args.get("key", "")
+            return self._db.read(key, agent_id=self._agent_id)
+        if name == "memory_search":
+            query = args.get("query", "")
+            return self._db.retrieve(query, agent_id=self._agent_id, session_id=session_id).records
+        return None
+
+    def shutdown(self) -> None:
+        """No-op — SQLite closes with the process."""
+
+    def on_session_end(self, messages: list) -> None:
+        """Record session outcome and check for pending conflicts. [12b]"""
+        if self._session_id:
+            self._db.lifecycle.record_outcome(
+                session_id=self._session_id,
+                agent_id=self._agent_id,
+                outcome_type="session_end",
+                outcome_value=1.0,
+            )
+
+    def on_session_switch(self, new_session_id: str, **kwargs) -> None:
+        """Re-scope internal session reference on session rotation."""
+        self._session_id = new_session_id
+
+    def on_pre_compress(self, messages: list) -> str:
+        """
+        Call configured summarizer if available; write summary as governed record.
+        Returns summary string, or '' to let Hermes handle compaction natively. [12b]
+        """
+        summarizer: Optional[Callable] = self._db._summarizer
+        if summarizer is None:
+            return ""
+        summary: str = summarizer(messages)
+        ts = _utcnow().strftime("%Y%m%dT%H%M%SZ")
+        self._db.write(
+            key=f"memory/episodic/hermes/{self._agent_id}/{self._session_id}/compaction-{ts}",
+            value=summary,
+            origin="agent_inferred",
+            agent_id=self._agent_id,
+            session_id=self._session_id,
+        )
+        return summary
+
+    def on_memory_write(
+        self,
+        action: str,
+        target: str,
+        content: str,
+        metadata: dict,
+    ) -> None:
+        """
+        Mirror Hermes-native memory writes for AgentDB governance audit. [12a]
+
+        NOTE: This hook cannot veto Hermes-native writes — it fires after
+        the write has already landed in Hermes's own store. Governance here
+        covers AgentDB's own records only.
+
+        Scope: only writes targeting MEMORY.md or DREAMS.md are governed;
+        high-frequency ephemeral daily notes are skipped.
+        """
+        governed_targets = {"MEMORY.md", "DREAMS.md"}
+        if Path(target).name not in governed_targets:
+            return
+        # Permission check is intentionally skipped here: this is a governance mirror of a
+        # Hermes-native write that already passed Hermes's own permission checks. AgentDB
+        # records the write for provenance tracking but cannot and should not re-gate it.
+        self._db.write(
+            key=f"memory/hermes-mirror/{self._agent_id}/{target}",
+            value=content,
+            origin="agent_inferred",
+            agent_id=self._agent_id,
+            session_id=self._session_id,
+        )
+
+    def on_delegation(self, task: str, result: str, **kwargs) -> None:
+        """Write subagent task result as a governed episodic record. [12b]"""
+        if result:
+            ts = _utcnow().strftime("%Y%m%dT%H%M%SZ")
+            self._db.write(
+                key=f"memory/episodic/hermes/{self._agent_id}/{self._session_id}/delegation-{ts}",
+                value=result,
+                origin="agent_inferred",
+                agent_id=self._agent_id,
+                session_id=self._session_id,
+            )
+
+    def backup_paths(self) -> list[str]:
+        """Return the AgentDB file path for backup tooling."""
+        if hasattr(self._db, "_path") and self._db._path and str(self._db._path) != ":memory:":
+            return [str(self._db._path)]
+        return []
+
+    # ------------------------------------------------------------------
+    # Internal handlers
+    # ------------------------------------------------------------------
+
+    def _on_conflict(self, **payload) -> None:
+        """
+        Platform-agnostic conflict handler.
+        Concrete notification wiring is platform-specific (Slack, Telegram, etc.).
+        """
+        pass

agentdb/backend.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import fnmatch
+from typing import Any, Optional
+
+from .governance.permission_router import PermissionDenied
+from .interface.client import AgentDB
+
+
+class AgentDBBackend:
+    """
+    A simple key-value interface over AgentDB for a specific agent.
+
+    trust_zone: "agent_inferred" or "human_approved"
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        trust_zone: str,
+        db: AgentDB,
+    ) -> None:
+        self._agent_id = agent_id
+        self._trust_zone = trust_zone
+        self.db = db
+
+    def write(self, key: str, value: Any) -> None:
+        """Write a value. Raises PermissionDenied if not allowed."""
+        # Derive origin from trust_zone
+        origin = "human_approved" if self._trust_zone == "human_approved" else "agent_inferred"
+        self.db.write(
+            key=key,
+            value=value,
+            origin=origin,
+            agent_id=self._agent_id,
+        )
+
+    def read(self, key: str) -> Optional[Any]:
+        """Read a value by key. Returns None if not found."""
+        record = self.db.read(key, agent_id=self._agent_id)
+        if record is None:
+            return None
+        return record.value
+
+    def delete(self, key: str) -> None:
+        """Delete/archive a record by key. Raises PermissionDenied if not allowed."""
+        self.db.delete(key, agent_id=self._agent_id, trust_zone=self._trust_zone)
+
+    def list(self, prefix: str) -> list[str]:
+        """List all keys that start with prefix, scoped to this agent."""
+        records = self.db._store.list_by_agent(self._agent_id)
+        return [r.key for r in records if r.key.startswith(prefix)]
+
+    def grep(self, pattern: str, prefix: str = "") -> list[str]:
+        """Return keys whose values contain the given string pattern, scoped to this agent."""
+        records = self.db._store.list_by_agent(self._agent_id)
+        results: list[str] = []
+        pattern_lower = pattern.lower()
+        for record in records:
+            if prefix and not record.key.startswith(prefix):
+                continue
+            import json
+            value_str = (
+                json.dumps(record.value)
+                if isinstance(record.value, (dict, list))
+                else str(record.value)
+            ).lower()
+            if pattern_lower in value_str:
+                results.append(record.key)
+        return results
+
+    def glob(self, pattern: str) -> list[str]:
+        """Return keys matching an fnmatch glob pattern, scoped to this agent."""
+        records = self.db._store.list_by_agent(self._agent_id)
+        return [r.key for r in records if fnmatch.fnmatch(r.key, pattern)]

agentdb/core/__init__.py

@@ -0,0 +1,19 @@
+from .models import (
+    Origin,
+    TrustLevel,
+    ExpiryPolicy,
+    MemoryTier,
+    MemoryRecord,
+    ConflictRecord,
+    Skill,
+)
+
+__all__ = [
+    "Origin",
+    "TrustLevel",
+    "ExpiryPolicy",
+    "MemoryTier",
+    "MemoryRecord",
+    "ConflictRecord",
+    "Skill",
+]

agentdb/core/directory_tracking.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def collect_directory_snapshots(
+    directories: list[str],
+    base_dir: Any = ".",
+    max_files_per_directory: int = 200,
+) -> list[dict]:
+    """
+    Collect a snapshot of each directory (relative to base_dir).
+
+    Returns a list of dicts:
+        {directory, exists, file_count, entries: [{path, ...}]}
+
+    paths in entries are relative to base_dir.
+    If a directory doesn't exist: {directory, exists=False, file_count=0, entries=[]}
+    """
+    base = Path(base_dir)
+    results: list[dict] = []
+
+    for directory in directories:
+        full_path = base / directory
+        if not full_path.exists():
+            results.append(
+                {
+                    "directory": directory,
+                    "exists": False,
+                    "file_count": 0,
+                    "entries": [],
+                }
+            )
+            continue
+
+        entries: list[dict] = []
+        count = 0
+        for item in sorted(full_path.rglob("*")):
+            if item.is_file():
+                if count >= max_files_per_directory:
+                    break
+                try:
+                    rel = item.relative_to(base)
+                    entries.append({"path": str(rel)})
+                except ValueError:
+                    entries.append({"path": str(item)})
+                count += 1
+
+        results.append(
+            {
+                "directory": directory,
+                "exists": True,
+                "file_count": count,
+                "entries": entries,
+            }
+        )
+
+    return results

agentdb/core/file_integrity.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def compute_file_sha256(path: Any) -> str:
+    """Return the SHA-256 hex digest (64 chars) of the file at path."""
+    p = Path(path)
+    h = hashlib.sha256()
+    with p.open("rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+@dataclass
+class FileObservation:
+    path: str
+    sha256: str
+    size_bytes: int
+    captured_at: str
+    modified_at: str
+
+    def to_dict(self) -> dict:
+        return {
+            "path": self.path,
+            "sha256": self.sha256,
+            "size_bytes": self.size_bytes,
+            "captured_at": self.captured_at,
+            "modified_at": self.modified_at,
+        }
+
+
+def observe_file(path: Any, base_dir: Optional[Any] = None) -> FileObservation:
+    """
+    Observe a single file and return a FileObservation.
+
+    path: the file to observe (absolute or relative)
+    base_dir: if provided, the returned .path is relative to base_dir
+    """
+    p = Path(path)
+    sha = compute_file_sha256(p)
+    stat = p.stat()
+    size_bytes = stat.st_size
+    captured_at = _utcnow().isoformat()
+    modified_at = datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc).isoformat()
+
+    if base_dir is not None:
+        try:
+            rel_path = str(p.relative_to(Path(base_dir)))
+        except ValueError:
+            rel_path = str(p)
+    else:
+        rel_path = str(p)
+
+    return FileObservation(
+        path=rel_path,
+        sha256=sha,
+        size_bytes=size_bytes,
+        captured_at=captured_at,
+        modified_at=modified_at,
+    )
+
+
+def observe_files(paths: list) -> list[dict]:
+    """Observe multiple files and return a list of to_dict() results."""
+    results = []
+    for p in paths:
+        obs = observe_file(p)
+        results.append(obs.to_dict())
+    return results

agentdb/core/models.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Optional
+
+
+class Origin(str, Enum):
+    HUMAN_APPROVED = "human_approved"
+    AGENT_INFERRED = "agent_inferred"
+    PROVIDER_INGESTED = "provider_ingested"
+
+
+class TrustLevel(str, Enum):
+    SEALED = "sealed"
+    HUMAN = "human"
+    AGENT = "agent"
+    PROVIDER = "provider"
+
+
+class ExpiryPolicy(str, Enum):
+    PERMANENT = "permanent"
+    EPISODIC = "episodic"
+    SESSION = "session"
+
+
+class MemoryTier(str, Enum):
+    WORKING = "working"
+    EPISODIC = "episodic"
+    LONG_TERM = "long_term"
+    ORG = "org"
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _new_uuid() -> str:
+    return str(uuid.uuid4())
+
+
+@dataclass
+class MemoryRecord:
+    key: str
+    value: Any
+    origin: str  # Origin enum value or raw string
+    trust_level: str  # TrustLevel enum value or raw string
+    agent_id: str
+    id: str = field(default_factory=_new_uuid)
+    confidence: float = 1.0
+    version: int = 1
+    archived: bool = False
+    retrieval_count: int = 0
+    created_at: datetime = field(default_factory=_utcnow)
+    entities: list = field(default_factory=list)
+    last_retrieved: Optional[datetime] = None
+    conflict_id: Optional[str] = None
+    expiry_time: Optional[datetime] = None
+    inferred: bool = False
+    working_dirs: list = field(default_factory=list)
+    embedding: Optional[list[float]] = field(default=None, repr=False)
+
+
+@dataclass
+class ConflictRecord:
+    record_a_id: str
+    record_b_id: str
+    conflict_type: str
+    id: str = field(default_factory=_new_uuid)
+    resolved: bool = False
+    auto_resolved: bool = False
+
+
+@dataclass
+class Skill:
+    id: str
+    name: str
+    content: str
+    authored_by: str
+    scope: list
+    version: str = "1.0.0"
+    archived: bool = False
+    health_score: float = 1.0
+    health_score_reasons: list = field(default_factory=list)
+    created_at: datetime = field(default_factory=_utcnow)
+    updated_at: datetime = field(default_factory=_utcnow)
+    last_retrieved: Optional[datetime] = None
+    parent_skill_id: Optional[str] = None

agentdb/core/profiles.py

@@ -0,0 +1,116 @@
+"""
+Built-in AgentDB profiles.
+
+To add a new built-in profile: define a new Profile(...) below and add it
+to BUILTIN_PROFILES. To change what "budget_optimized" means: edit the
+BUDGET_OPTIMIZED instance directly -- every field is named, typed, and
+lives on its own dataclass below.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class LifecycleSettings:
+    confidence_decay_rate: float
+    archival_threshold: float
+    staleness_days: int
+    reinforce_rate: float
+
+
+@dataclass(frozen=True)
+class RankerWeights:
+    provenance: float
+    recency: float
+    confidence: float
+    causal: float
+    semantic: float
+    workspace: float = 0.0  # opt-in; weight 0.0 = disabled
+
+
+@dataclass(frozen=True)
+class RetrievalSettings:
+    retrieve_limit: int
+    conflict_threshold: float  # currently unused elsewhere in the codebase; reserved
+    min_composite_score: float  # records ranked below this score are excluded; 0.0 = no threshold
+    ranker_weights: RankerWeights
+
+
+@dataclass(frozen=True)
+class InjectionSettings:
+    context_token_limit: int
+    memory_budget_chars: int
+    memory_header: str
+    override_prefix: str
+    record_line_format: str
+
+
+@dataclass(frozen=True)
+class CaptureSettings:
+    conversation_jsonl: bool
+    tracking_max_files_per_directory: int
+    auto_persist_response: bool
+
+
+@dataclass(frozen=True)
+class Profile:
+    name: str
+    lifecycle: LifecycleSettings
+    retrieval: RetrievalSettings
+    injection: InjectionSettings
+    capture: CaptureSettings
+
+
+_SHARED_INJECTION_TEXT = dict(
+    memory_header="Background context from previous sessions (supplemental — current conversation and user request take priority):",
+    override_prefix="Override instruction:",
+    record_line_format="- {key}: {value}",
+)
+
+BUDGET_OPTIMIZED = Profile(
+    name="budget_optimized",
+    lifecycle=LifecycleSettings(
+        confidence_decay_rate=0.0, archival_threshold=0.10, staleness_days=90, reinforce_rate=0.10,
+    ),
+    retrieval=RetrievalSettings(
+        retrieve_limit=5, conflict_threshold=0.85, min_composite_score=0.0,
+        ranker_weights=RankerWeights(provenance=0.35, recency=0.25, confidence=0.25, causal=0.15, semantic=0.0, workspace=0.0),
+    ),
+    injection=InjectionSettings(context_token_limit=1000, memory_budget_chars=2000, **_SHARED_INJECTION_TEXT),
+    capture=CaptureSettings(
+        conversation_jsonl=False, tracking_max_files_per_directory=200, auto_persist_response=False,
+    ),
+)
+
+FULL_STORAGE = Profile(
+    name="full_storage",
+    lifecycle=LifecycleSettings(
+        confidence_decay_rate=0.0, archival_threshold=0.0, staleness_days=3650, reinforce_rate=0.10,
+    ),
+    retrieval=RetrievalSettings(
+        retrieve_limit=200, conflict_threshold=0.85, min_composite_score=0.0,
+        ranker_weights=RankerWeights(provenance=0.35, recency=0.25, confidence=0.25, causal=0.15, semantic=0.0, workspace=0.0),
+    ),
+    injection=InjectionSettings(context_token_limit=50000, memory_budget_chars=200000, **_SHARED_INJECTION_TEXT),
+    capture=CaptureSettings(
+        conversation_jsonl=True, tracking_max_files_per_directory=10000, auto_persist_response=True,
+    ),
+)
+
+RESEARCH = Profile(
+    name="research",
+    lifecycle=LifecycleSettings(
+        confidence_decay_rate=0.0, archival_threshold=0.05, staleness_days=180, reinforce_rate=0.10,
+    ),
+    retrieval=RetrievalSettings(
+        retrieve_limit=50, conflict_threshold=0.85, min_composite_score=0.0,
+        ranker_weights=RankerWeights(provenance=0.25, recency=0.35, confidence=0.25, causal=0.15, semantic=0.0, workspace=0.0),
+    ),
+    injection=InjectionSettings(context_token_limit=8000, memory_budget_chars=24000, **_SHARED_INJECTION_TEXT),
+    capture=CaptureSettings(
+        conversation_jsonl=True, tracking_max_files_per_directory=500, auto_persist_response=True,
+    ),
+)
+
+BUILTIN_PROFILES: dict[str, Profile] = {p.name: p for p in (BUDGET_OPTIMIZED, FULL_STORAGE, RESEARCH)}