AbstractMemory 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

abstractmemory/cognitive/__init__.py

@@ -0,0 +1 @@
+# Cognitive memory patterns and learning

abstractmemory/components/__init__.py

@@ -0,0 +1 @@
+# Memory components for four-tier architecture

abstractmemory/components/core.py

@@ -0,0 +1,112 @@
+"""
+Core memory - always-accessible foundational facts (MemGPT/Letta pattern).
+"""
+
+from typing import Dict, Optional, List
+from datetime import datetime
+from dataclasses import dataclass
+
+from abstractmemory.core.interfaces import IMemoryComponent, MemoryItem
+
+
+@dataclass
+class CoreMemoryBlock:
+    """A block of core memory (always in context)"""
+    block_id: str
+    label: str           # "persona" or "user_info"
+    content: str         # Max ~200 tokens
+    last_updated: datetime
+    edit_count: int = 0
+
+    def update(self, new_content: str, agent_reasoning: str):
+        """Agent can self-edit this block"""
+        self.content = new_content
+        self.last_updated = datetime.now()
+        self.edit_count += 1
+
+
+class CoreMemory(IMemoryComponent):
+    """
+    Always-accessible core memory for fundamental facts.
+    Based on MemGPT/Letta research - stores agent persona + user information.
+    """
+
+    def __init__(self, max_blocks: int = 10, max_tokens_per_block: int = 200):
+        self.blocks: Dict[str, CoreMemoryBlock] = {}
+        self.max_blocks = max_blocks
+        self.max_tokens_per_block = max_tokens_per_block
+
+        # Initialize default blocks (MemGPT pattern)
+        self.blocks["persona"] = CoreMemoryBlock(
+            block_id="persona",
+            label="persona",
+            content="I am an AI assistant with persistent memory capabilities.",
+            last_updated=datetime.now()
+        )
+        self.blocks["user_info"] = CoreMemoryBlock(
+            block_id="user_info",
+            label="user_info",
+            content="User information will be learned over time.",
+            last_updated=datetime.now()
+        )
+
+    def get_context(self) -> str:
+        """Get all core memory as context string (always included in prompts)"""
+        context_parts = []
+        for block in self.blocks.values():
+            context_parts.append(f"[{block.label}] {block.content}")
+        return "\n".join(context_parts)
+
+    def update_block(self, block_id: str, content: str, reasoning: str = "") -> bool:
+        """Agent updates a core memory block (self-editing capability)"""
+        if block_id in self.blocks:
+            if len(content) <= self.max_tokens_per_block * 4:  # Rough token estimate
+                self.blocks[block_id].update(content, reasoning)
+                return True
+        return False
+
+    def add_block(self, label: str, content: str) -> Optional[str]:
+        """Add new core memory block if space available"""
+        if len(self.blocks) < self.max_blocks:
+            block_id = f"core_{len(self.blocks)}"
+            self.blocks[block_id] = CoreMemoryBlock(
+                block_id=block_id,
+                label=label,
+                content=content,
+                last_updated=datetime.now()
+            )
+            return block_id
+        return None
+
+    # IMemoryComponent interface implementation
+    def add(self, item: MemoryItem) -> str:
+        """Add important fact to core memory"""
+        # Convert MemoryItem to core memory block
+        content = str(item.content)
+        if "user" in content.lower():
+            return self.update_block("user_info", content) and "user_info" or ""
+        elif "persona" in content.lower() or "agent" in content.lower():
+            return self.update_block("persona", content) and "persona" or ""
+        else:
+            return self.add_block("general", content) or ""
+
+    def retrieve(self, query: str, limit: int = 10) -> List[MemoryItem]:
+        """Retrieve core memory blocks matching query"""
+        results = []
+        query_lower = query.lower()
+
+        for block in self.blocks.values():
+            if query_lower in block.content.lower() or query_lower in block.label.lower():
+                results.append(MemoryItem(
+                    content={"label": block.label, "content": block.content},
+                    event_time=block.last_updated,
+                    ingestion_time=block.last_updated,
+                    confidence=1.0,  # Core memory is always high confidence
+                    metadata={"block_id": block.block_id, "edit_count": block.edit_count}
+                ))
+
+        return results[:limit]
+
+    def consolidate(self) -> int:
+        """Core memory doesn't consolidate - it's manually curated"""
+        return 0

abstractmemory/components/episodic.py

