cortext-memory 0.1.0__py3-none-any.whl

cortext/__init__.py

@@ -0,0 +1,72 @@
+"""Cortext — Memory system for AI agents.
+
+5-element detector compliant, internationalized, efficient.
+"""
+
+from cortext.cortex import CortexV5
+from cortext.core.memory import Memory
+from cortext.core.entity import Entity
+from cortext.core.relation import Relation, RelationType
+from cortext.core.graph import MemoryGraph, RecallResult
+from cortext.core.validation import (
+    CanonicalValidator,
+    ValidationResult,
+    ValidationStatus,
+    ValidationPolicy,
+    create_default_validator,
+    create_strict_validator,
+)
+from cortext.core.recall import (
+    StructuralQueryParser,
+    QueryIntent,
+    pack_for_context,
+    RegexExtractor,
+    LLMExtractor,
+    HybridExtractor,
+)
+from cortext.core.decay import (
+    DecayConfig,
+    retrievability,
+    effective_stability,
+    decay_status,
+    ForgetGate,
+    ForgetGateConfig,
+)
+from cortext.workers import DreamAgent
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main entry point
+    "CortexV5",
+    # Core data structures
+    "Memory",
+    "Entity",
+    "Relation",
+    "RelationType",
+    "MemoryGraph",
+    "RecallResult",
+    # Validation
+    "CanonicalValidator",
+    "ValidationResult",
+    "ValidationStatus",
+    "ValidationPolicy",
+    "create_default_validator",
+    "create_strict_validator",
+    # Recall
+    "StructuralQueryParser",
+    "QueryIntent",
+    "pack_for_context",
+    "RegexExtractor",
+    "LLMExtractor",
+    "HybridExtractor",
+    # Decay
+    "DecayConfig",
+    "retrievability",
+    "effective_stability",
+    "decay_status",
+    "ForgetGate",
+    "ForgetGateConfig",
+    # Workers
+    "DreamAgent",
+]

cortext/core/__init__.py

@@ -0,0 +1 @@
+"""Core data structures: Memory, Entity, Relation, MemoryGraph."""

cortext/core/decay/__init__.py

@@ -0,0 +1,23 @@
+"""
+Decay subsystem: Ebbinghaus R = e^(-t/S) + Forget Gate.
+"""
+
+from cortext.core.decay.ebbinghaus import (
+    DecayConfig,
+    retrievability,
+    effective_stability,
+    decay_status,
+)
+from cortext.core.decay.forget_gate import (
+    ForgetGate,
+    ForgetGateConfig,
+)
+
+__all__ = [
+    "DecayConfig",
+    "retrievability",
+    "effective_stability",
+    "decay_status",
+    "ForgetGate",
+    "ForgetGateConfig",
+]

cortext/core/decay/ebbinghaus.py

