agent-memory-engine 0.1.0__py3-none-any.whl

agent_memory/controller/consolidation.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+from math import sqrt
+from typing import Any
+
+from agent_memory.extraction.prompts import CONSOLIDATION_PROMPT
+from agent_memory.llm.base import LLMClient
+from agent_memory.models import MemoryDraft, MemoryItem, MemoryType
+
+
+CONSOLIDATION_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "content": {"type": "string"},
+        "memory_type": {"type": "string", "enum": ["semantic", "episodic", "procedural"]},
+        "importance": {"type": "number"},
+        "tags": {"type": "array", "items": {"type": "string"}},
+    },
+    "required": ["content", "memory_type", "importance", "tags"],
+    "additionalProperties": False,
+}
+
+
+@dataclass(slots=True)
+class ConsolidationPlanner:
+    similarity_threshold: float = 0.9
+    recency_window_days: float = 45.0
+
+    def group_by_entities(self, memories: list[MemoryItem]) -> dict[str, list[MemoryItem]]:
+        grouped: dict[str, list[MemoryItem]] = defaultdict(list)
+        for memory in memories:
+            if not memory.entity_refs:
+                continue
+            grouped[memory.entity_refs[0].lower()].append(memory)
+        return {key: value for key, value in grouped.items() if len(value) > 1}
+
+    def find_merge_groups(self, memories: list[MemoryItem]) -> list[list[MemoryItem]]:
+        groups: list[list[MemoryItem]] = []
+        for entity_memories in self.group_by_entities(memories).values():
+            ordered = sorted(entity_memories, key=lambda item: item.created_at)
+            current_group: list[MemoryItem] = []
+            for memory in ordered:
+                if not current_group:
+                    current_group = [memory]
+                    continue
+                if self._should_merge(current_group[-1], memory):
+                    current_group.append(memory)
+                else:
+                    if len(current_group) > 1:
+                        groups.append(current_group)
+                    current_group = [memory]
+            if len(current_group) > 1:
+                groups.append(current_group)
+        return groups
+
+    def create_merged_draft(
+        self,
+        memories: list[MemoryItem],
+        *,
+        source_id: str,
+        llm_client: LLMClient | None = None,
+    ) -> MemoryDraft:
+        if llm_client is not None:
+            merged = self._create_merged_draft_with_llm(memories, source_id=source_id, llm_client=llm_client)
+            if merged is not None:
+                return merged
+        return self._create_merged_draft_heuristic(memories, source_id=source_id)
+
+    def _should_merge(self, left: MemoryItem, right: MemoryItem) -> bool:
+        age_gap_days = abs((right.created_at - left.created_at).total_seconds()) / 86400.0
+        if age_gap_days > self.recency_window_days:
+            return False
+        if not set(entity.lower() for entity in left.entity_refs) & set(entity.lower() for entity in right.entity_refs):
+            return False
+        return self._cosine_similarity(left.embedding, right.embedding) >= self.similarity_threshold
+
+    def _create_merged_draft_with_llm(
+        self,
+        memories: list[MemoryItem],
+        *,
+        source_id: str,
+        llm_client: LLMClient,
+    ) -> MemoryDraft | None:
+        prompt = "Merge these overlapping memories into one durable memory:\n" + "\n".join(
+            f"- {memory.content}" for memory in memories
+        )
+        response = llm_client.generate_json(
+            prompt=prompt,
+            schema=CONSOLIDATION_SCHEMA,
+            schema_name="memory_consolidation",
+            system_prompt=CONSOLIDATION_PROMPT,
+        )
+        content = str(response.get("content", "")).strip()
+        if not content:
+            return None
+        return MemoryDraft(
+            content=content,
+            memory_type=MemoryType(str(response.get("memory_type", "semantic"))),
+            importance=float(response.get("importance", 0.7)),
+            trust_score=max(memory.trust_score for memory in memories),
+            source_id=source_id,
+            entity_refs=sorted({entity for memory in memories for entity in memory.entity_refs}),
+            tags=sorted({tag for memory in memories for tag in memory.tags} | set(response.get("tags", [])) | {"consolidated"}),
+        )
+
+    def _create_merged_draft_heuristic(self, memories: list[MemoryItem], *, source_id: str) -> MemoryDraft:
+        ordered = sorted(
+            memories,
+            key=lambda item: (item.importance, item.trust_score, item.created_at),
+            reverse=True,
+        )
+        anchor = ordered[0]
+        return MemoryDraft(
+            content=anchor.content,
+            memory_type=anchor.memory_type,
+            importance=max(memory.importance for memory in memories),
+            trust_score=max(memory.trust_score for memory in memories),
+            source_id=source_id,
+            entity_refs=sorted({entity for memory in memories for entity in memory.entity_refs}),
+            tags=sorted({tag for memory in memories for tag in memory.tags} | {"consolidated"}),
+        )
+
+    def _cosine_similarity(self, left: list[float], right: list[float]) -> float:
+        if not left or not right:
+            return 0.0
+        size = min(len(left), len(right))
+        left_trimmed = left[:size]
+        right_trimmed = right[:size]
+        numerator = sum(a * b for a, b in zip(left_trimmed, right_trimmed, strict=False))
+        left_norm = sqrt(sum(a * a for a in left_trimmed))
+        right_norm = sqrt(sum(b * b for b in right_trimmed))
+        if left_norm == 0 or right_norm == 0:
+            return 0.0
+        return numerator / (left_norm * right_norm)

