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

abstractmemory/graph/knowledge_graph.py

@@ -0,0 +1,178 @@
+"""
+Temporal knowledge graph implementation.
+"""
+
+import networkx as nx
+from datetime import datetime
+from typing import Dict, List, Optional, Tuple, Any
+
+from abstractmemory.core.temporal import GroundingAnchor, TemporalSpan, RelationalContext
+
+
+class TemporalKnowledgeGraph:
+    """
+    Knowledge graph with bi-temporal modeling.
+    Based on Zep/Graphiti architecture.
+    """
+
+    def __init__(self):
+        self.graph = nx.MultiDiGraph()
+        self._node_counter = 0
+        self._edge_counter = 0
+        self.ontology = {}  # Auto-built ontology
+
+    def add_entity(self, value: str, entity_type: str = 'entity') -> str:
+        """Add or get entity node"""
+        # Check for existing entity (deduplication)
+        for node_id, data in self.graph.nodes(data=True):
+            if data.get('value') == value:
+                # Update access time
+                self.graph.nodes[node_id]['last_accessed'] = datetime.now()
+                return node_id
+
+        # Create new entity
+        node_id = f"entity_{self._node_counter}"
+        self._node_counter += 1
+
+        self.graph.add_node(
+            node_id,
+            value=value,
+            type=entity_type,
+            created_at=datetime.now(),
+            last_accessed=datetime.now(),
+            importance=1.0
+        )
+
+        # Update ontology
+        if entity_type not in self.ontology:
+            self.ontology[entity_type] = []
+        self.ontology[entity_type].append(node_id)
+
+        return node_id
+
+    def add_fact(self, subject: str, predicate: str, object: str,
+                event_time: datetime, confidence: float = 1.0,
+                source: Optional[str] = None, ingestion_time: Optional[datetime] = None) -> str:
+        """Add temporally anchored fact"""
+
+        # Get or create nodes
+        subj_id = self.add_entity(subject)
+        obj_id = self.add_entity(object)
+
+        # Create grounding anchor
+        anchor = GroundingAnchor(
+            event_time=event_time,
+            ingestion_time=ingestion_time or datetime.now(),
+            validity_span=TemporalSpan(start=event_time),
+            relational=RelationalContext(user_id="default"),  # Will be updated when used in GroundedMemory
+            confidence=confidence,
+            source=source
+        )
+
+        # Check for contradictions
+        self._handle_contradictions(subj_id, predicate, obj_id, anchor)
+
+        # Add edge with temporal data
+        edge_id = f"edge_{self._edge_counter}"
+        self._edge_counter += 1
+
+        self.graph.add_edge(
+            subj_id, obj_id,
+            key=edge_id,
+            predicate=predicate,
+            anchor=anchor,
+            confidence=confidence,
+            valid=True
+        )
+
+        return edge_id
+
+    def _handle_contradictions(self, subj_id: str, predicate: str,
+                              obj_id: str, new_anchor: GroundingAnchor):
+        """Handle temporal contradictions"""
+        # Check existing edges for contradictions
+        for _, _, key, data in self.graph.edges(subj_id, keys=True, data=True):
+            if data.get('predicate') == predicate and data.get('valid'):
+                old_anchor = data.get('anchor')
+                if old_anchor:
+                    # Check for temporal overlap
+                    if self._has_temporal_overlap(old_anchor, new_anchor):
+                        # Invalidate older fact (new info takes precedence)
+                        if old_anchor.ingestion_time < new_anchor.ingestion_time:
+                            data['valid'] = False
+                            old_anchor.validity_span.end = new_anchor.event_time
+                            old_anchor.validity_span.valid = False
+
+    def _has_temporal_overlap(self, anchor1: GroundingAnchor,
+                             anchor2: GroundingAnchor) -> bool:
+        """Check if two anchors have temporal overlap"""
+        span1 = anchor1.validity_span
+        span2 = anchor2.validity_span
+
+        # If either span has no end, check if starts overlap
+        if span1.end is None or span2.end is None:
+            return True  # Conservative: assume overlap
+
+        # Check for actual overlap
+        return not (span1.end < span2.start or span2.end < span1.start)
+
+    def query_at_time(self, query: str, point_in_time: datetime) -> List[Dict[str, Any]]:
+        """Query knowledge state at specific time"""
+        results = []
+
+        for u, v, key, data in self.graph.edges(keys=True, data=True):
+            anchor = data.get('anchor')
+            if not anchor:
+                continue
+
+            # Check if fact was known and valid at this time
+            if (anchor.ingestion_time <= point_in_time and
+                anchor.event_time <= point_in_time and
+                data.get('valid', True)):  # Default to True if not explicitly set
+
+                # Check if still valid at query time
+                if (anchor.validity_span.end is None or
+                    anchor.validity_span.end > point_in_time):
+
+                    # Check if matches query
+                    if query.lower() in data.get('predicate', '').lower():
+                        results.append({
+                            'subject': self.graph.nodes[u]['value'],
+                            'predicate': data['predicate'],
+                            'object': self.graph.nodes[v]['value'],
+                            'confidence': data.get('confidence', 1.0),
+                            'event_time': anchor.event_time,
+                            'source': getattr(anchor, 'source', None)
+                        })
+
+        return results
+
+    def get_entity_evolution(self, entity: str, start: datetime,
+                            end: datetime) -> List[Dict[str, Any]]:
+        """Track how entity's relationships evolved over time"""
+        # Find entity node
+        entity_id = None
+        for node_id, data in self.graph.nodes(data=True):
+            if data.get('value') == entity:
+                entity_id = node_id
+                break
+
+        if not entity_id:
+            return []
+
+        evolution = []
+
+        # Check all edges involving this entity
+        for u, v, key, data in self.graph.edges(keys=True, data=True):
+            if u == entity_id or v == entity_id:
+                anchor = data.get('anchor')
+                if anchor and start <= anchor.event_time <= end:
+                    evolution.append({
+                        'time': anchor.event_time,
+                        'type': 'fact_added' if data.get('valid') else 'fact_invalidated',
+                        'subject': self.graph.nodes[u]['value'],
+                        'predicate': data['predicate'],
+                        'object': self.graph.nodes[v]['value']
+                    })
+
+        return sorted(evolution, key=lambda x: x['time'])