@@ -0,0 +1,126 @@
+"""
+Ebbinghaus decay — R = e^(-t/S).
+
+The classic forgetting curve, applied to memory retrieval. Simple,
+universal, and validated empirically (Ebbinghaus, 1885).
+
+Formula: R = e^(-t/S)
+  - R: retrievability (0.0-1.0)
+  - t: time since last access (days)
+  - S: stability (days) — base × modifiers
+
+Stability modifiers (extensible):
+  - access_count: more accesses = more stable (log scale)
+  - importance: high importance = more stable
+  - consolidation: consolidated memories = more stable
+  - (custom) user-defined via metadata
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cortext.core.memory import Memory
+
+
+@dataclass
+class DecayConfig:
+    """Tunables for the decay function."""
+
+    # Base stability (days for 63% decay without reinforcement)
+    base_stability_days: float = 7.0
+
+    # Stability modifiers
+    access_log_multiplier: float = 1.0      # log(access_count + 1) factor
+    importance_bonus: float = 1.3            # bonus for high importance (>0.7)
+    consolidation_bonus: float = 2.0        # bonus for consolidated memories
+
+    # Min/max stability (prevent degenerate values)
+    min_stability: float = 0.1
+    max_stability: float = 365.0
+
+    # Thresholds for status
+    active_threshold: float = 0.7
+    fading_threshold: float = 0.3
+    forgotten_threshold: float = 0.1
+
+
+def retrievability(
+    memory: "Memory",
+    now: datetime | None = None,
+    config: DecayConfig | None = None,
+) -> float:
+    """
+    Compute retrievability of a memory using the Ebbinghaus curve.
+
+    R = e^(-t/S), where S = base_stability × modifiers.
+
+    Returns:
+        float between 0.0 (forgotten) and 1.0 (fresh)
+    """
+    if config is None:
+        config = DecayConfig()
+    now = now or datetime.now()
+
+    # Reference time = last access, fallback to creation
+    reference_time = memory.last_accessed or memory.when
+    days_since = max(0.0, (now - reference_time).total_seconds() / 86400)
+
+    # Compute effective stability
+    s = effective_stability(memory, config)
+
+    # Ebbinghaus formula
+    return math.exp(-days_since / s)
+
+
+def effective_stability(
+    memory: "Memory",
+    config: DecayConfig | None = None,
+) -> float:
+    """
+    Compute the effective stability S for a memory.
+
+    S = base × access_modifier × importance_modifier × consolidation_modifier
+    """
+    if config is None:
+        config = DecayConfig()
+
+    s = config.base_stability_days
+
+    # Access count modifier (logarithmic)
+    access_factor = 1.0 + config.access_log_multiplier * math.log(memory.access_count + 1)
+    s *= access_factor
+
+    # Importance bonus
+    if memory.importance > 0.7:
+        s *= config.importance_bonus
+
+    # Consolidation bonus
+    if memory.is_consolidated:
+        s *= config.consolidation_bonus
+
+    return max(config.min_stability, min(config.max_stability, s))
+
+
+def decay_status(
+    memory: "Memory",
+    now: datetime | None = None,
+    config: DecayConfig | None = None,
+) -> str:
+    """
+    Get a categorical status: "active" | "fading" | "weak" | "forgotten".
+    """
+    if config is None:
+        config = DecayConfig()
+    r = retrievability(memory, now, config)
+    if r >= config.active_threshold:
+        return "active"
+    elif r >= config.fading_threshold:
+        return "fading"
+    elif r >= config.forgotten_threshold:
+        return "weak"
+    return "forgotten"

cortext/core/decay/forget_gate.py

@@ -0,0 +1,169 @@
+"""
+Forget Gate — active forgetting based on 3 signals.
+
+Inspired by LSTM forget gates and active forgetting in human cognition.
+3 signals combine into a forget score (0-1, higher = more forgettable):
+
+  1. Noise (0.4 weight): how likely the memory is noise vs signal
+     - Low importance, no participants, empty/short content
+  2. Redundancy (0.35): is this memory redundant with others?
+  3. Obsolescence (0.25): is this memory outdated?
+
+Usage: gate = ForgetGate()
+       score = gate.compute_forget_signal(memory, graph)
+       if score >= threshold: accelerate_decay(memory)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cortext.core.memory import Memory
+    from cortext.core.graph import MemoryGraph
+
+
+@dataclass
+class ForgetGateConfig:
+    noise_weight: float = 0.4
+    redundancy_weight: float = 0.35
+    obsolescence_weight: float = 0.25
+    forget_threshold: float = 0.3  # lowered from 0.6 — typical "noisy" memories cross this
+
+
+class ForgetGate:
+    """
+    Active forgetting: score memories for deletion.
+
+    Combines 3 signals into a single forget score.
+    """
+
+    def __init__(self, config: ForgetGateConfig | None = None) -> None:
+        self.config = config or ForgetGateConfig()
+
+    def compute_forget_signal(
+        self, memory: "Memory", graph: "MemoryGraph"
+    ) -> float:
+        """Compute forget signal (0-1, higher = more forgettable)."""
+        noise = self._noise_score(memory)
+        redundancy = self._redundancy_score(memory, graph)
+        obsolescence = self._obsolescence_score(memory)
+
+        return min(1.0, max(0.0, (
+            self.config.noise_weight * noise +
+            self.config.redundancy_weight * redundancy +
+            self.config.obsolescence_weight * obsolescence
+        )))
+
+    def filter_forgettable(
+        self, memories: list["Memory"], graph: "MemoryGraph"
+    ) -> tuple[list["Memory"], list["Memory"]]:
+        """
+        Split memories into (keep, forget) based on forget signal.
+
+        Returns:
+            (memories_to_keep, memories_to_forget)
+        """
+        keep: list["Memory"] = []
+        forget: list["Memory"] = []
+        for mem in memories:
+            signal = self.compute_forget_signal(mem, graph)
+            if signal >= self.config.forget_threshold:
+                forget.append(mem)
+            else:
+                keep.append(mem)
+        return keep, forget
+
+    def accelerate_decay(
+        self, memory: "Memory", multiplier: float = 0.5
+    ) -> float:
+        """Reduce importance to accelerate decay. Returns new importance."""
+        memory.importance = max(0.0, memory.importance * multiplier)
+        return memory.importance
+
+    def _noise_score(self, memory: "Memory") -> float:
+        """Estimate if memory is noise vs signal."""
+        score = 0.0
+
+        # Low importance
+        if memory.importance < 0.3:
+            score += 0.3
+        elif memory.importance < 0.5:
+            score += 0.1
+
+        # No participants
+        if not memory.who:
+            score += 0.2
+
+        # Empty/short content
+        content_len = len(memory.what or "")
+        if content_len < 10:
+            score += 0.2
+        elif content_len < 30:
+            score += 0.1
+
+        # Generic values
+        generic_terms = {"undefined", "none", "null", "unknown", "n/a", ""}
+        if (memory.what or "").lower().strip() in generic_terms:
+            score += 0.2
+
+        # Not consolidated
+        if not memory.is_consolidated:
+            score += 0.1
+
+        return min(1.0, score)
+
+    def _redundancy_score(
+        self, memory: "Memory", graph: "MemoryGraph"
+    ) -> float:
+        """Estimate redundancy with other memories."""
+        score = 0.0
+        similar_count = 0
+        if hasattr(graph, "iter_memories"):
+            for other in graph.iter_memories():
+                if other.id == memory.id:
+                    continue
+                # Simple overlap check on what-field
+                a = set((memory.what or "").lower().split())
+                b = set((other.what or "").lower().split())
+                if a and b:
+                    overlap = len(a & b) / len(a | b)
+                    if overlap > 0.7:
+                        similar_count += 1
+
+        if similar_count >= 3:
+            score += 0.5
+        elif similar_count >= 1:
+            score += 0.2
+
+        return min(1.0, score)
+
+    def _obsolescence_score(self, memory: "Memory") -> float:
+        """Estimate if memory is obsolete."""
+        score = 0.0
+        now = datetime.now()
+
+        # Old with no recent access
+        if memory.when:
+            days_old = (now - memory.when).days
+            last_access = memory.last_accessed or memory.when
+            days_since_access = (now - last_access).days
+            if days_old > 90 and days_since_access > 60:
+                score += 0.4
+            elif days_old > 30 and days_since_access > 30:
+                score += 0.2
+
+        # Low retrievability (uses ebbinghaus)
+        try:
+            from cortext.core.decay.ebbinghaus import retrievability
+            r = retrievability(memory)
+            if r < 0.2:
+                score += 0.4
+            elif r < 0.4:
+                score += 0.2
+        except Exception:
+            pass
+
+        return min(1.0, score)