agent_memory/controller/forgetting.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import exp, log
+
+from agent_memory.models import MemoryItem, MemoryLayer
+
+
+@dataclass(slots=True)
+class ForgettingPolicy:
+    short_term_beta: float = 1.2
+    long_term_beta: float = 0.8
+    promote_threshold: float = 0.7
+    demote_threshold: float = 0.3
+
+    def effective_strength(self, memory: MemoryItem, age_days: float) -> float:
+        access_boost = 1 + log(1 + max(memory.access_count, 0))
+        beta = self.long_term_beta if memory.layer is MemoryLayer.LONG_TERM else self.short_term_beta
+        temporal_decay = exp(-memory.decay_rate * (age_days**beta))
+        return memory.importance * memory.trust_score * access_boost * temporal_decay
+
+    def next_layer(self, memory: MemoryItem, age_days: float) -> MemoryLayer:
+        strength = self.effective_strength(memory, age_days=age_days)
+        if strength >= self.promote_threshold:
+            return MemoryLayer.LONG_TERM
+        if strength <= self.demote_threshold:
+            return MemoryLayer.SHORT_TERM
+        return memory.layer
+

agent_memory/controller/router.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+import re
+
+from agent_memory.models import QueryIntent, RetrievalPlan
+
+
+INTENT_PATTERNS: list[tuple[QueryIntent, tuple[str, ...]]] = [
+    (QueryIntent.CAUSAL, ("为什么", "为何", "导致", "cause", "caused", "why")),
+    (QueryIntent.TEMPORAL, ("上周", "最近", "之前", "刚才", "when", "recent", "before")),
+    (QueryIntent.PROCEDURAL, ("如何", "怎么", "步骤", "how to", "how do", "step")),
+    (QueryIntent.EXPLORATORY, ("关于", "all about", "everything about", "related to")),
+    (QueryIntent.FACTUAL, ("什么是", "谁是", "what is", "who is", "which")),
+]
+
+
+@dataclass(slots=True)
+class IntentRouter:
+    def classify(self, query: str) -> QueryIntent:
+        normalized = query.lower()
+        for intent, patterns in INTENT_PATTERNS:
+            if any(pattern in normalized for pattern in patterns):
+                return intent
+        return QueryIntent.GENERAL
+
+    def plan(self, query: str) -> RetrievalPlan:
+        intent = self.classify(query)
+        if intent is QueryIntent.FACTUAL:
+            return RetrievalPlan(intent=intent, strategies=["semantic", "entity", "full_text"])
+        if intent is QueryIntent.TEMPORAL:
+            return RetrievalPlan(
+                intent=intent,
+                strategies=["semantic", "full_text"],
+                filters={"sort": "recency"},
+            )
+        if intent is QueryIntent.CAUSAL:
+            return RetrievalPlan(intent=intent, strategies=["semantic", "full_text", "causal_trace"])
+        if intent is QueryIntent.EXPLORATORY:
+            return RetrievalPlan(intent=intent, strategies=["entity", "semantic", "full_text"])
+        if intent is QueryIntent.PROCEDURAL:
+            return RetrievalPlan(
+                intent=intent,
+                strategies=["semantic", "full_text"],
+                filters={"memory_type": "procedural"},
+            )
+        return RetrievalPlan(intent=intent, strategies=["semantic", "full_text"])
+
+
+def reciprocal_rank_fusion(rankings: dict[str, list[str]], k: int = 60) -> dict[str, float]:
+    scores: dict[str, float] = defaultdict(float)
+    for ranked_ids in rankings.values():
+        for rank, item_id in enumerate(ranked_ids, start=1):
+            scores[item_id] += 1.0 / (k + rank)
+    return dict(sorted(scores.items(), key=lambda item: item[1], reverse=True))
+
+
+def strip_intent_markers(query: str) -> str:
+    pattern = re.compile(r"(为什么|为何|导致|what is|who is|how to|how do|all about|everything about)", re.IGNORECASE)
+    return pattern.sub(" ", query).strip()
+

