neural-memory 0.1.0__py3-none-any.whl

neural_memory/core/neuron.py

@@ -0,0 +1,168 @@
+"""Neuron data structures - the basic units of memory."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+from uuid import uuid4
+
+
+class NeuronType(StrEnum):
+    """Types of neurons in the memory system."""
+
+    TIME = "time"  # Temporal markers: "3pm", "yesterday"
+    SPATIAL = "spatial"  # Locations: "coffee shop", "office"
+    ENTITY = "entity"  # Named entities: "Alice", "FastAPI"
+    ACTION = "action"  # Verbs/actions: "discussed", "completed"
+    STATE = "state"  # Emotional/mental states: "happy", "frustrated"
+    CONCEPT = "concept"  # Abstract ideas: "API design", "authentication"
+    SENSORY = "sensory"  # Sensory experiences: "loud", "bright"
+    INTENT = "intent"  # Goals/intentions: "learn", "build"
+
+
+@dataclass(frozen=True)
+class Neuron:
+    """
+    A neuron represents a single unit of memory.
+
+    Neurons are immutable - they represent facts that don't change.
+    The activation state is stored separately in NeuronState.
+
+    Attributes:
+        id: Unique identifier (UUID or content-hash)
+        type: Category of information this neuron represents
+        content: The raw value/text of this memory unit
+        metadata: Type-specific additional information
+        created_at: When this neuron was created
+    """
+
+    id: str
+    type: NeuronType
+    content: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+    created_at: datetime = field(default_factory=datetime.utcnow)
+
+    @classmethod
+    def create(
+        cls,
+        type: NeuronType,
+        content: str,
+        metadata: dict[str, Any] | None = None,
+        neuron_id: str | None = None,
+    ) -> Neuron:
+        """
+        Factory method to create a new Neuron.
+
+        Args:
+            type: The type of neuron
+            content: The content/value
+            metadata: Optional metadata dict
+            neuron_id: Optional explicit ID (generates UUID if not provided)
+
+        Returns:
+            A new Neuron instance
+        """
+        return cls(
+            id=neuron_id or str(uuid4()),
+            type=type,
+            content=content,
+            metadata=metadata or {},
+            created_at=datetime.utcnow(),
+        )
+
+    def with_metadata(self, **kwargs: Any) -> Neuron:
+        """
+        Create a new Neuron with updated metadata.
+
+        Args:
+            **kwargs: Metadata key-value pairs to add/update
+
+        Returns:
+            New Neuron with merged metadata
+        """
+        return Neuron(
+            id=self.id,
+            type=self.type,
+            content=self.content,
+            metadata={**self.metadata, **kwargs},
+            created_at=self.created_at,
+        )
+
+
+@dataclass
+class NeuronState:
+    """
+    Mutable activation state for a neuron.
+
+    Separated from Neuron to allow state changes without
+    modifying the immutable neuron data.
+
+    Attributes:
+        neuron_id: Reference to the associated Neuron
+        activation_level: Current activation (0.0 - 1.0)
+        access_frequency: How many times this neuron has been activated
+        last_activated: When this neuron was last activated
+        decay_rate: How fast activation decays over time
+        created_at: When this state was created
+    """
+
+    neuron_id: str
+    activation_level: float = 0.0
+    access_frequency: int = 0
+    last_activated: datetime | None = None
+    decay_rate: float = 0.1
+    created_at: datetime = field(default_factory=datetime.utcnow)
+
+    def activate(self, level: float = 1.0) -> NeuronState:
+        """
+        Create a new state with updated activation.
+
+        Args:
+            level: Activation level to set (clamped to 0.0-1.0)
+
+        Returns:
+            New NeuronState with updated activation
+        """
+        clamped_level = max(0.0, min(1.0, level))
+        return NeuronState(
+            neuron_id=self.neuron_id,
+            activation_level=clamped_level,
+            access_frequency=self.access_frequency + 1,
+            last_activated=datetime.utcnow(),
+            decay_rate=self.decay_rate,
+            created_at=self.created_at,
+        )
+
+    def decay(self, time_delta_seconds: float) -> NeuronState:
+        """
+        Apply decay to activation based on time elapsed.
+
+        Uses exponential decay: new_level = old_level * e^(-decay_rate * time)
+
+        Args:
+            time_delta_seconds: Time elapsed since last update
+
+        Returns:
+            New NeuronState with decayed activation
+        """
+        import math
+
+        days_elapsed = time_delta_seconds / 86400  # Convert to days
+        decay_factor = math.exp(-self.decay_rate * days_elapsed)
+        new_level = self.activation_level * decay_factor
+
+        return NeuronState(
+            neuron_id=self.neuron_id,
+            activation_level=new_level,
+            access_frequency=self.access_frequency,
+            last_activated=self.last_activated,
+            decay_rate=self.decay_rate,
+            created_at=self.created_at,
+        )
+
+    @property
+    def is_active(self) -> bool:
+        """Check if neuron is currently active (above threshold)."""
+        return self.activation_level > 0.1

neural_memory/core/project.py

@@ -0,0 +1,257 @@
+"""Project scoping for memory organization.
+
+Projects allow grouping memories by context (sprint, feature, research topic)
+with automatic time-based prioritization.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Project:
+    """A project scope for organizing memories.
+
+    Projects define a context boundary for memories, typically representing
+    a sprint, feature, research topic, or any focused work period.
+    """
+
+    id: str
+    name: str
+    description: str = ""
+    start_date: datetime = field(default_factory=datetime.utcnow)
+    end_date: datetime | None = None  # None = ongoing
+    tags: frozenset[str] = field(default_factory=frozenset)
+    priority: float = 1.0  # Higher = more important
+    metadata: dict[str, Any] = field(default_factory=dict)
+    created_at: datetime = field(default_factory=datetime.utcnow)
+
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        description: str = "",
+        start_date: datetime | None = None,
+        end_date: datetime | None = None,
+        duration_days: int | None = None,
+        tags: set[str] | None = None,
+        priority: float = 1.0,
+        metadata: dict[str, Any] | None = None,
+    ) -> Project:
+        """Create a new project.
+
+        Args:
+            name: Project name
+            description: Optional description
+            start_date: When project starts (default: now)
+            end_date: When project ends (optional)
+            duration_days: Alternative to end_date - set duration from start
+            tags: Optional tags for categorization
+            priority: Project priority (default: 1.0)
+            metadata: Optional metadata
+
+        Returns:
+            New Project instance
+        """
+        now = datetime.utcnow()
+        start = start_date or now
+
+        # Calculate end_date from duration if provided
+        end = end_date
+        if end is None and duration_days is not None:
+            end = start + timedelta(days=duration_days)
+
+        return cls(
+            id=str(uuid.uuid4()),
+            name=name,
+            description=description,
+            start_date=start,
+            end_date=end,
+            tags=frozenset(tags) if tags else frozenset(),
+            priority=priority,
+            metadata=metadata or {},
+            created_at=now,
+        )
+
+    @property
+    def is_active(self) -> bool:
+        """Check if project is currently active."""
+        now = datetime.utcnow()
+        if now < self.start_date:
+            return False
+        if self.end_date is not None and now > self.end_date:
+            return False
+        return True
+
+    @property
+    def is_ongoing(self) -> bool:
+        """Check if project has no defined end date."""
+        return self.end_date is None
+
+    @property
+    def days_remaining(self) -> int | None:
+        """Get days remaining until project end, or None if ongoing."""
+        if self.end_date is None:
+            return None
+        delta = self.end_date - datetime.utcnow()
+        return max(0, delta.days)
+
+    @property
+    def duration_days(self) -> int | None:
+        """Get total project duration in days, or None if ongoing."""
+        if self.end_date is None:
+            return None
+        delta = self.end_date - self.start_date
+        return delta.days
+
+    def contains_date(self, date: datetime) -> bool:
+        """Check if a date falls within project timeframe."""
+        if date < self.start_date:
+            return False
+        if self.end_date is not None and date > self.end_date:
+            return False
+        return True
+
+    def with_end_date(self, end_date: datetime) -> Project:
+        """Create a copy with new end date."""
+        return Project(
+            id=self.id,
+            name=self.name,
+            description=self.description,
+            start_date=self.start_date,
+            end_date=end_date,
+            tags=self.tags,
+            priority=self.priority,
+            metadata=self.metadata,
+            created_at=self.created_at,
+        )
+
+    def with_extended_deadline(self, extra_days: int) -> Project:
+        """Extend project deadline by given days."""
+        if self.end_date is None:
+            raise ValueError("Cannot extend ongoing project - set end_date first")
+        new_end = self.end_date + timedelta(days=extra_days)
+        return self.with_end_date(new_end)
+
+    def with_tags(self, tags: set[str]) -> Project:
+        """Create a copy with new tags."""
+        return Project(
+            id=self.id,
+            name=self.name,
+            description=self.description,
+            start_date=self.start_date,
+            end_date=self.end_date,
+            tags=frozenset(tags),
+            priority=self.priority,
+            metadata=self.metadata,
+            created_at=self.created_at,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "start_date": self.start_date.isoformat(),
+            "end_date": self.end_date.isoformat() if self.end_date else None,
+            "tags": list(self.tags),
+            "priority": self.priority,
+            "metadata": self.metadata,
+            "created_at": self.created_at.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Project:
+        """Create from dictionary."""
+        return cls(
+            id=data["id"],
+            name=data["name"],
+            description=data.get("description", ""),
+            start_date=datetime.fromisoformat(data["start_date"]),
+            end_date=datetime.fromisoformat(data["end_date"]) if data.get("end_date") else None,
+            tags=frozenset(data.get("tags", [])),
+            priority=data.get("priority", 1.0),
+            metadata=data.get("metadata", {}),
+            created_at=datetime.fromisoformat(data["created_at"]),
+        )
+
+
+@dataclass(frozen=True)
+class MemoryScope:
+    """Defines what memories to prioritize for retrieval.
+
+    Used to filter and boost memories based on project, time window, or tags.
+    """
+
+    project_id: str | None = None
+    time_window_days: int | None = 7  # Auto-prioritize recent
+    tags: frozenset[str] | None = None
+    min_relevance: float = 0.3  # Threshold for inclusion
+
+    @classmethod
+    def for_project(cls, project_id: str) -> MemoryScope:
+        """Create scope for specific project."""
+        return cls(project_id=project_id)
+
+    @classmethod
+    def recent(cls, days: int = 7) -> MemoryScope:
+        """Create scope for recent memories."""
+        return cls(time_window_days=days)
+
+    @classmethod
+    def with_tags(cls, tags: set[str]) -> MemoryScope:
+        """Create scope for specific tags."""
+        return cls(tags=frozenset(tags))
+
+    def matches(
+        self,
+        project_id: str | None = None,
+        created_at: datetime | None = None,
+        tags: frozenset[str] | None = None,
+    ) -> bool:
+        """Check if memory attributes match this scope."""
+        # Project filter
+        if self.project_id is not None and project_id != self.project_id:
+            return False
+
+        # Time window filter
+        if self.time_window_days is not None and created_at is not None:
+            cutoff = datetime.utcnow() - timedelta(days=self.time_window_days)
+            if created_at < cutoff:
+                return False
+
+        # Tags filter (must have at least one matching tag)
+        if self.tags is not None and tags is not None:
+            if not self.tags.intersection(tags):
+                return False
+
+        return True
+
+    def relevance_boost(
+        self,
+        created_at: datetime | None = None,
+        project_priority: float = 1.0,
+    ) -> float:
+        """Calculate relevance boost for a memory.
+
+        Returns multiplier (1.0 = no boost, >1.0 = boosted).
+        """
+        boost = 1.0
+
+        # Recency boost (exponential decay within window)
+        if self.time_window_days is not None and created_at is not None:
+            days_ago = (datetime.utcnow() - created_at).days
+            if days_ago <= self.time_window_days:
+                # Linear decay: 1.5 at day 0, 1.0 at window edge
+                recency_factor = 1.0 + 0.5 * (1 - days_ago / self.time_window_days)
+                boost *= recency_factor
+
+        # Project priority boost
+        boost *= project_priority
+
+        return boost

neural_memory/core/synapse.py

@@ -0,0 +1,215 @@
+"""Synapse data structures - connections between neurons."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+from uuid import uuid4
+
+
+class SynapseType(StrEnum):
+    """Types of synaptic connections between neurons."""
+
+    # Temporal relationships
+    HAPPENED_AT = "happened_at"  # Event -> Time
+    BEFORE = "before"  # Event A -> Event B (A happened before B)
+    AFTER = "after"  # Event A -> Event B (A happened after B)
+    DURING = "during"  # Event -> Period
+
+    # Spatial relationships
+    AT_LOCATION = "at_location"  # Event/Entity -> Place
+    CONTAINS = "contains"  # Place -> Entity
+    NEAR = "near"  # Place -> Place
+
+    # Causal relationships
+    CAUSED_BY = "caused_by"  # Effect -> Cause
+    LEADS_TO = "leads_to"  # Cause -> Effect
+    ENABLES = "enables"  # Condition -> Action
+    PREVENTS = "prevents"  # Blocker -> Action
+
+    # Associative relationships
+    CO_OCCURS = "co_occurs"  # Entity -> Entity (appear together)
+    RELATED_TO = "related_to"  # General association
+    SIMILAR_TO = "similar_to"  # Semantic similarity
+
+    # Semantic relationships
+    IS_A = "is_a"  # Instance -> Category
+    HAS_PROPERTY = "has_property"  # Entity -> Property
+    INVOLVES = "involves"  # Event -> Entity
+
+    # Emotional relationships
+    FELT = "felt"  # Event -> Emotion
+    EVOKES = "evokes"  # Stimulus -> Emotion
+
+
+class Direction(StrEnum):
+    """Direction of synapse connection."""
+
+    UNIDIRECTIONAL = "uni"  # One-way: source -> target
+    BIDIRECTIONAL = "bi"  # Two-way: source <-> target
+
+
+# Synapse types that are typically bidirectional
+BIDIRECTIONAL_TYPES: frozenset[SynapseType] = frozenset(
+    {
+        SynapseType.CO_OCCURS,
+        SynapseType.RELATED_TO,
+        SynapseType.SIMILAR_TO,
+        SynapseType.NEAR,
+    }
+)
+
+# Synapse types with inverse relationships
+INVERSE_TYPES: dict[SynapseType, SynapseType] = {
+    SynapseType.BEFORE: SynapseType.AFTER,
+    SynapseType.AFTER: SynapseType.BEFORE,
+    SynapseType.CAUSED_BY: SynapseType.LEADS_TO,
+    SynapseType.LEADS_TO: SynapseType.CAUSED_BY,
+    SynapseType.CONTAINS: SynapseType.AT_LOCATION,
+    SynapseType.AT_LOCATION: SynapseType.CONTAINS,
+}
+
+
+@dataclass
+class Synapse:
+    """
+    A synapse represents a connection between two neurons.
+
+    Synapses have semantic meaning (type) and strength (weight).
+    They can be reinforced through use or decay over time.
+
+    Attributes:
+        id: Unique identifier
+        source_id: ID of the source neuron
+        target_id: ID of the target neuron
+        type: The semantic type of this connection
+        weight: Connection strength (0.0 - 1.0)
+        direction: Whether connection is uni or bidirectional
+        metadata: Additional connection-specific data
+        reinforced_count: How many times this connection was reinforced
+        last_activated: When this synapse was last used
+        created_at: When this synapse was created
+    """
+
+    id: str
+    source_id: str
+    target_id: str
+    type: SynapseType
+    weight: float = 0.5
+    direction: Direction = Direction.UNIDIRECTIONAL
+    metadata: dict[str, Any] = field(default_factory=dict)
+    reinforced_count: int = 0
+    last_activated: datetime | None = None
+    created_at: datetime = field(default_factory=datetime.utcnow)
+
+    @classmethod
+    def create(
+        cls,
+        source_id: str,
+        target_id: str,
+        type: SynapseType,
+        weight: float = 0.5,
+        direction: Direction | None = None,
+        metadata: dict[str, Any] | None = None,
+        synapse_id: str | None = None,
+    ) -> Synapse:
+        """
+        Factory method to create a new Synapse.
+
+        Args:
+            source_id: ID of source neuron
+            target_id: ID of target neuron
+            type: Synapse type
+            weight: Initial weight (default 0.5)
+            direction: Connection direction (auto-detected if None)
+            metadata: Optional metadata
+            synapse_id: Optional explicit ID
+
+        Returns:
+            A new Synapse instance
+        """
+        # Auto-detect direction based on type
+        if direction is None:
+            direction = (
+                Direction.BIDIRECTIONAL if type in BIDIRECTIONAL_TYPES else Direction.UNIDIRECTIONAL
+            )
+
+        return cls(
+            id=synapse_id or str(uuid4()),
+            source_id=source_id,
+            target_id=target_id,
+            type=type,
+            weight=max(0.0, min(1.0, weight)),
+            direction=direction,
+            metadata=metadata or {},
+            created_at=datetime.utcnow(),
+        )
+
+    def reinforce(self, delta: float = 0.05) -> Synapse:
+        """
+        Create a new Synapse with reinforced weight.
+
+        Args:
+            delta: Amount to increase weight by
+
+        Returns:
+            New Synapse with increased weight (capped at 1.0)
+        """
+        return Synapse(
+            id=self.id,
+            source_id=self.source_id,
+            target_id=self.target_id,
+            type=self.type,
+            weight=min(1.0, self.weight + delta),
+            direction=self.direction,
+            metadata=self.metadata,
+            reinforced_count=self.reinforced_count + 1,
+            last_activated=datetime.utcnow(),
+            created_at=self.created_at,
+        )
+
+    def decay(self, factor: float = 0.95) -> Synapse:
+        """
+        Create a new Synapse with decayed weight.
+
+        Args:
+            factor: Decay multiplier (0.0 - 1.0)
+
+        Returns:
+            New Synapse with decreased weight
+        """
+        return Synapse(
+            id=self.id,
+            source_id=self.source_id,
+            target_id=self.target_id,
+            type=self.type,
+            weight=self.weight * factor,
+            direction=self.direction,
+            metadata=self.metadata,
+            reinforced_count=self.reinforced_count,
+            last_activated=self.last_activated,
+            created_at=self.created_at,
+        )
+
+    @property
+    def is_bidirectional(self) -> bool:
+        """Check if this synapse allows traversal in both directions."""
+        return self.direction == Direction.BIDIRECTIONAL
+
+    def get_inverse_type(self) -> SynapseType | None:
+        """Get the inverse synapse type if one exists."""
+        return INVERSE_TYPES.get(self.type)
+
+    def connects(self, neuron_id: str) -> bool:
+        """Check if this synapse connects to a given neuron."""
+        return self.source_id == neuron_id or self.target_id == neuron_id
+
+    def other_end(self, neuron_id: str) -> str | None:
+        """Get the ID of the neuron at the other end of this synapse."""
+        if self.source_id == neuron_id:
+            return self.target_id
+        if self.target_id == neuron_id:
+            return self.source_id
+        return None

neural_memory/engine/__init__.py

@@ -0,0 +1,15 @@
+"""Engine components for memory encoding and retrieval."""
+
+from neural_memory.engine.activation import ActivationResult, SpreadingActivation
+from neural_memory.engine.encoder import EncodingResult, MemoryEncoder
+from neural_memory.engine.retrieval import DepthLevel, ReflexPipeline, RetrievalResult
+
+__all__ = [
+    "ActivationResult",
+    "DepthLevel",
+    "EncodingResult",
+    "MemoryEncoder",
+    "ReflexPipeline",
+    "RetrievalResult",
+    "SpreadingActivation",
+]