cortext/core/entity.py

@@ -0,0 +1,85 @@
+"""
+Entity — represents a "thing" that can be referenced in memories.
+
+Entities are language-agnostic. A person named "Maria" in PT and
+"Maria" in EN is the same entity. The name is just a string.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass
+class Entity:
+    """
+    A referenceable thing in the memory system.
+
+    Attributes:
+        type: type tag (e.g., "person", "place", "concept", "file")
+        name: display name (in any language)
+        identifiers: list of ways to identify this entity (emails, IDs, paths)
+        attributes: free-form metadata
+    """
+
+    type: str
+    name: str
+    identifiers: list[str] = field(default_factory=list)
+    attributes: dict[str, Any] = field(default_factory=dict)
+    id: str = field(default_factory=lambda: str(uuid4()))
+    created_at: datetime = field(default_factory=datetime.now)
+    updated_at: datetime = field(default_factory=datetime.now)
+
+    def __post_init__(self) -> None:
+        if not self.type or not self.type.strip():
+            raise ValueError("Entity 'type' is required")
+        if not self.name or not self.name.strip():
+            raise ValueError("Entity 'name' is required")
+        self.type = self.type.strip()
+        self.name = self.name.strip()
+
+    def matches(self, query: str) -> bool:
+        """Check if this entity matches a query (name, ID, or identifier)."""
+        if not query:
+            return False
+        q = query.lower()
+        if q == self.id or q == self.name.lower():
+            return True
+        if any(q in ident.lower() for ident in self.identifiers):
+            return True
+        return False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "type": self.type,
+            "name": self.name,
+            "identifiers": list(self.identifiers),
+            "attributes": dict(self.attributes),
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Entity":
+        return cls(
+            id=data.get("id", str(uuid4())),
+            type=data.get("type", ""),
+            name=data.get("name", ""),
+            identifiers=data.get("identifiers", []),
+            attributes=data.get("attributes", {}),
+        )
+
+    def __repr__(self) -> str:
+        return f"Entity(type={self.type!r}, name={self.name!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Entity):
+            return False
+        return self.id == other.id
+
+    def __hash__(self) -> int:
+        return hash(self.id)

cortext/core/graph.py

@@ -0,0 +1,226 @@
+"""
+MemoryGraph — collection of memories, entities, and relations.
+
+Enxuto, sem feature flags, sem BFS/Louvain/PageRank. Operations are
+O(1) for direct lookup, O(n) for scans. The Dream Agent (background
+worker) handles consolidation separately.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Iterator, Optional
+
+from cortext.core.memory import Memory
+from cortext.core.entity import Entity
+from cortext.core.relation import Relation
+
+
+@dataclass
+class RecallResult:
+    """Result of a memory recall operation."""
+
+    memories: list[Memory] = field(default_factory=list)
+    entities: list[Entity] = field(default_factory=list)
+    relations: list[Relation] = field(default_factory=list)
+    metrics: dict[str, Any] = field(default_factory=dict)
+
+    def __len__(self) -> int:
+        return len(self.memories)
+
+    def is_empty(self) -> bool:
+        return len(self.memories) == 0 and len(self.entities) == 0 and len(self.relations) == 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "memories": [m.to_dict() for m in self.memories],
+            "entities": [e.to_dict() for e in self.entities],
+            "relations": [r.to_dict() for r in self.relations],
+            "metrics": self.metrics,
+        }
+
+
+class MemoryGraph:
+    """
+    In-memory graph of memories, entities, and relations.
+
+    API enxuto: 5 métodos públicos (add_memory, add_entity, add_relation,
+    get_*, iter_*) + 1 busca livre (find). Sem indexação sofisticada
+    (sem inverted index, sem BFS expansion). Dream Agent pode adicionar
+    indexação opcional se necessário.
+    """
+
+    def __init__(self, namespace: str = "default") -> None:
+        """Initialize an in-memory graph (no persistence in core)."""
+        self.namespace = namespace
+        self._memories: dict[str, Memory] = {}
+        self._entities: dict[str, Entity] = {}
+        self._relations: dict[str, Relation] = {}
+
+    # === Add operations ===
+
+    def add_memory(self, memory: Memory) -> Memory:
+        """Add a memory. Returns the memory (with id)."""
+        if not isinstance(memory, Memory):
+            raise TypeError(f"expected Memory, got {type(memory).__name__}")
+        self._memories[memory.id] = memory
+        return memory
+
+    def add_entity(self, entity: Entity) -> Entity:
+        """Add an entity. Returns the entity (with id)."""
+        if not isinstance(entity, Entity):
+            raise TypeError(f"expected Entity, got {type(entity).__name__}")
+        self._entities[entity.id] = entity
+        return entity
+
+    def add_relation(self, relation: Relation) -> Relation:
+        """Add a relation. Returns the relation (with id)."""
+        if not isinstance(relation, Relation):
+            raise TypeError(f"expected Relation, got {type(relation).__name__}")
+        self._relations[relation.id] = relation
+        return relation
+
+    # === Get operations ===
+
+    def get_memory(self, memory_id: str) -> Optional[Memory]:
+        return self._memories.get(memory_id)
+
+    def get_entity(self, entity_id: str) -> Optional[Entity]:
+        return self._entities.get(entity_id)
+
+    def get_relation(self, relation_id: str) -> Optional[Relation]:
+        return self._relations.get(relation_id)
+
+    # === Iteration ===
+
+    def iter_memories(self) -> Iterator[Memory]:
+        return iter(self._memories.values())
+
+    def iter_entities(self) -> Iterator[Entity]:
+        return iter(self._entities.values())
+
+    def iter_relations(self) -> Iterator[Relation]:
+        return iter(self._relations.values())
+
+    def all_memories(self) -> list[Memory]:
+        return list(self._memories.values())
+
+    def all_entities(self) -> list[Entity]:
+        return list(self._entities.values())
+
+    def all_relations(self) -> list[Relation]:
+        return list(self._relations.values())
+
+    # === Find operations ===
+
+    def find_memories(
+        self,
+        who: Optional[str] = None,
+        where: Optional[str] = None,
+        what_contains: Optional[str] = None,
+    ) -> list[Memory]:
+        """
+        Find memories matching filters. O(n) scan.
+
+        Args:
+            who: filter by participant (case-insensitive substring)
+            where: filter by namespace/exact match
+            what_contains: filter by substring in 'what' field
+        """
+        results: list[Memory] = []
+        for mem in self._memories.values():
+            if who is not None and not mem.is_about(who):
+                continue
+            if where is not None and mem.where != where:
+                continue
+            if what_contains is not None and what_contains.lower() not in mem.what.lower():
+                continue
+            results.append(mem)
+        return results
+
+    def find_entities_by_name(self, name: str) -> list[Entity]:
+        """Find entities by name (case-insensitive exact match)."""
+        name_lower = name.lower()
+        return [e for e in self._entities.values() if e.name.lower() == name_lower]
+
+    def find_relations(
+        self,
+        from_id: Optional[str] = None,
+        to_id: Optional[str] = None,
+        relation_type: Optional[str] = None,
+    ) -> list[Relation]:
+        """Find relations matching filters. O(n) scan."""
+        results: list[Relation] = []
+        for rel in self._relations.values():
+            if from_id is not None and rel.from_id != from_id:
+                continue
+            if to_id is not None and rel.to_id != to_id:
+                continue
+            if relation_type is not None and rel.relation_type != relation_type.lower():
+                continue
+            results.append(rel)
+        return results
+
+    # === Persistence ===
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the whole graph to a plain dict (JSON-ready)."""
+        return {
+            "namespace": self.namespace,
+            "memories": [m.to_dict() for m in self._memories.values()],
+            "entities": [e.to_dict() for e in self._entities.values()],
+            "relations": [r.to_dict() for r in self._relations.values()],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "MemoryGraph":
+        """Reconstruct a graph from a dict produced by ``to_dict``."""
+        graph = cls(namespace=data.get("namespace", "default"))
+        for m in data.get("memories", []):
+            graph.add_memory(Memory.from_dict(m))
+        for e in data.get("entities", []):
+            graph.add_entity(Entity.from_dict(e))
+        for r in data.get("relations", []):
+            graph.add_relation(Relation.from_dict(r))
+        return graph
+
+    def save(self, path: Any) -> None:
+        """Persist the graph to a JSON file at ``path`` (atomic write)."""
+        import json
+        import os
+        from pathlib import Path
+
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(path.suffix + ".tmp")
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(self.to_dict(), f, ensure_ascii=False, default=str)
+        os.replace(tmp, path)
+
+    @classmethod
+    def load(cls, path: Any, namespace: str = "default") -> "MemoryGraph":
+        """Load a graph from a JSON file. Returns an empty graph if missing."""
+        import json
+        from pathlib import Path
+
+        path = Path(path)
+        if not path.exists():
+            return cls(namespace=namespace)
+        with open(path, encoding="utf-8") as f:
+            return cls.from_dict(json.load(f))
+
+    # === Stats ===
+
+    def stats(self) -> dict[str, Any]:
+        return {
+            "namespace": self.namespace,
+            "total_memories": len(self._memories),
+            "total_entities": len(self._entities),
+            "total_relations": len(self._relations),
+        }
+
+    def __len__(self) -> int:
+        return len(self._memories)
+
+    def __repr__(self) -> str:
+        return f"MemoryGraph(ns={self.namespace!r}, M={len(self._memories)}, E={len(self._entities)}, R={len(self._relations)})"