agent_memory/controller/trust.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class TrustScorer:
+    recency_weight: float = 0.15
+    corroboration_weight: float = 0.15
+    contradiction_weight: float = 0.2
+    source_weight: float = 0.5
+
+    def score(
+        self,
+        *,
+        source_reliability: float,
+        corroboration_count: int = 0,
+        contradiction_count: int = 0,
+        age_days: float = 0.0,
+    ) -> float:
+        recency_bonus = max(0.0, 1.0 - min(age_days, 90.0) / 90.0)
+        corroboration_bonus = min(corroboration_count, 5) / 5.0
+        contradiction_penalty = min(contradiction_count, 5) / 5.0
+        raw_score = (
+            source_reliability * self.source_weight
+            + recency_bonus * self.recency_weight
+            + corroboration_bonus * self.corroboration_weight
+            - contradiction_penalty * self.contradiction_weight
+        )
+        return max(0.0, min(1.0, raw_score))
+

agent_memory/embedding/__init__.py

@@ -0,0 +1,5 @@
+from agent_memory.embedding.local_provider import LocalEmbeddingProvider
+from agent_memory.embedding.openai_provider import OpenAIEmbeddingProvider
+
+__all__ = ["LocalEmbeddingProvider", "OpenAIEmbeddingProvider"]
+

agent_memory/embedding/base.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class EmbeddingProvider(Protocol):
+    dimension: int
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        ...
+

agent_memory/embedding/local_provider.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import hashlib
+
+
+class LocalEmbeddingProvider:
+    def __init__(self, dimension: int = 384, model_name: str = "sentence-transformers/all-MiniLM-L6-v2") -> None:
+        self.dimension = dimension
+        self.model_name = model_name
+        self._model = None
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        model = self._load_model()
+        if model is None:
+            return [self._hash_embed(text) for text in texts]
+        return [list(vector) for vector in model.encode(texts, normalize_embeddings=True)]
+
+    def _load_model(self):
+        if self._model is not None:
+            return self._model
+        try:
+            from sentence_transformers import SentenceTransformer
+        except ImportError:
+            return None
+        self._model = SentenceTransformer(self.model_name)
+        return self._model
+
+    def _hash_embed(self, text: str) -> list[float]:
+        digest = hashlib.sha256(text.encode("utf-8")).digest()
+        values: list[float] = []
+        while len(values) < self.dimension:
+            for byte in digest:
+                values.append((byte / 255.0) * 2 - 1)
+                if len(values) == self.dimension:
+                    break
+            digest = hashlib.sha256(digest).digest()
+        return values
+