@@ -0,0 +1,68 @@
+"""
+Episodic memory for experiences and events.
+"""
+
+from typing import List, Dict
+from datetime import datetime
+
+from abstractmemory.core.interfaces import IMemoryComponent, MemoryItem
+from abstractmemory.core.temporal import GroundingAnchor, TemporalSpan, RelationalContext
+
+
+class EpisodicMemory(IMemoryComponent):
+    """Long-term episodic memory with temporal organization"""
+
+    def __init__(self):
+        self.episodes = {}  # ID -> Episode
+        self.temporal_index = {}  # For temporal queries
+
+    def add(self, item: MemoryItem) -> str:
+        """Add episode to memory"""
+        episode_id = f"ep_{len(self.episodes)}_{datetime.now().timestamp()}"
+
+        # Create grounding anchor with minimal relational context
+        anchor = GroundingAnchor(
+            event_time=item.event_time,
+            ingestion_time=item.ingestion_time,
+            validity_span=TemporalSpan(start=item.event_time),
+            relational=RelationalContext(user_id="default"),  # Will be updated when used in GroundedMemory
+            confidence=item.confidence
+        )
+
+        self.episodes[episode_id] = {
+            'item': item,
+            'anchor': anchor,
+            'related': []  # Links to related episodes
+        }
+
+        # Update temporal index
+        self.temporal_index[episode_id] = anchor
+
+        return episode_id
+
+    def retrieve(self, query: str, limit: int = 10) -> List[MemoryItem]:
+        """Retrieve episodes matching query"""
+        # Simple implementation - would use embeddings in production
+        results = []
+        query_lower = query.lower()
+
+        for episode in self.episodes.values():
+            if query_lower in str(episode['item'].content).lower():
+                results.append(episode['item'])
+                if len(results) >= limit:
+                    break
+
+        return results
+
+    def consolidate(self) -> int:
+        """Consolidate similar episodes"""
+        # Would implement clustering/summarization
+        return 0
+
+    def get_episodes_between(self, start: datetime, end: datetime) -> List[MemoryItem]:
+        """Get episodes between times"""
+        results = []
+        for episode in self.episodes.values():
+            if start <= episode['anchor'].event_time <= end:
+                results.append(episode['item'])
+        return sorted(results, key=lambda x: x.event_time)

abstractmemory/components/semantic.py

@@ -0,0 +1,102 @@
+"""
+Semantic memory for facts, concepts, and learned knowledge.
+Separate from Core (identity) and Episodic (events).
+"""
+
+from typing import List, Dict, Set
+from datetime import datetime
+from collections import defaultdict
+
+from abstractmemory.core.interfaces import IMemoryComponent, MemoryItem
+
+
+class SemanticMemory(IMemoryComponent):
+    """
+    Long-term storage of facts and concepts learned over time.
+    Only stores validated, recurring knowledge.
+    """
+
+    def __init__(self, validation_threshold: int = 3):
+        """
+        Args:
+            validation_threshold: How many times a fact must be observed to be stored
+        """
+        self.facts: Dict[str, Dict] = {}  # Validated facts
+        self.concepts: Dict[str, Set[str]] = {}  # Concept relationships
+        self.pending_facts: defaultdict = defaultdict(int)  # Counting occurrences
+        self.validation_threshold = validation_threshold
+
+    def add(self, item: MemoryItem) -> str:
+        """Add potential fact - only stored after validation"""
+        fact_key = str(item.content).lower()
+
+        # Count occurrence
+        self.pending_facts[fact_key] += 1
+
+        # Promote to validated facts if threshold met
+        if self.pending_facts[fact_key] >= self.validation_threshold:
+            fact_id = f"fact_{len(self.facts)}_{datetime.now().timestamp()}"
+            occurrence_count = self.pending_facts[fact_key]
+            self.facts[fact_id] = {
+                'content': item.content,
+                'confidence': min(1.0, occurrence_count * 0.1 + 0.3),  # Confidence grows with repetition
+                'first_seen': item.event_time,
+                'validated_at': datetime.now(),
+                'occurrence_count': occurrence_count,
+                'original_metadata': item.metadata or {}
+            }
+            # Clear from pending
+            del self.pending_facts[fact_key]
+            return fact_id
+
+        return ""  # Not yet validated
+
+    def retrieve(self, query: str, limit: int = 10) -> List[MemoryItem]:
+        """Retrieve validated facts matching query"""
+        results = []
+        query_lower = query.lower()
+
+        for fact_id, fact in self.facts.items():
+            if query_lower in str(fact['content']).lower():
+                # Preserve original metadata and add occurrence count
+                original_metadata = fact.get('original_metadata', {})
+                metadata = original_metadata.copy()
+                metadata['occurrence_count'] = fact['occurrence_count']
+
+                results.append(MemoryItem(
+                    content=fact['content'],
+                    event_time=fact['first_seen'],
+                    ingestion_time=fact['validated_at'],
+                    confidence=fact['confidence'],
+                    metadata=metadata
+                ))
+                if len(results) >= limit:
+                    break
+
+        # Sort by confidence and return results
+        sorted_results = sorted(results, key=lambda x: x.confidence, reverse=True)[:limit]
+        return sorted_results
+
+    def consolidate(self) -> int:
+        """Link related facts into concepts"""
+        consolidated = 0
+        # Group facts by common terms
+        for fact_id, fact in self.facts.items():
+            words = str(fact['content']).lower().split()
+            for word in words:
+                if len(word) > 3:  # Skip short words
+                    if word not in self.concepts:
+                        self.concepts[word] = set()
+                    self.concepts[word].add(fact_id)
+                    consolidated += 1
+        return consolidated
+
+    def get_concept_network(self, concept: str) -> Dict[str, Set[str]]:
+        """Get related facts for a concept"""
+        if concept.lower() in self.concepts:
+            fact_ids = self.concepts[concept.lower()]
+            return {
+                'concept': concept,
+                'facts': [self.facts[fid]['content'] for fid in fact_ids if fid in self.facts]
+            }
+        return {'concept': concept, 'facts': []}

