neural-memory 0.1.0__py3-none-any.whl

neural_memory/core/fiber.py

@@ -0,0 +1,236 @@
+"""Fiber data structures - memory clusters of related neurons."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+from uuid import uuid4
+
+
+@dataclass
+class Fiber:
+    """
+    A fiber represents a memory cluster - a subgraph of related neurons.
+
+    Fibers bundle together neurons and synapses that form a coherent
+    memory or concept. They act as retrieval units and can be
+    compressed into summaries over time.
+
+    Attributes:
+        id: Unique identifier
+        neuron_ids: Set of neuron IDs in this fiber
+        synapse_ids: Set of synapse IDs connecting neurons in this fiber
+        anchor_neuron_id: Primary entry point neuron for this fiber
+        time_start: Earliest timestamp in this memory
+        time_end: Latest timestamp in this memory
+        coherence: How tightly connected the neurons are (0.0 - 1.0)
+        salience: Importance/relevance score (0.0 - 1.0)
+        frequency: Number of times this fiber has been accessed
+        summary: Optional compressed text summary
+        tags: Optional tags for categorization
+        metadata: Additional fiber-specific data
+        created_at: When this fiber was created
+    """
+
+    id: str
+    neuron_ids: set[str]
+    synapse_ids: set[str]
+    anchor_neuron_id: str
+    time_start: datetime | None = None
+    time_end: datetime | None = None
+    coherence: float = 0.0
+    salience: float = 0.0
+    frequency: int = 0
+    summary: str | None = None
+    tags: set[str] = field(default_factory=set)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    created_at: datetime = field(default_factory=datetime.utcnow)
+
+    @classmethod
+    def create(
+        cls,
+        neuron_ids: set[str],
+        synapse_ids: set[str],
+        anchor_neuron_id: str,
+        time_start: datetime | None = None,
+        time_end: datetime | None = None,
+        summary: str | None = None,
+        tags: set[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        fiber_id: str | None = None,
+    ) -> Fiber:
+        """
+        Factory method to create a new Fiber.
+
+        Args:
+            neuron_ids: Set of neuron IDs
+            synapse_ids: Set of synapse IDs
+            anchor_neuron_id: Primary entry point
+            time_start: Optional start time
+            time_end: Optional end time
+            summary: Optional text summary
+            tags: Optional tags
+            metadata: Optional metadata
+            fiber_id: Optional explicit ID
+
+        Returns:
+            A new Fiber instance
+        """
+        if anchor_neuron_id not in neuron_ids:
+            raise ValueError(f"Anchor neuron {anchor_neuron_id} must be in neuron_ids")
+
+        return cls(
+            id=fiber_id or str(uuid4()),
+            neuron_ids=neuron_ids,
+            synapse_ids=synapse_ids,
+            anchor_neuron_id=anchor_neuron_id,
+            time_start=time_start,
+            time_end=time_end,
+            summary=summary,
+            tags=tags or set(),
+            metadata=metadata or {},
+            created_at=datetime.utcnow(),
+        )
+
+    def access(self) -> Fiber:
+        """
+        Create a new Fiber with incremented access frequency.
+
+        Returns:
+            New Fiber with frequency + 1
+        """
+        return Fiber(
+            id=self.id,
+            neuron_ids=self.neuron_ids,
+            synapse_ids=self.synapse_ids,
+            anchor_neuron_id=self.anchor_neuron_id,
+            time_start=self.time_start,
+            time_end=self.time_end,
+            coherence=self.coherence,
+            salience=self.salience,
+            frequency=self.frequency + 1,
+            summary=self.summary,
+            tags=self.tags,
+            metadata=self.metadata,
+            created_at=self.created_at,
+        )
+
+    def with_salience(self, salience: float) -> Fiber:
+        """
+        Create a new Fiber with updated salience.
+
+        Args:
+            salience: New salience value (clamped to 0.0-1.0)
+
+        Returns:
+            New Fiber with updated salience
+        """
+        return Fiber(
+            id=self.id,
+            neuron_ids=self.neuron_ids,
+            synapse_ids=self.synapse_ids,
+            anchor_neuron_id=self.anchor_neuron_id,
+            time_start=self.time_start,
+            time_end=self.time_end,
+            coherence=self.coherence,
+            salience=max(0.0, min(1.0, salience)),
+            frequency=self.frequency,
+            summary=self.summary,
+            tags=self.tags,
+            metadata=self.metadata,
+            created_at=self.created_at,
+        )
+
+    def with_summary(self, summary: str) -> Fiber:
+        """
+        Create a new Fiber with a summary.
+
+        Args:
+            summary: The summary text
+
+        Returns:
+            New Fiber with summary
+        """
+        return Fiber(
+            id=self.id,
+            neuron_ids=self.neuron_ids,
+            synapse_ids=self.synapse_ids,
+            anchor_neuron_id=self.anchor_neuron_id,
+            time_start=self.time_start,
+            time_end=self.time_end,
+            coherence=self.coherence,
+            salience=self.salience,
+            frequency=self.frequency,
+            summary=summary,
+            tags=self.tags,
+            metadata=self.metadata,
+            created_at=self.created_at,
+        )
+
+    def add_tags(self, *new_tags: str) -> Fiber:
+        """
+        Create a new Fiber with additional tags.
+
+        Args:
+            *new_tags: Tags to add
+
+        Returns:
+            New Fiber with merged tags
+        """
+        return Fiber(
+            id=self.id,
+            neuron_ids=self.neuron_ids,
+            synapse_ids=self.synapse_ids,
+            anchor_neuron_id=self.anchor_neuron_id,
+            time_start=self.time_start,
+            time_end=self.time_end,
+            coherence=self.coherence,
+            salience=self.salience,
+            frequency=self.frequency,
+            summary=self.summary,
+            tags=self.tags | set(new_tags),
+            metadata=self.metadata,
+            created_at=self.created_at,
+        )
+
+    @property
+    def neuron_count(self) -> int:
+        """Number of neurons in this fiber."""
+        return len(self.neuron_ids)
+
+    @property
+    def synapse_count(self) -> int:
+        """Number of synapses in this fiber."""
+        return len(self.synapse_ids)
+
+    @property
+    def time_span(self) -> float | None:
+        """
+        Duration of this memory in seconds.
+
+        Returns None if time bounds are not set.
+        """
+        if self.time_start and self.time_end:
+            return (self.time_end - self.time_start).total_seconds()
+        return None
+
+    def contains_neuron(self, neuron_id: str) -> bool:
+        """Check if this fiber contains a specific neuron."""
+        return neuron_id in self.neuron_ids
+
+    def overlaps_time(self, start: datetime, end: datetime) -> bool:
+        """
+        Check if this fiber's time range overlaps with given range.
+
+        Args:
+            start: Query start time
+            end: Query end time
+
+        Returns:
+            True if there is any overlap
+        """
+        if self.time_start is None or self.time_end is None:
+            return False
+
+        return self.time_start <= end and self.time_end >= start

neural_memory/core/memory_types.py

@@ -0,0 +1,331 @@
+"""Memory types and classification for Neural Memory.
+
+Integrates MemoCore concepts: typed memories with priority, expiry, and provenance.
+This enables smarter query routing and memory lifecycle management.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from enum import IntEnum, StrEnum
+from typing import Any
+
+
+class MemoryType(StrEnum):
+    """Types of memories based on their nature and purpose."""
+
+    # Core types from MemoCore
+    FACT = "fact"  # Objective information: "Python 3.11 was released in Oct 2022"
+    DECISION = "decision"  # Choices made: "We decided to use PostgreSQL"
+    PREFERENCE = "preference"  # User preferences: "I prefer tabs over spaces"
+    TODO = "todo"  # Action items: "Need to refactor auth module"
+    INSIGHT = "insight"  # Learned patterns: "This codebase uses dependency injection"
+    CONTEXT = "context"  # Situational info: "Working on project X for client Y"
+    INSTRUCTION = "instruction"  # User guidelines: "Always use type hints"
+
+    # Additional useful types
+    ERROR = "error"  # Error patterns: "This API returns 429 on rate limit"
+    WORKFLOW = "workflow"  # Process patterns: "Deploy flow: test -> stage -> prod"
+    REFERENCE = "reference"  # External refs: "Docs at https://..."
+
+
+class Priority(IntEnum):
+    """Memory priority levels (0-10 scale)."""
+
+    LOWEST = 0
+    LOW = 2
+    NORMAL = 5
+    HIGH = 7
+    CRITICAL = 10
+
+    @classmethod
+    def from_int(cls, value: int) -> Priority:
+        """Convert integer to nearest Priority level."""
+        if value <= 1:
+            return cls.LOWEST
+        elif value <= 3:
+            return cls.LOW
+        elif value <= 6:
+            return cls.NORMAL
+        elif value <= 8:
+            return cls.HIGH
+        else:
+            return cls.CRITICAL
+
+
+class Confidence(StrEnum):
+    """Confidence level in the memory's accuracy."""
+
+    VERIFIED = "verified"  # Confirmed by user or external source
+    HIGH = "high"  # Very likely accurate
+    MEDIUM = "medium"  # Probably accurate
+    LOW = "low"  # Uncertain, needs verification
+    INFERRED = "inferred"  # AI-inferred, may be wrong
+
+
+@dataclass(frozen=True)
+class Provenance:
+    """Tracks the origin and reliability of a memory.
+
+    Attributes:
+        source: Where this memory came from
+        confidence: How reliable this memory is
+        verified: Whether explicitly verified by user
+        verified_at: When verification happened
+        created_by: Who/what created this memory
+        last_confirmed: When last confirmed as still valid
+    """
+
+    source: str  # "user_input", "ai_inference", "import", "observation"
+    confidence: Confidence = Confidence.MEDIUM
+    verified: bool = False
+    verified_at: datetime | None = None
+    created_by: str = "user"
+    last_confirmed: datetime | None = None
+
+    def verify(self) -> Provenance:
+        """Create a new Provenance marked as verified."""
+        return Provenance(
+            source=self.source,
+            confidence=Confidence.VERIFIED,
+            verified=True,
+            verified_at=datetime.utcnow(),
+            created_by=self.created_by,
+            last_confirmed=datetime.utcnow(),
+        )
+
+    def confirm(self) -> Provenance:
+        """Create a new Provenance with updated confirmation time."""
+        return Provenance(
+            source=self.source,
+            confidence=self.confidence,
+            verified=self.verified,
+            verified_at=self.verified_at,
+            created_by=self.created_by,
+            last_confirmed=datetime.utcnow(),
+        )
+
+
+@dataclass(frozen=True)
+class TypedMemory:
+    """A memory with type classification, priority, and lifecycle metadata.
+
+    This wraps around fibers to add MemoCore-style memory management.
+
+    Attributes:
+        fiber_id: Reference to the underlying Fiber
+        memory_type: Classification of this memory
+        priority: Importance level (0-10)
+        provenance: Origin and reliability info
+        expires_at: Optional expiration timestamp
+        project_id: Optional project scope
+        tags: Additional categorization tags
+        metadata: Extra type-specific data
+        created_at: Creation timestamp
+    """
+
+    fiber_id: str
+    memory_type: MemoryType
+    priority: Priority = Priority.NORMAL
+    provenance: Provenance = field(default_factory=lambda: Provenance(source="user_input"))
+    expires_at: datetime | None = None
+    project_id: str | None = None
+    tags: frozenset[str] = field(default_factory=frozenset)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    created_at: datetime = field(default_factory=datetime.utcnow)
+
+    @classmethod
+    def create(
+        cls,
+        fiber_id: str,
+        memory_type: MemoryType,
+        priority: Priority | int = Priority.NORMAL,
+        source: str = "user_input",
+        confidence: Confidence = Confidence.MEDIUM,
+        expires_in_days: int | None = None,
+        project_id: str | None = None,
+        tags: set[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> TypedMemory:
+        """Factory method to create a TypedMemory.
+
+        Args:
+            fiber_id: The underlying fiber ID
+            memory_type: Type of memory
+            priority: Priority level (int or Priority enum)
+            source: Source of this memory
+            confidence: Confidence level
+            expires_in_days: Optional days until expiry
+            project_id: Optional project scope
+            tags: Optional tags
+            metadata: Optional metadata
+
+        Returns:
+            A new TypedMemory instance
+        """
+        if isinstance(priority, int):
+            priority = Priority.from_int(priority)
+
+        expires_at = None
+        if expires_in_days is not None:
+            expires_at = datetime.utcnow() + timedelta(days=expires_in_days)
+
+        return cls(
+            fiber_id=fiber_id,
+            memory_type=memory_type,
+            priority=priority,
+            provenance=Provenance(source=source, confidence=confidence),
+            expires_at=expires_at,
+            project_id=project_id,
+            tags=frozenset(tags) if tags else frozenset(),
+            metadata=metadata or {},
+            created_at=datetime.utcnow(),
+        )
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if this memory has expired."""
+        if self.expires_at is None:
+            return False
+        return datetime.utcnow() > self.expires_at
+
+    @property
+    def days_until_expiry(self) -> int | None:
+        """Days until this memory expires, or None if no expiry."""
+        if self.expires_at is None:
+            return None
+        delta = self.expires_at - datetime.utcnow()
+        return max(0, delta.days)
+
+    def with_priority(self, priority: Priority | int) -> TypedMemory:
+        """Create a new TypedMemory with updated priority."""
+        if isinstance(priority, int):
+            priority = Priority.from_int(priority)
+        return TypedMemory(
+            fiber_id=self.fiber_id,
+            memory_type=self.memory_type,
+            priority=priority,
+            provenance=self.provenance,
+            expires_at=self.expires_at,
+            project_id=self.project_id,
+            tags=self.tags,
+            metadata=self.metadata,
+            created_at=self.created_at,
+        )
+
+    def verify(self) -> TypedMemory:
+        """Create a new TypedMemory marked as verified."""
+        return TypedMemory(
+            fiber_id=self.fiber_id,
+            memory_type=self.memory_type,
+            priority=self.priority,
+            provenance=self.provenance.verify(),
+            expires_at=self.expires_at,
+            project_id=self.project_id,
+            tags=self.tags,
+            metadata=self.metadata,
+            created_at=self.created_at,
+        )
+
+    def extend_expiry(self, days: int) -> TypedMemory:
+        """Create a new TypedMemory with extended expiry."""
+        new_expiry = datetime.utcnow() + timedelta(days=days)
+        return TypedMemory(
+            fiber_id=self.fiber_id,
+            memory_type=self.memory_type,
+            priority=self.priority,
+            provenance=self.provenance,
+            expires_at=new_expiry,
+            project_id=self.project_id,
+            tags=self.tags,
+            metadata=self.metadata,
+            created_at=self.created_at,
+        )
+
+
+# Default expiry settings per memory type
+DEFAULT_EXPIRY_DAYS: dict[MemoryType, int | None] = {
+    MemoryType.FACT: None,  # Facts don't expire by default
+    MemoryType.DECISION: 90,  # Decisions may become stale
+    MemoryType.PREFERENCE: None,  # Preferences persist
+    MemoryType.TODO: 30,  # TODOs should be acted on
+    MemoryType.INSIGHT: 180,  # Insights may become outdated
+    MemoryType.CONTEXT: 7,  # Context is usually short-term
+    MemoryType.INSTRUCTION: None,  # Instructions persist
+    MemoryType.ERROR: 30,  # Error patterns may get fixed
+    MemoryType.WORKFLOW: 365,  # Workflows change slowly
+    MemoryType.REFERENCE: None,  # References persist
+}
+
+
+def suggest_memory_type(content: str) -> MemoryType:
+    """Suggest a memory type based on content analysis.
+
+    This is a simple heuristic. For production, use NLP.
+
+    Args:
+        content: The memory content to analyze
+
+    Returns:
+        Suggested MemoryType
+    """
+    content_lower = content.lower()
+
+    # TODO patterns (highest priority - actionable)
+    if any(
+        kw in content_lower
+        for kw in ["todo", "need to", "should", "must", "fix", "implement", "add"]
+    ):
+        return MemoryType.TODO
+
+    # Decision patterns
+    if any(
+        kw in content_lower
+        for kw in ["decided", "chose", "will use", "going with", "picked", "selected"]
+    ):
+        return MemoryType.DECISION
+
+    # Instruction patterns (check BEFORE preference - "always use" vs "always")
+    if any(
+        kw in content_lower
+        for kw in [
+            "always use",
+            "never use",
+            "make sure",
+            "remember to",
+            "don't forget",
+        ]
+    ):
+        return MemoryType.INSTRUCTION
+
+    # Preference patterns
+    if any(kw in content_lower for kw in ["prefer", "like", "favorite", "hate"]):
+        return MemoryType.PREFERENCE
+
+    # Insight patterns (check BEFORE error - "discovered" vs "issue")
+    if any(
+        kw in content_lower
+        for kw in ["learned", "realized", "discovered", "found that", "turns out"]
+    ):
+        return MemoryType.INSIGHT
+
+    # Error patterns
+    if any(
+        kw in content_lower
+        for kw in ["error", "bug", "issue", "problem", "fail", "crash", "exception"]
+    ):
+        return MemoryType.ERROR
+
+    # Workflow patterns
+    if any(
+        kw in content_lower for kw in ["workflow", "process", "step", "flow", "pipeline", "deploy"]
+    ):
+        return MemoryType.WORKFLOW
+
+    # Reference patterns
+    if any(kw in content_lower for kw in ["http", "https", "docs", "documentation"]):
+        return MemoryType.REFERENCE
+
+    # Default to fact
+    return MemoryType.FACT