agent_memory/embedding/openai_provider.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+
+class OpenAIEmbeddingProvider:
+    def __init__(self, model: str = "text-embedding-3-small", dimension: int = 1536) -> None:
+        self.model = model
+        self.dimension = dimension
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        raise RuntimeError("Install the OpenAI SDK and wire API calls before using OpenAIEmbeddingProvider.")
+

agent_memory/extraction/__init__.py

@@ -0,0 +1,5 @@
+from agent_memory.extraction.entity_extractor import EntityExtractor
+from agent_memory.extraction.pipeline import ConversationMemoryPipeline
+
+__all__ = ["ConversationMemoryPipeline", "EntityExtractor"]
+

agent_memory/extraction/entity_extractor.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+import re
+
+
+class EntityExtractor:
+    def extract(self, text: str) -> list[str]:
+        entities = set()
+        entities.update(re.findall(r"#([\w-]+)", text))
+        entities.update(re.findall(r"\b[A-Z][A-Za-z0-9_-]{1,}\b", text))
+        entities.update(re.findall(r"[\u4e00-\u9fff]{2,8}", text))
+        return sorted(entity.strip() for entity in entities if entity.strip())
+

agent_memory/extraction/pipeline.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from agent_memory.extraction.entity_extractor import EntityExtractor
+from agent_memory.extraction.prompts import EXTRACT_FACTS_PROMPT
+from agent_memory.llm.base import LLMClient
+from agent_memory.models import ConversationTurn, MemoryDraft, MemoryType
+
+
+PREFERENCE_MARKERS = ("喜欢", "偏好", "需要", "负责", "正在做", "prefer", "need", "working on", "building", "goal", "目标", "because", "因为")
+IGNORE_PATTERNS = ("谢谢", "收到", "好的", "ok", "okay", "got it", "明白", "哈哈", "lol")
+MEMORY_EXTRACTION_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "memories": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "content": {"type": "string"},
+                    "memory_type": {"type": "string", "enum": ["semantic", "episodic", "procedural"]},
+                    "importance": {"type": "number"},
+                    "trust_score": {"type": "number"},
+                    "tags": {"type": "array", "items": {"type": "string"}},
+                },
+                "required": ["content", "memory_type", "importance", "trust_score", "tags"],
+                "additionalProperties": False,
+            },
+        }
+    },
+    "required": ["memories"],
+    "additionalProperties": False,
+}
+
+
+class ConversationMemoryPipeline:
+    def __init__(self, entity_extractor: EntityExtractor | None = None, llm_client: LLMClient | None = None) -> None:
+        self.entity_extractor = entity_extractor or EntityExtractor()
+        self.llm_client = llm_client
+
+    def extract(self, turns: list[ConversationTurn], source_id: str) -> list[MemoryDraft]:
+        if self.llm_client is not None:
+            try:
+                drafts = self._extract_with_llm(turns=turns, source_id=source_id)
+                if drafts:
+                    return drafts
+            except Exception:
+                pass
+        return self._extract_heuristically(turns=turns, source_id=source_id)
+
+    def _extract_with_llm(self, turns: list[ConversationTurn], source_id: str) -> list[MemoryDraft]:
+        transcript = "\n".join(f"{turn.role}: {turn.content}" for turn in turns)
+        response = self.llm_client.generate_json(
+            prompt=f"Conversation:\n{transcript}",
+            schema=MEMORY_EXTRACTION_SCHEMA,
+            schema_name="memory_extraction",
+            system_prompt=EXTRACT_FACTS_PROMPT,
+        )
+        drafts: list[MemoryDraft] = []
+        for item in response.get("memories", []):
+            content = str(item.get("content", "")).strip()
+            if not content:
+                continue
+            drafts.append(
+                MemoryDraft(
+                    content=content,
+                    memory_type=MemoryType(str(item.get("memory_type", "semantic"))),
+                    importance=float(item.get("importance", 0.5)),
+                    trust_score=float(item.get("trust_score", 0.7)),
+                    source_id=source_id,
+                    entity_refs=self.entity_extractor.extract(content),
+                    tags=list(item.get("tags", [])),
+                )
+            )
+        return drafts
+
+    def _extract_heuristically(self, turns: list[ConversationTurn], source_id: str) -> list[MemoryDraft]:
+        drafts: list[MemoryDraft] = []
+        seen_contents: set[str] = set()
+        for turn in turns:
+            if turn.role != "user":
+                continue
+            sentences = [segment.strip() for segment in re.split(r"[。！？!?\.]", turn.content) if segment.strip()]
+            for sentence in sentences:
+                if len(sentence) < 6:
+                    continue
+                normalized = sentence.lower()
+                if any(pattern in normalized for pattern in IGNORE_PATTERNS):
+                    continue
+                score = self._sentence_score(normalized)
+                if score < 1:
+                    continue
+                content = sentence.strip()
+                if content in seen_contents:
+                    continue
+                seen_contents.add(content)
+                drafts.append(
+                    MemoryDraft(
+                        content=content,
+                        memory_type=MemoryType.PROCEDURAL if self._looks_procedural(normalized) else MemoryType.SEMANTIC,
+                        importance=min(1.0, 0.4 + 0.15 * score),
+                        trust_score=0.75,
+                        source_id=source_id,
+                        entity_refs=self.entity_extractor.extract(content),
+                        tags=["conversation", turn.role, "heuristic"],
+                    )
+                )
+        return drafts
+
+    def _sentence_score(self, normalized_sentence: str) -> int:
+        score = 0
+        if any(marker in normalized_sentence for marker in PREFERENCE_MARKERS):
+            score += 1
+        if any(keyword in normalized_sentence for keyword in ("always", "usually", "habit", "习惯", "偏好", "因为", "reason")):
+            score += 1
+        if len(normalized_sentence) > 32:
+            score += 1
+        return score
+
+    def _looks_procedural(self, normalized_sentence: str) -> bool:
+        return any(marker in normalized_sentence for marker in ("how to", "步骤", "流程", "先", "然后", "最后"))