abstractmemory/components/working.py

@@ -0,0 +1,50 @@
+"""
+Working memory with sliding window.
+"""
+
+from collections import deque
+from typing import List, Optional
+from datetime import datetime
+
+from abstractmemory.core.interfaces import IMemoryComponent, MemoryItem
+
+
+class WorkingMemory(IMemoryComponent):
+    """Short-term working memory with fixed capacity"""
+
+    def __init__(self, capacity: int = 10):
+        self.capacity = capacity
+        self.items = deque(maxlen=capacity)
+
+    def add(self, item: MemoryItem) -> str:
+        """Add item to working memory"""
+        item_id = f"wm_{datetime.now().timestamp()}"
+        self.items.append((item_id, item))
+
+        # Auto-consolidate if over capacity (deque will handle max capacity automatically)
+        return item_id
+
+    def retrieve(self, query: str, limit: int = 10) -> List[MemoryItem]:
+        """Retrieve recent items matching query"""
+        results = []
+        query_lower = query.lower()
+
+        for item_id, item in self.items:
+            if query_lower in str(item.content).lower():
+                results.append(item)
+                if len(results) >= limit:
+                    break
+
+        return results
+
+    def consolidate(self) -> int:
+        """Move old items to episodic memory"""
+        # In real implementation, would move to episodic
+        to_consolidate = len(self.items) // 2
+        for _ in range(to_consolidate):
+            self.items.popleft()
+        return to_consolidate
+
+    def get_context_window(self) -> List[MemoryItem]:
+        """Get current context window"""
+        return [item for _, item in self.items]

abstractmemory/core/__init__.py

@@ -0,0 +1 @@
+# Core memory interfaces and temporal models

abstractmemory/core/interfaces.py

