memorytrace 0.1.0__py3-none-any.whl

engram/models/fact.py

@@ -0,0 +1,58 @@
+"""Fact data models with temporal dimension."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+from engram.models.source import Source
+
+
+class FactStatus(str, Enum):
+    UNVERIFIED = "unverified"
+    VERIFIED = "verified"
+    CONFLICTED = "conflicted"
+    EXPIRED = "expired"
+    RETRACTED = "retracted"
+
+
+@dataclass
+class Fact:
+    """A single piece of knowledge about an entity, with provenance and temporal bounds."""
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    entity_id: str = ""
+    subject: str = ""
+    predicate: str = ""
+    object: str = ""
+    raw_text: str = ""
+    source: Source = field(default_factory=Source)
+    confidence: float = 0.5
+    status: FactStatus = FactStatus.UNVERIFIED
+    valid_from: Optional[datetime] = None
+    valid_to: Optional[datetime] = None  # None = currently valid
+    superseded_by: Optional[str] = None
+    created_at: datetime = field(default_factory=datetime.now)
+
+    def __post_init__(self) -> None:
+        self.confidence = max(0.0, min(1.0, self.confidence))
+
+    @property
+    def is_current(self) -> bool:
+        """Whether this fact is currently valid (not expired or superseded)."""
+        if self.valid_to is not None:
+            return False
+        if self.superseded_by is not None:
+            return False
+        if self.status in (FactStatus.EXPIRED, FactStatus.RETRACTED):
+            return False
+        return True
+
+    def supersede(self, new_fact_id: str) -> None:
+        """Mark this fact as superseded by another."""
+        self.superseded_by = new_fact_id
+        self.valid_to = datetime.now()
+        self.status = FactStatus.EXPIRED

engram/models/quality.py

@@ -0,0 +1,61 @@
+"""Quality gate data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+from engram.models.fact import Fact
+
+
+class Action(str, Enum):
+    ACCEPT = "accept"
+    QUARANTINE = "quarantine"
+    FLAG_CONFLICT = "flag_conflict"
+    REJECT = "reject"
+
+
+@dataclass
+class ConflictInfo:
+    """Information about a data conflict between facts."""
+
+    conflict_id: str = ""
+    existing_fact: Optional[Fact] = None
+    new_fact: Optional[Fact] = None
+    conflict_type: str = ""  # value_change, contradiction
+    suggested_resolution: str = ""  # supersede, manual_review, keep_old
+
+
+@dataclass
+class PIIMatch:
+    """A detected PII occurrence in text."""
+
+    pii_type: str = ""  # credit_card, ssn, api_key, email, phone, rrn
+    start: int = 0
+    end: int = 0
+    original: str = ""
+
+
+@dataclass
+class ValidationResult:
+    """Result of quality gate validation."""
+
+    action: Action = Action.ACCEPT
+    reason: str = ""
+    confidence: float = 0.0
+    conflicts: list[ConflictInfo] = field(default_factory=list)
+    pii_matches: list[PIIMatch] = field(default_factory=list)
+    masked_text: Optional[str] = None  # text after PII masking
+
+    @property
+    def is_accepted(self) -> bool:
+        return self.action == Action.ACCEPT
+
+    @property
+    def is_quarantined(self) -> bool:
+        return self.action == Action.QUARANTINE
+
+    @property
+    def has_conflicts(self) -> bool:
+        return self.action == Action.FLAG_CONFLICT

engram/models/relation.py