agent_memory/extraction/prompts.py

@@ -0,0 +1,40 @@
+EXTRACT_FACTS_PROMPT = """
+You extract durable long-term memories from conversations for an agent memory engine.
+
+Only keep information that is likely to matter across future sessions.
+Prioritize:
+- stable preferences
+- identity or role information
+- long-running goals
+- durable procedural knowledge
+- causal explanations for important decisions
+
+Ignore:
+- chit-chat
+- acknowledgements
+- one-off small talk
+- transient details unless they explain an important choice
+
+Return JSON only.
+"""
+
+CONFLICT_JUDGE_PROMPT = """
+You compare two candidate memories and decide whether they:
+- contradict
+- supersede
+- support each other
+- should both be kept
+Return a short rationale and a resolution label.
+"""
+
+CONSOLIDATION_PROMPT = """
+You merge semantically overlapping memories into one durable summary.
+
+Produce one canonical memory that:
+- preserves the most useful stable facts
+- keeps causal rationale when important
+- avoids duplicates
+- uses concise wording
+
+Return JSON only.
+"""

agent_memory/governance/__init__.py

@@ -0,0 +1,6 @@
+from agent_memory.governance.audit import AuditLogReader
+from agent_memory.governance.export import MemoryExporter, MemoryImporter
+from agent_memory.governance.health import MemoryHealthMonitor
+
+__all__ = ["AuditLogReader", "MemoryExporter", "MemoryHealthMonitor", "MemoryImporter"]
+

agent_memory/governance/audit.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agent_memory.storage.sqlite_backend import SQLiteBackend
+
+
+@dataclass(slots=True)
+class AuditLogReader:
+    backend: SQLiteBackend
+
+    def recent(self, limit: int = 50) -> list[dict[str, object]]:
+        return self.backend.get_audit_events(limit=limit)
+