abstractmemory/simple.py

@@ -0,0 +1,151 @@
+"""
+Simple, efficient memory for task-specific agents.
+No over-engineering - just what's needed for the job.
+"""
+
+from typing import List, Optional, Dict, Any
+from collections import deque
+from datetime import datetime
+
+
+class ScratchpadMemory:
+    """
+    Lightweight memory for ReAct agents and single-task tools.
+
+    Use this for:
+    - ReAct agent thought-action-observation cycles
+    - Summarizer working memory
+    - Extractor temporary context
+    - Any agent that doesn't need persistence
+
+    Example:
+        # For a ReAct agent
+        scratchpad = ScratchpadMemory(max_entries=20)
+        scratchpad.add_thought("Need to search for Python tutorials")
+        scratchpad.add_action("search", {"query": "Python basics"})
+        scratchpad.add_observation("Found 10 relevant tutorials")
+
+        # Get full context for next iteration
+        context = scratchpad.get_context()
+    """
+
+    def __init__(self, max_entries: int = 100):
+        """Initialize scratchpad with bounded size"""
+        self.entries: deque = deque(maxlen=max_entries)
+        self.thoughts: List[str] = []
+        self.actions: List[Dict[str, Any]] = []
+        self.observations: List[str] = []
+
+    def add(self, content: str, entry_type: str = "note"):
+        """Add any entry to scratchpad"""
+        entry = {
+            "type": entry_type,
+            "content": content,
+            "timestamp": datetime.now().isoformat()
+        }
+        self.entries.append(entry)
+
+    def add_thought(self, thought: str):
+        """Add a thought (for ReAct pattern)"""
+        self.thoughts.append(thought)
+        self.add(thought, "thought")
+
+    def add_action(self, action: str, params: Optional[Dict] = None):
+        """Add an action (for ReAct pattern)"""
+        action_entry = {"action": action, "params": params or {}}
+        self.actions.append(action_entry)
+        self.add(f"Action: {action} with {params}", "action")
+
+    def add_observation(self, observation: str):
+        """Add an observation (for ReAct pattern)"""
+        self.observations.append(observation)
+        self.add(observation, "observation")
+
+    def get_context(self, last_n: Optional[int] = None) -> str:
+        """Get scratchpad context as string"""
+        entries_to_use = list(self.entries)
+        if last_n:
+            entries_to_use = entries_to_use[-last_n:]
+
+        context_lines = []
+        for entry in entries_to_use:
+            if entry["type"] == "thought":
+                context_lines.append(f"Thought: {entry['content']}")
+            elif entry["type"] == "action":
+                context_lines.append(f"Action: {entry['content']}")
+            elif entry["type"] == "observation":
+                context_lines.append(f"Observation: {entry['content']}")
+            else:
+                context_lines.append(entry['content'])
+
+        return "\n".join(context_lines)
+
+    def get_react_history(self) -> Dict[str, List]:
+        """Get structured ReAct history"""
+        return {
+            "thoughts": self.thoughts,
+            "actions": self.actions,
+            "observations": self.observations
+        }
+
+    def clear(self):
+        """Clear the scratchpad"""
+        self.entries.clear()
+        self.thoughts.clear()
+        self.actions.clear()
+        self.observations.clear()
+
+    def __len__(self) -> int:
+        return len(self.entries)
+
+    def __str__(self) -> str:
+        return f"ScratchpadMemory({len(self.entries)} entries)"
+
+
+class BufferMemory:
+    """
+    Simple conversation buffer (wrapper around BasicSession).
+
+    Use this when BasicSession from AbstractLLM Core is sufficient.
+    This is just a thin adapter for compatibility.
+
+    Example:
+        # For a simple chatbot
+        memory = BufferMemory(max_messages=50)
+        memory.add_message("user", "What's the weather?")
+        memory.add_message("assistant", "I don't have weather data")
+        context = memory.get_context()
+    """
+
+    def __init__(self, max_messages: int = 100):
+        """Initialize buffer with size limit"""
+        self.messages: deque = deque(maxlen=max_messages)
+
+    def add_message(self, role: str, content: str):
+        """Add a message to the buffer"""
+        self.messages.append({
+            "role": role,
+            "content": content,
+            "timestamp": datetime.now().isoformat()
+        })
+
+    def get_messages(self) -> List[Dict[str, str]]:
+        """Get messages for LLM context"""
+        return [{"role": m["role"], "content": m["content"]}
+                for m in self.messages]
+
+    def get_context(self, last_n: Optional[int] = None) -> str:
+        """Get conversation as formatted string"""
+        messages = list(self.messages)
+        if last_n:
+            messages = messages[-last_n:]
+
+        lines = []
+        for msg in messages:
+            lines.append(f"{msg['role']}: {msg['content']}")
+
+        return "\n".join(lines)
+
+    def clear(self):
+        """Clear the buffer"""
+        self.messages.clear()