@@ -0,0 +1,26 @@
+"""Relation model for directed entity graph edges."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional
+
+
+@dataclass
+class Relation:
+    """A directed relationship between two entities."""
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    from_entity_id: str = ""
+    to_entity_id: str = ""
+    relation_type: str = ""  # CEO_OF, INVESTED_IN, WORKS_WITH, MEMBER_OF, etc.
+    metadata: dict = field(default_factory=dict)
+    valid_from: Optional[datetime] = None
+    valid_to: Optional[datetime] = None  # None = currently valid
+    created_at: datetime = field(default_factory=datetime.now)
+
+    @property
+    def is_current(self) -> bool:
+        return self.valid_to is None

engram/models/search.py

@@ -0,0 +1,96 @@
+"""Search-related data models."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional
+
+from engram.models.entity import Entity
+from engram.models.fact import Fact
+
+
+@dataclass
+class SearchOptions:
+    """Options for a memory search query."""
+
+    query: str = ""
+    max_results: int = 10
+    max_tokens: int = 500  # token budget for agent context
+    min_confidence: float = 0.0
+    entity_types: list[str] = field(default_factory=list)
+    tiers: list[str] = field(default_factory=list)
+    date_from: Optional[datetime] = None
+    date_to: Optional[datetime] = None
+    include_archived: bool = False
+
+
+@dataclass
+class SearchHit:
+    """A single search result."""
+
+    entity: Entity
+    facts: list[Fact] = field(default_factory=list)
+    relevance_score: float = 0.0
+    snippet: str = ""
+    token_count: int = 0
+
+
+@dataclass
+class SearchResult:
+    """Complete search response."""
+
+    query: str = ""
+    hits: list[SearchHit] = field(default_factory=list)
+    total_count: int = 0
+    search_time_ms: float = 0.0
+    total_tokens: int = 0
+
+    def to_agent_context(self, max_tokens: int = 500) -> str:
+        """Serialize to compact text for LLM context injection."""
+        if not self.hits:
+            return f"No results found for '{self.query}'."
+
+        parts: list[str] = []
+        tokens_used = 0
+        for hit in self.hits:
+            entry = f"[{hit.entity.name}] ({hit.entity.entity_type})"
+            if hit.entity.state.role:
+                entry += f" Role: {hit.entity.state.role}"
+            if hit.entity.state.affiliation:
+                entry += f" @ {hit.entity.state.affiliation}"
+            if hit.snippet:
+                entry += f" | {hit.snippet}"
+            # Rough token estimate: 1 token ≈ 4 chars
+            entry_tokens = len(entry) // 4
+            if tokens_used + entry_tokens > max_tokens:
+                break
+            parts.append(entry)
+            tokens_used += entry_tokens
+
+        return "\n".join(parts)
+
+    def to_dict(self) -> dict:
+        """Structured dict for MCP/SDK responses."""
+        return {
+            "query": self.query,
+            "total_count": self.total_count,
+            "search_time_ms": self.search_time_ms,
+            "hits": [
+                {
+                    "entity_name": h.entity.name,
+                    "entity_type": h.entity.entity_type,
+                    "relevance_score": h.relevance_score,
+                    "snippet": h.snippet,
+                    "facts": [
+                        {"text": f.raw_text, "confidence": f.confidence, "status": f.status.value}
+                        for f in h.facts
+                    ],
+                }
+                for h in self.hits
+            ],
+        }
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, indent=indent)

engram/models/session.py