@@ -0,0 +1,95 @@
+"""
+Core memory interfaces based on SOTA research.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Tuple
+from datetime import datetime
+from dataclasses import dataclass
+
+
+@dataclass
+class MemoryItem:
+    """Base class for memory items"""
+    content: Any
+    event_time: datetime      # When it happened
+    ingestion_time: datetime  # When we learned it
+    confidence: float = 1.0
+    metadata: Dict[str, Any] = None
+
+    def __post_init__(self):
+        if self.metadata is None:
+            self.metadata = {}
+
+
+class IMemoryComponent(ABC):
+    """Interface for memory components"""
+
+    @abstractmethod
+    def add(self, item: MemoryItem) -> str:
+        """Add item to memory, return ID"""
+        pass
+
+    @abstractmethod
+    def retrieve(self, query: str, limit: int = 10) -> List[MemoryItem]:
+        """Retrieve relevant items"""
+        pass
+
+    @abstractmethod
+    def consolidate(self) -> int:
+        """Consolidate memory, return items consolidated"""
+        pass
+
+
+class IRetriever(ABC):
+    """Interface for retrieval strategies"""
+
+    @abstractmethod
+    def search(self, query: str, limit: int = 10) -> List[Tuple[float, Any]]:
+        """Search and return (score, item) tuples"""
+        pass
+
+
+class IStorage(ABC):
+    """Interface for storage backends"""
+
+    @abstractmethod
+    def save(self, key: str, value: Any) -> None:
+        """Save value with key"""
+        pass
+
+    @abstractmethod
+    def load(self, key: str) -> Any:
+        """Load value by key"""
+        pass
+
+    @abstractmethod
+    def exists(self, key: str) -> bool:
+        """Check if key exists"""
+        pass
+
+    @abstractmethod
+    def save_interaction(self, user_id: str, timestamp: datetime,
+                        user_input: str, agent_response: str,
+                        topic: str, metadata: Optional[Dict] = None) -> str:
+        """Save verbatim interaction, return interaction ID"""
+        pass
+
+    @abstractmethod
+    def save_experiential_note(self, timestamp: datetime, reflection: str,
+                              interaction_id: str, note_type: str = "reflection",
+                              metadata: Optional[Dict] = None) -> str:
+        """Save AI experiential note, return note ID"""
+        pass
+
+    @abstractmethod
+    def link_interaction_to_note(self, interaction_id: str, note_id: str) -> None:
+        """Create bidirectional link between interaction and note"""
+        pass
+
+    @abstractmethod
+    def search_interactions(self, query: str, user_id: Optional[str] = None,
+                           start_date: Optional[datetime] = None,
+                           end_date: Optional[datetime] = None) -> List[Dict]:
+        """Search interactions with filters"""
+        pass

abstractmemory/core/temporal.py

@@ -0,0 +1,100 @@
+"""
+Bi-temporal data model based on Zep/Graphiti research.
+"""
+
+from datetime import datetime, timedelta
+from typing import List, Optional, Tuple
+from dataclasses import dataclass, field
+
+
+@dataclass
+class TemporalSpan:
+    """Represents a time span with validity"""
+    start: datetime
+    end: Optional[datetime] = None
+    valid: bool = True
+
+
+@dataclass
+class RelationalContext:
+    """Who is involved in this memory"""
+    user_id: str                     # Primary user/speaker
+    agent_id: Optional[str] = None   # Which agent persona
+    relationship: Optional[str] = None  # "owner", "colleague", "stranger"
+    session_id: Optional[str] = None   # Conversation session
+
+@dataclass
+class GroundingAnchor:
+    """Multi-dimensional grounding for experiential memory"""
+    # Temporal grounding (when)
+    event_time: datetime        # When it happened
+    ingestion_time: datetime    # When we learned about it
+    validity_span: TemporalSpan # When it was/is valid
+
+    # Relational grounding (who)
+    relational: RelationalContext  # Who is involved
+
+    # Additional grounding
+    confidence: float = 1.0
+    source: Optional[str] = None
+    location: Optional[str] = None  # Where (optional)
+
+
+class TemporalIndex:
+    """Index for efficient temporal queries"""
+
+    def __init__(self):
+        self._by_event_time = []      # Sorted by event time
+        self._by_ingestion_time = []  # Sorted by ingestion time
+        self._anchors = {}             # ID -> GroundingAnchor
+
+    def add_anchor(self, anchor_id: str, anchor: GroundingAnchor):
+        """Add temporal anchor to index"""
+        self._anchors[anchor_id] = anchor
+
+        # Insert into sorted lists
+        self._insert_sorted(self._by_event_time,
+                          (anchor.event_time, anchor_id))
+        self._insert_sorted(self._by_ingestion_time,
+                          (anchor.ingestion_time, anchor_id))
+
+    def query_at_time(self, point_in_time: datetime,
+                     use_event_time: bool = True) -> List[str]:
+        """Get valid anchor IDs at specific time"""
+        valid_ids = []
+
+        for anchor_id, anchor in self._anchors.items():
+            # Check if anchor was known at this time
+            if anchor.ingestion_time > point_in_time:
+                continue
+
+            # Check if anchor was valid at this time
+            if use_event_time:
+                if anchor.event_time <= point_in_time:
+                    if anchor.validity_span.valid:
+                        if (anchor.validity_span.end is None or
+                            anchor.validity_span.end > point_in_time):
+                            valid_ids.append(anchor_id)
+
+        return valid_ids
+
+    def _insert_sorted(self, lst: list, item: tuple):
+        """Insert item into sorted list"""
+        import bisect
+        bisect.insort(lst, item)
+
+    def get_evolution(self, start: datetime, end: datetime) -> List[Tuple[datetime, str]]:
+        """Get evolution of knowledge between times"""
+        changes = []
+
+        for anchor_id, anchor in self._anchors.items():
+            # Include if ingested during period
+            if start <= anchor.ingestion_time <= end:
+                changes.append((anchor.ingestion_time, f"Added: {anchor_id}"))
+
+            # Include if invalidated during period
+            if anchor.validity_span.end:
+                if start <= anchor.validity_span.end <= end:
+                    changes.append((anchor.validity_span.end, f"Invalidated: {anchor_id}"))
+
+        return sorted(changes)

abstractmemory/graph/__init__.py

@@ -0,0 +1 @@
+# Temporal knowledge graph implementation