agent_memory/governance/export.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from datetime import datetime
+from enum import Enum
+import json
+from pathlib import Path
+
+from agent_memory.models import MemoryItem, MemoryLayer, MemoryType, RelationEdge, RelationType
+from agent_memory.storage.sqlite_backend import SQLiteBackend
+
+
+def _serialize_value(value: object) -> object:
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, list):
+        return [_serialize_value(item) for item in value]
+    return value
+
+
+@dataclass(slots=True)
+class MemoryExporter:
+    backend: SQLiteBackend
+
+    def export_jsonl(self, path: str) -> int:
+        destination = Path(path)
+        count = 0
+        with destination.open("w", encoding="utf-8") as handle:
+            for memory in self.backend.list_memories(include_deleted=True):
+                payload = {key: _serialize_value(value) for key, value in asdict(memory).items()}
+                handle.write(json.dumps({"type": "memory", "payload": payload}, ensure_ascii=False) + "\n")
+                count += 1
+            for relation in self.backend.list_relations():
+                payload = {key: _serialize_value(value) for key, value in asdict(relation).items()}
+                handle.write(json.dumps({"type": "relation", "payload": payload}, ensure_ascii=False) + "\n")
+        return count
+
+
+@dataclass(slots=True)
+class MemoryImporter:
+    backend: SQLiteBackend
+
+    def import_jsonl(self, path: str) -> int:
+        source = Path(path)
+        count = 0
+        memories: list[MemoryItem] = []
+        relations: list[RelationEdge] = []
+        with source.open("r", encoding="utf-8") as handle:
+            for line in handle:
+                entry = json.loads(line)
+                if entry["type"] == "memory":
+                    payload = entry["payload"]
+                    for key in ("created_at", "last_accessed", "valid_from", "valid_until", "deleted_at"):
+                        if payload.get(key):
+                            payload[key] = datetime.fromisoformat(payload[key])
+                    payload["memory_type"] = MemoryType(payload["memory_type"])
+                    payload["layer"] = MemoryLayer(payload["layer"])
+                    memories.append(MemoryItem(**payload))
+                elif entry["type"] == "relation":
+                    payload = entry["payload"]
+                    payload["created_at"] = datetime.fromisoformat(payload["created_at"])
+                    payload["relation_type"] = RelationType(payload["relation_type"])
+                    relations.append(RelationEdge(**payload))
+        for memory in sorted(memories, key=lambda item: (item.causal_parent_id is not None, item.created_at)):
+            if self.backend.get_memory(memory.id) is None:
+                self.backend.add_memory(memory)
+                count += 1
+        for edge in relations:
+            self.backend.add_relation(edge)
+        return count

agent_memory/governance/health.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from agent_memory.models import HealthReport
+from agent_memory.storage.sqlite_backend import SQLiteBackend
+
+
+@dataclass(slots=True)
+class MemoryHealthMonitor:
+    backend: SQLiteBackend
+
+    def generate(self) -> HealthReport:
+        snapshot = self.backend.health_snapshot()
+        suggestions: list[str] = []
+        if snapshot["stale_ratio"] >= 0.3:
+            suggestions.append("30%+ memories are stale; run a forgetting cycle.")
+        if snapshot["orphan_ratio"] >= 0.2:
+            suggestions.append("Orphan ratio is high; consolidate or attach relation edges.")
+        if snapshot["unresolved_conflicts"] > 0:
+            suggestions.append("Resolve contradiction edges to improve trust calibration.")
+
+        size = 0
+        if self.backend.database_path != ":memory:":
+            path = Path(self.backend.database_path)
+            if path.exists():
+                size = path.stat().st_size
+
+        return HealthReport(
+            total_memories=int(snapshot["total_memories"]),
+            stale_ratio=float(snapshot["stale_ratio"]),
+            orphan_ratio=float(snapshot["orphan_ratio"]),
+            unresolved_conflicts=int(snapshot["unresolved_conflicts"]),
+            average_trust_score=float(snapshot["average_trust_score"]),
+            database_size_bytes=size,
+            audit_events=int(snapshot["audit_events"]),
+            suggestions=suggestions,
+        )
+

agent_memory/interfaces/__init__.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+__all__ = ["create_mcp_server", "create_rest_app"]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "create_mcp_server":
+        return import_module("agent_memory.interfaces.mcp_server").create_mcp_server
+    if name == "create_rest_app":
+        return import_module("agent_memory.interfaces.rest_api").create_rest_app
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")