@@ -0,0 +1,53 @@
+"""Session and session event models."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional
+
+
+@dataclass
+class Session:
+    """A conversation session with an AI agent."""
+
+    session_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    agent_id: str = "default"
+    started_at: datetime = field(default_factory=datetime.now)
+    ended_at: Optional[datetime] = None
+    parent_session_id: Optional[str] = None
+    entities_accessed: list[str] = field(default_factory=list)
+    entities_modified: list[str] = field(default_factory=list)
+    facts_added: list[str] = field(default_factory=list)
+    summary: Optional[str] = None
+    metadata: dict = field(default_factory=dict)
+
+    @property
+    def is_active(self) -> bool:
+        return self.ended_at is None
+
+    @property
+    def duration_seconds(self) -> Optional[float]:
+        if self.ended_at is None:
+            return None
+        return (self.ended_at - self.started_at).total_seconds()
+
+    @property
+    def duration_minutes(self) -> Optional[float]:
+        secs = self.duration_seconds
+        if secs is None:
+            return None
+        return round(secs / 60, 1)
+
+
+@dataclass
+class SessionEvent:
+    """An auditable event within a session."""
+
+    id: Optional[int] = None  # auto-increment in DB
+    session_id: str = ""
+    event_type: str = ""  # search, read, write, update, delete
+    target: str = ""  # entity_id or query string
+    detail: dict = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=datetime.now)

engram/models/source.py

@@ -0,0 +1,73 @@
+"""Source and provenance models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+
+class SourceType(str, Enum):
+    DIRECT_SPEECH = "direct_speech"
+    DOCUMENT = "document"
+    API = "api"
+    WEB = "web"
+    AGENT_INFERENCE = "agent_inference"
+    USER_INPUT = "user_input"
+
+
+# Base trust scores per source type
+_SOURCE_BASE_TRUST: dict[SourceType, float] = {
+    SourceType.DIRECT_SPEECH: 0.95,
+    SourceType.DOCUMENT: 0.85,
+    SourceType.USER_INPUT: 0.90,
+    SourceType.API: 0.80,
+    SourceType.WEB: 0.60,
+    SourceType.AGENT_INFERENCE: 0.40,
+}
+
+
+@dataclass
+class Source:
+    """Provenance metadata for a fact."""
+
+    type: SourceType = SourceType.USER_INPUT
+    author: str = ""
+    channel: str = ""  # meeting, email, slack, cli, mcp
+    timestamp: datetime = field(default_factory=datetime.now)
+    confidence: float = 1.0  # submitter's own confidence (0.0–1.0)
+    url: Optional[str] = None
+    session_id: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        self.confidence = max(0.0, min(1.0, self.confidence))
+
+    @property
+    def trust_score(self) -> float:
+        """Combined trust: base score for source type × submitter confidence."""
+        base = _SOURCE_BASE_TRUST.get(self.type, 0.5)
+        return base * self.confidence
+
+    def to_dict(self) -> dict:
+        return {
+            "type": self.type.value,
+            "author": self.author,
+            "channel": self.channel,
+            "timestamp": self.timestamp.isoformat(),
+            "confidence": self.confidence,
+            "url": self.url,
+            "session_id": self.session_id,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Source:
+        return cls(
+            type=SourceType(data.get("type", "user_input")),
+            author=data.get("author", ""),
+            channel=data.get("channel", ""),
+            timestamp=datetime.fromisoformat(data["timestamp"]) if data.get("timestamp") else datetime.now(),
+            confidence=data.get("confidence", 1.0),
+            url=data.get("url"),
+            session_id=data.get("session_id"),
+        )

engram/quality/__init__.py

@@ -0,0 +1,8 @@
+"""Quality gate system for Engram."""
+
+from engram.quality.gate import QualityGate
+from engram.quality.confidence import compute_confidence
+from engram.quality.conflict import ConflictDetector
+from engram.quality.pii import PIIDetector
+
+__all__ = ["QualityGate", "compute_confidence", "ConflictDetector", "PIIDetector"]

engram/quality/confidence.py

@@ -0,0 +1,38 @@
+"""Confidence scoring for facts based on source type and extraction method."""
+
+from __future__ import annotations
+
+from engram.models.source import SourceType
+
+# Base trust per source type
+_SOURCE_BASE: dict[SourceType, float] = {
+    SourceType.DIRECT_SPEECH: 0.95,
+    SourceType.USER_INPUT: 0.90,
+    SourceType.DOCUMENT: 0.85,
+    SourceType.API: 0.80,
+    SourceType.WEB: 0.60,
+    SourceType.AGENT_INFERENCE: 0.40,
+}
+
+# Multiplier per extraction method
+_EXTRACTION_MULT: dict[str, float] = {
+    "regex": 0.7,
+    "llm": 1.0,
+    "manual": 1.0,
+}
+
+
+def compute_confidence(
+    source_type: SourceType,
+    source_confidence: float,
+    extraction_method: str = "manual",
+) -> float:
+    """Compute final confidence score for a fact.
+
+    confidence = base_trust(source_type) × source_confidence × extraction_multiplier
+    Result is clamped to [0.0, 1.0].
+    """
+    base = _SOURCE_BASE.get(source_type, 0.5)
+    method_mult = _EXTRACTION_MULT.get(extraction_method, 0.7)
+    raw = base * max(0.0, min(1.0, source_confidence)) * method_mult
+    return max(0.0, min(1.0, round(raw, 4)))

engram/quality/conflict.py

@@ -0,0 +1,79 @@
+"""Conflict detection — finds when new facts contradict existing ones."""
+
+from __future__ import annotations
+
+import uuid
+
+from engram.models.fact import Fact
+from engram.models.quality import ConflictInfo
+from engram.storage.base import StorageBackend
+
+
+class ConflictDetector:
+    """Detects when a new fact contradicts existing facts for the same entity+predicate."""
+
+    def __init__(self, storage: StorageBackend):
+        self.storage = storage
+
+    def find_conflicts(self, new_fact: Fact) -> list[ConflictInfo]:
+        """Check if new_fact conflicts with any current facts.
+
+        A conflict occurs when:
+        - Same entity_id AND same predicate
+        - Different object value
+        - Both are currently valid (valid_to is None)
+        """
+        existing = self.storage.get_current_facts(new_fact.entity_id)
+        conflicts: list[ConflictInfo] = []
+
+        for old in existing:
+            if old.id == new_fact.id:
+                continue
+            if not self._same_predicate(new_fact, old):
+                continue
+            if self._same_object(new_fact, old):
+                continue
+
+            # Conflict found
+            resolution = self._suggest_resolution(old, new_fact)
+            conflicts.append(ConflictInfo(
+                conflict_id=str(uuid.uuid4()),
+                existing_fact=old,
+                new_fact=new_fact,
+                conflict_type="value_change",
+                suggested_resolution=resolution,
+            ))
+
+        return conflicts
+
+    def is_duplicate(self, new_fact: Fact) -> bool:
+        """Check if an identical fact already exists (same entity+predicate+object)."""
+        existing = self.storage.get_current_facts(new_fact.entity_id)
+        for old in existing:
+            if self._same_predicate(new_fact, old) and self._same_object(new_fact, old):
+                return True
+        return False
+
+    def _same_predicate(self, a: Fact, b: Fact) -> bool:
+        """Check if two facts refer to the same predicate (case-insensitive)."""
+        return a.predicate.strip().lower() == b.predicate.strip().lower()
+
+    def _same_object(self, a: Fact, b: Fact) -> bool:
+        """Check if two facts have the same value (case-insensitive, normalized)."""
+        import re
+        norm_a = re.sub(r'\b(the|a|an)\b', '', a.object.strip().lower()).strip()
+        norm_b = re.sub(r'\b(the|a|an)\b', '', b.object.strip().lower()).strip()
+        return norm_a == norm_b
+
+    def _suggest_resolution(self, old: Fact, new: Fact) -> str:
+        """Suggest how to resolve a conflict based on trust scores."""
+        old_trust = old.source.trust_score
+        new_trust = new.source.trust_score
+
+        trust_diff = new_trust - old_trust
+        if trust_diff > 0.3:
+            return "supersede"
+        elif trust_diff < -0.3:
+            return "keep_old"
+        else:
+            return "manual_review"

engram/quality/decay.py

@@ -0,0 +1,28 @@
+"""Time-based decay — identifies stale facts that need review."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from typing import Optional
+
+from engram.models.fact import Fact
+
+
+def find_stale_facts(
+    facts: list[Fact],
+    days: int = 90,
+    reference_time: Optional[datetime] = None,
+) -> list[Fact]:
+    """Find facts that haven't been updated within the given period.
+
+    Args:
+        facts: Facts to check.
+        days: Number of days before a fact is considered stale.
+        reference_time: Time to compare against (default: now).
+
+    Returns:
+        List of stale facts.
+    """
+    now = reference_time or datetime.now()
+    cutoff = now - timedelta(days=days)
+    return [f for f in facts if f.is_current and f.created_at < cutoff]

engram/quality/gate.py

@@ -0,0 +1,120 @@
+"""Quality gate — pipeline orchestrator for write validation."""
+
+from __future__ import annotations
+
+from engram.config import EngramConfig
+from engram.models.fact import Fact, FactStatus
+from engram.models.quality import Action, ConflictInfo, ValidationResult
+from engram.quality.confidence import compute_confidence
+from engram.quality.conflict import ConflictDetector
+from engram.quality.pii import PIIDetector
+from engram.storage.base import StorageBackend
+
+
+class QualityGate:
+    """Pipeline: confidence → PII masking → conflict detection → accept/reject/quarantine.
+
+    Every write operation passes through this gate before reaching storage.
+    """
+
+    def __init__(self, config: EngramConfig, storage: StorageBackend):
+        self.config = config
+        self.conflict_detector = ConflictDetector(storage)
+        self.pii_detector = PIIDetector()
+        self.min_confidence = config.min_confidence
+        self.auto_resolve_threshold = config.auto_resolve_threshold
+        self.enable_pii = config.enable_pii_detection
+
+    def validate(
+        self,
+        fact: Fact,
+        extraction_method: str = "manual",
+    ) -> ValidationResult:
+        """Run the full quality gate pipeline on a fact.
+
+        Returns ValidationResult with action:
+        - ACCEPT: fact is good, store it
+        - QUARANTINE: low confidence, store as unverified
+        - FLAG_CONFLICT: conflicts with existing data
+        - REJECT: should not be stored (e.g., all PII with no substance)
+        """
+
+        # Step 1: Compute confidence
+        computed_conf = compute_confidence(
+            source_type=fact.source.type,
+            source_confidence=fact.source.confidence,
+            extraction_method=extraction_method,
+        )
+        fact.confidence = computed_conf
+
+        # Step 2: PII detection and masking
+        pii_matches = []
+        masked_text = None
+        if self.enable_pii and fact.raw_text:
+            pii_matches = self.pii_detector.scan(fact.raw_text)
+            if pii_matches:
+                masked_text = self.pii_detector.mask(fact.raw_text, pii_matches)
+                fact.raw_text = masked_text
+                # Also mask subject/object if they contain PII
+                if self.pii_detector.has_pii(fact.object):
+                    fact.object = self.pii_detector.mask(fact.object)
+                if self.pii_detector.has_pii(fact.subject):
+                    fact.subject = self.pii_detector.mask(fact.subject)
+
+        # Step 3: Confidence threshold check
+        if computed_conf < self.min_confidence:
+            fact.status = FactStatus.UNVERIFIED
+            return ValidationResult(
+                action=Action.QUARANTINE,
+                reason=f"Confidence {computed_conf:.2f} below threshold {self.min_confidence:.2f}",
+                confidence=computed_conf,
+                pii_matches=pii_matches,
+                masked_text=masked_text,
+            )
+
+        # Step 3.5: Duplicate detection
+        if fact.entity_id and self.conflict_detector.is_duplicate(fact):
+            return ValidationResult(
+                action=Action.REJECT,
+                reason="Duplicate fact already exists",
+                confidence=computed_conf,
+                pii_matches=pii_matches,
+                masked_text=masked_text,
+            )
+
+        # Step 4: Conflict detection
+        if fact.entity_id:
+            conflicts = self.conflict_detector.find_conflicts(fact)
+            if conflicts:
+                # Check if we can auto-resolve
+                auto_resolved = self._try_auto_resolve(conflicts)
+                if not auto_resolved:
+                    fact.status = FactStatus.CONFLICTED
+                    return ValidationResult(
+                        action=Action.FLAG_CONFLICT,
+                        reason=f"Conflicts with {len(conflicts)} existing fact(s)",
+                        confidence=computed_conf,
+                        conflicts=conflicts,
+                        pii_matches=pii_matches,
+                        masked_text=masked_text,
+                    )
+
+        # Step 5: Accept
+        return ValidationResult(
+            action=Action.ACCEPT,
+            reason="Passed all quality checks",
+            confidence=computed_conf,
+            pii_matches=pii_matches,
+            masked_text=masked_text,
+        )
+
+    def _try_auto_resolve(self, conflicts: list[ConflictInfo]) -> bool:
+        """Attempt to auto-resolve conflicts if trust difference is large enough."""
+        all_resolved = True
+        for conflict in conflicts:
+            if conflict.suggested_resolution == "supersede":
+                # New fact has much higher trust — auto-supersede
+                continue
+            else:
+                all_resolved = False
+        return all_resolved