abstractmemory/storage/__init__.py

@@ -0,0 +1,16 @@
+# Storage backends for memory persistence
+
+from .dual_manager import DualStorageManager
+from .markdown_storage import MarkdownStorage
+
+# LanceDB is optional
+try:
+    from .lancedb_storage import LanceDBStorage
+except ImportError:
+    LanceDBStorage = None
+
+__all__ = [
+    'DualStorageManager',
+    'MarkdownStorage',
+    'LanceDBStorage'
+]

abstractmemory/storage/dual_manager.py

@@ -0,0 +1,278 @@
+"""
+Dual Storage Manager for managing multiple storage backends.
+Supports markdown, lancedb, dual, or no storage modes.
+"""
+
+from typing import Optional, Dict, List, Literal, Any
+from datetime import datetime
+import logging
+
+from ..core.interfaces import IStorage
+
+logger = logging.getLogger(__name__)
+
+
+class DualStorageManager:
+    """
+    Manages multiple storage backends for verbatim interactions and experiential notes.
+
+    Modes:
+    - "markdown": Human-readable, observable, version-controllable
+    - "lancedb": SQL + vector search capabilities via AbstractCore embeddings
+    - "dual": Write to both, read from LanceDB for performance
+    - None: No persistence (default)
+    """
+
+    def __init__(self,
+                 mode: Optional[Literal["markdown", "lancedb", "dual"]] = None,
+                 markdown_path: Optional[str] = None,
+                 lancedb_uri: Optional[str] = None,
+                 embedding_provider: Optional[Any] = None):
+        """
+        Initialize storage manager.
+
+        Args:
+            mode: Storage mode to use
+            markdown_path: Path for markdown storage
+            lancedb_uri: URI for LanceDB storage
+            embedding_provider: AbstractCore instance for embeddings
+        """
+        self.mode = mode
+        self.embedding_provider = embedding_provider
+
+        # Initialize storage backends based on mode
+        self.markdown_storage = None
+        self.lancedb_storage = None
+
+        if mode in ["markdown", "dual"] and markdown_path:
+            try:
+                from .markdown_storage import MarkdownStorage
+                self.markdown_storage = MarkdownStorage(markdown_path)
+                logger.info(f"Initialized markdown storage at {markdown_path}")
+            except (ImportError, OSError, FileNotFoundError) as e:
+                logger.warning(f"Failed to initialize markdown storage: {e}")
+                self.markdown_storage = None
+
+        if mode in ["lancedb", "dual"] and lancedb_uri:
+            try:
+                from .lancedb_storage import LanceDBStorage
+                self.lancedb_storage = LanceDBStorage(lancedb_uri, embedding_provider)
+                logger.info(f"Initialized LanceDB storage at {lancedb_uri}")
+            except (ImportError, OSError, FileNotFoundError) as e:
+                logger.warning(f"Failed to initialize LanceDB storage: {e}")
+                self.lancedb_storage = None
+
+    def is_enabled(self) -> bool:
+        """Check if any storage backend is enabled"""
+        return self.mode is not None and (self.markdown_storage is not None or self.lancedb_storage is not None)
+
+    def save_interaction(self, user_id: str, timestamp: datetime,
+                        user_input: str, agent_response: str,
+                        topic: str, metadata: Optional[Dict] = None) -> Optional[str]:
+        """
+        Save verbatim interaction to enabled storage backends.
+
+        Returns:
+            Interaction ID if successful, None if no storage enabled
+        """
+        if not self.is_enabled():
+            return None
+
+        interaction_id = None
+
+        # Save to markdown storage
+        if self.markdown_storage:
+            try:
+                interaction_id = self.markdown_storage.save_interaction(
+                    user_id, timestamp, user_input, agent_response, topic, metadata
+                )
+                logger.debug(f"Saved interaction {interaction_id} to markdown storage")
+            except Exception as e:
+                logger.error(f"Failed to save interaction to markdown: {e}")
+
+        # Save to LanceDB storage
+        if self.lancedb_storage:
+            try:
+                # Generate embedding if provider available
+                embedding = None
+                if self.embedding_provider:
+                    text = f"{user_input} {agent_response}"
+                    embedding = self.embedding_provider.generate_embedding(text)
+
+                ldb_id = self.lancedb_storage.save_interaction(
+                    user_id, timestamp, user_input, agent_response, topic, metadata
+                )
+                if interaction_id is None:  # Use LanceDB ID if markdown didn't provide one
+                    interaction_id = ldb_id
+
+                logger.debug(f"Saved interaction {ldb_id} to LanceDB storage")
+            except Exception as e:
+                logger.error(f"Failed to save interaction to LanceDB: {e}")
+
+        return interaction_id
+
+    def save_experiential_note(self, timestamp: datetime, reflection: str,
+                              interaction_id: str, note_type: str = "reflection",
+                              metadata: Optional[Dict] = None) -> Optional[str]:
+        """
+        Save AI experiential note to enabled storage backends.
+
+        Returns:
+            Note ID if successful, None if no storage enabled
+        """
+        if not self.is_enabled():
+            return None
+
+        note_id = None
+
+        # Save to markdown storage
+        if self.markdown_storage:
+            try:
+                note_id = self.markdown_storage.save_experiential_note(
+                    timestamp, reflection, interaction_id, note_type, metadata
+                )
+                logger.debug(f"Saved experiential note {note_id} to markdown storage")
+            except Exception as e:
+                logger.error(f"Failed to save experiential note to markdown: {e}")
+
+        # Save to LanceDB storage
+        if self.lancedb_storage:
+            try:
+                # Generate embedding for reflection if provider available
+                embedding = None
+                if self.embedding_provider:
+                    embedding = self.embedding_provider.generate_embedding(reflection)
+
+                ldb_note_id = self.lancedb_storage.save_experiential_note(
+                    timestamp, reflection, interaction_id, note_type, metadata
+                )
+                if note_id is None:  # Use LanceDB ID if markdown didn't provide one
+                    note_id = ldb_note_id
+
+                logger.debug(f"Saved experiential note {ldb_note_id} to LanceDB storage")
+            except Exception as e:
+                logger.error(f"Failed to save experiential note to LanceDB: {e}")
+
+        return note_id
+
+    def link_interaction_to_note(self, interaction_id: str, note_id: str) -> None:
+        """Create bidirectional link between interaction and experiential note"""
+        if not self.is_enabled():
+            return
+
+        # Link in markdown storage
+        if self.markdown_storage:
+            try:
+                self.markdown_storage.link_interaction_to_note(interaction_id, note_id)
+                logger.debug(f"Linked interaction {interaction_id} to note {note_id} in markdown")
+            except Exception as e:
+                logger.error(f"Failed to create link in markdown: {e}")
+
+        # Link in LanceDB storage
+        if self.lancedb_storage:
+            try:
+                self.lancedb_storage.link_interaction_to_note(interaction_id, note_id)
+                logger.debug(f"Linked interaction {interaction_id} to note {note_id} in LanceDB")
+            except Exception as e:
+                logger.error(f"Failed to create link in LanceDB: {e}")
+
+    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. Prefers LanceDB for performance, falls back to markdown.
+
+        Returns:
+            List of matching interactions
+        """
+        if not self.is_enabled():
+            return []
+
+        # Prefer LanceDB for search if available (SQL + vector capabilities)
+        if self.lancedb_storage:
+            try:
+                results = self.lancedb_storage.search_interactions(
+                    query, user_id, start_date, end_date
+                )
+                logger.debug(f"Found {len(results)} interactions via LanceDB search")
+                return results
+            except Exception as e:
+                logger.error(f"LanceDB search failed: {e}")
+
+        # Fallback to markdown search
+        if self.markdown_storage:
+            try:
+                results = self.markdown_storage.search_interactions(
+                    query, user_id, start_date, end_date
+                )
+                logger.debug(f"Found {len(results)} interactions via markdown search")
+                return results
+            except Exception as e:
+                logger.error(f"Markdown search failed: {e}")
+
+        return []
+
+    def save_memory_component(self, component_name: str, component_data: Any) -> None:
+        """Save memory component (core, semantic, working, episodic) for backup"""
+        if not self.is_enabled():
+            return
+
+        # Save to markdown as human-readable snapshot
+        if self.markdown_storage and hasattr(self.markdown_storage, 'save_memory_component'):
+            try:
+                self.markdown_storage.save_memory_component(component_name, component_data)
+                logger.debug(f"Saved {component_name} component to markdown storage")
+            except Exception as e:
+                logger.error(f"Failed to save {component_name} to markdown: {e}")
+
+        # Save to LanceDB for efficient querying
+        if self.lancedb_storage and hasattr(self.lancedb_storage, 'save_memory_component'):
+            try:
+                self.lancedb_storage.save_memory_component(component_name, component_data)
+                logger.debug(f"Saved {component_name} component to LanceDB storage")
+            except Exception as e:
+                logger.error(f"Failed to save {component_name} to LanceDB: {e}")
+
+    def load_memory_component(self, component_name: str) -> Optional[Any]:
+        """Load memory component. Prefers LanceDB for performance."""
+        if not self.is_enabled():
+            return None
+
+        # Try LanceDB first for performance
+        if self.lancedb_storage and hasattr(self.lancedb_storage, 'load_memory_component'):
+            try:
+                component = self.lancedb_storage.load_memory_component(component_name)
+                if component is not None:
+                    logger.debug(f"Loaded {component_name} component from LanceDB storage")
+                    return component
+            except Exception as e:
+                logger.error(f"Failed to load {component_name} from LanceDB: {e}")
+
+        # Fallback to markdown
+        if self.markdown_storage and hasattr(self.markdown_storage, 'load_memory_component'):
+            try:
+                component = self.markdown_storage.load_memory_component(component_name)
+                if component is not None:
+                    logger.debug(f"Loaded {component_name} component from markdown storage")
+                    return component
+            except Exception as e:
+                logger.error(f"Failed to load {component_name} from markdown: {e}")
+
+        return None
+
+    def get_storage_stats(self) -> Dict[str, Any]:
+        """Get statistics about stored data"""
+        stats = {
+            "mode": self.mode,
+            "markdown_enabled": self.markdown_storage is not None,
+            "lancedb_enabled": self.lancedb_storage is not None,
+            "embedding_provider": self.embedding_provider is not None
+        }
+
+        if self.markdown_storage and hasattr(self.markdown_storage, 'get_stats'):
+            stats["markdown_stats"] = self.markdown_storage.get_stats()
+
+        if self.lancedb_storage and hasattr(self.lancedb_storage, 'get_stats'):
+            stats["lancedb_stats"] = self.lancedb_storage.get_stats()
+
+        return stats