stellar-memory 1.0.0__py3-none-any.whl

stellar_memory/__init__.py

@@ -0,0 +1,164 @@
+"""Stellar Memory - A celestial-structure-based AI memory management system.
+
+Give any AI human-like memory, built on a celestial structure.
+"""
+
+from stellar_memory.stellar import StellarMemory
+from stellar_memory.config import (
+    StellarConfig, MemoryFunctionConfig, ZoneConfig,
+    EmbedderConfig, LLMConfig, TunerConfig,
+    ConsolidationConfig, SessionConfig,
+    EventConfig, NamespaceConfig, GraphConfig,
+    DecayConfig, EventLoggerConfig, RecallConfig,
+    VectorIndexConfig, SummarizationConfig,
+    AdaptiveDecayConfig, GraphAnalyticsConfig,
+    StorageConfig, SyncConfig, SecurityConfig,
+    ConnectorConfig, DashboardConfig,
+    EmotionConfig, ServerConfig,
+    MetacognitionConfig, SelfLearningConfig,
+    MultimodalConfig, ReasoningConfig, BenchmarkConfig,
+)
+from stellar_memory.models import (
+    MemoryItem, ScoreBreakdown, ReorbitResult, MemoryStats,
+    EvaluationResult, FeedbackRecord,
+    ConsolidationResult, SessionInfo, MemorySnapshot,
+    MemoryEdge, DecayResult, HealthStatus, SummarizationResult,
+    ChangeEvent, AccessRole, IngestResult, ZoneDistribution,
+    EmotionVector, TimelineEntry,
+    IntrospectionResult, ConfidentRecall, RecallLog,
+    OptimizationReport, ReasoningResult, Contradiction,
+    BenchmarkReport,
+)
+from stellar_memory.event_bus import EventBus
+from stellar_memory.memory_graph import MemoryGraph
+from stellar_memory.persistent_graph import PersistentMemoryGraph
+from stellar_memory.namespace import NamespaceManager
+from stellar_memory.decay_manager import DecayManager
+from stellar_memory.event_logger import EventLogger
+from stellar_memory.llm_adapter import MemoryMiddleware, AnthropicAdapter
+from stellar_memory.vector_index import VectorIndex, BruteForceIndex, BallTreeIndex
+from stellar_memory.summarizer import MemorySummarizer
+from stellar_memory.adaptive_decay import AdaptiveDecayManager
+from stellar_memory.graph_analyzer import GraphAnalyzer, GraphStats, CentralityResult
+from stellar_memory.providers import ProviderRegistry
+from stellar_memory.storage import StorageBackend
+from stellar_memory.security.encryption import EncryptionManager
+from stellar_memory.security.access_control import AccessControl
+from stellar_memory.security.audit import SecurityAudit
+from stellar_memory.sync import MemorySyncManager
+from stellar_memory.emotion import EmotionAnalyzer
+from stellar_memory.stream import MemoryStream
+from stellar_memory.metacognition import Introspector, ConfidenceScorer
+from stellar_memory.multimodal import (
+    ContentTypeHandler, TextHandler, CodeHandler, JsonHandler,
+    get_handler, detect_content_type,
+)
+from stellar_memory.self_learning import PatternCollector, WeightOptimizer
+from stellar_memory.reasoning import MemoryReasoner, ContradictionDetector
+from stellar_memory.benchmark import StandardDataset, MemoryBenchmark
+
+try:
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("stellar-memory")
+except Exception:
+    __version__ = "1.0.0"
+
+__all__ = [
+    "StellarMemory",
+    "StellarConfig",
+    "MemoryFunctionConfig",
+    "ZoneConfig",
+    "EmbedderConfig",
+    "LLMConfig",
+    "TunerConfig",
+    "ConsolidationConfig",
+    "SessionConfig",
+    "EventConfig",
+    "NamespaceConfig",
+    "GraphConfig",
+    "DecayConfig",
+    "EventLoggerConfig",
+    "RecallConfig",
+    "VectorIndexConfig",
+    "SummarizationConfig",
+    "AdaptiveDecayConfig",
+    "GraphAnalyticsConfig",
+    "MemoryItem",
+    "ScoreBreakdown",
+    "ReorbitResult",
+    "MemoryStats",
+    "EvaluationResult",
+    "FeedbackRecord",
+    "ConsolidationResult",
+    "SessionInfo",
+    "MemorySnapshot",
+    "MemoryEdge",
+    "DecayResult",
+    "HealthStatus",
+    "SummarizationResult",
+    "EventBus",
+    "MemoryGraph",
+    "PersistentMemoryGraph",
+    "NamespaceManager",
+    "DecayManager",
+    "EventLogger",
+    "MemoryMiddleware",
+    "AnthropicAdapter",
+    "VectorIndex",
+    "BruteForceIndex",
+    "BallTreeIndex",
+    "MemorySummarizer",
+    "AdaptiveDecayManager",
+    "GraphAnalyzer",
+    "GraphStats",
+    "CentralityResult",
+    "ProviderRegistry",
+    "StorageConfig",
+    "SyncConfig",
+    "SecurityConfig",
+    "ConnectorConfig",
+    "DashboardConfig",
+    "ChangeEvent",
+    "AccessRole",
+    "IngestResult",
+    "ZoneDistribution",
+    "StorageBackend",
+    "EncryptionManager",
+    "AccessControl",
+    "SecurityAudit",
+    "MemorySyncManager",
+    # P7
+    "EmotionConfig",
+    "ServerConfig",
+    "EmotionVector",
+    "TimelineEntry",
+    "EmotionAnalyzer",
+    "MemoryStream",
+    # P9
+    "MetacognitionConfig",
+    "SelfLearningConfig",
+    "MultimodalConfig",
+    "ReasoningConfig",
+    "BenchmarkConfig",
+    "IntrospectionResult",
+    "ConfidentRecall",
+    "RecallLog",
+    "OptimizationReport",
+    "ReasoningResult",
+    "Contradiction",
+    "BenchmarkReport",
+    "Introspector",
+    "ConfidenceScorer",
+    "ContentTypeHandler",
+    "TextHandler",
+    "CodeHandler",
+    "JsonHandler",
+    "get_handler",
+    "detect_content_type",
+    "PatternCollector",
+    "WeightOptimizer",
+    "MemoryReasoner",
+    "ContradictionDetector",
+    "StandardDataset",
+    "MemoryBenchmark",
+]

stellar_memory/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Stellar Memory adapters for AI frameworks."""
+
+from stellar_memory.adapters.langchain import StellarLangChainMemory
+from stellar_memory.adapters.openai_plugin import OpenAIMemoryPlugin, STELLAR_TOOLS
+
+__all__ = ["StellarLangChainMemory", "OpenAIMemoryPlugin", "STELLAR_TOOLS"]

stellar_memory/adapters/langchain.py

@@ -0,0 +1,67 @@
+"""LangChain Memory interface adapter for Stellar Memory."""
+
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from stellar_memory.stellar import StellarMemory
+
+
+class StellarLangChainMemory:
+    """LangChain BaseMemory compatible adapter.
+
+    Usage::
+
+        from stellar_memory import StellarMemory
+        from stellar_memory.adapters.langchain import StellarLangChainMemory
+
+        memory = StellarMemory()
+        lc_memory = StellarLangChainMemory(memory)
+        # Use with LangChain ConversationChain
+    """
+
+    memory_key: str = "history"
+    input_key: str = "input"
+    output_key: str = "output"
+
+    def __init__(self, stellar_memory: StellarMemory,
+                 recall_limit: int = 5,
+                 memory_key: str = "history"):
+        self._memory = stellar_memory
+        self._recall_limit = recall_limit
+        self.memory_key = memory_key
+
+    @property
+    def memory_variables(self) -> list[str]:
+        return [self.memory_key]
+
+    def load_memory_variables(self, inputs: dict[str, Any]) -> dict[str, str]:
+        """Recall relevant memories based on input."""
+        query = inputs.get(self.input_key, "")
+        if not query:
+            return {self.memory_key: ""}
+
+        results = self._memory.recall(str(query), limit=self._recall_limit)
+        if not results:
+            return {self.memory_key: ""}
+
+        context = "\n".join(f"- {item.content}" for item in results)
+        return {self.memory_key: context}
+
+    def save_context(self, inputs: dict[str, Any],
+                     outputs: dict[str, str]) -> None:
+        """Store the conversation exchange as a memory."""
+        user_input = inputs.get(self.input_key, "")
+        assistant_output = outputs.get(self.output_key, "")
+        if user_input or assistant_output:
+            content = f"User: {user_input}\nAssistant: {assistant_output}"
+            self._memory.store(
+                content=content,
+                auto_evaluate=True,
+                metadata={"source": "langchain"},
+            )
+
+    def clear(self) -> None:
+        """No-op for persistent memory."""
+        pass

stellar_memory/adapters/openai_plugin.py

@@ -0,0 +1,125 @@
+"""OpenAI function calling schema for Stellar Memory."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from stellar_memory.stellar import StellarMemory
+
+
+STELLAR_TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "memory_store",
+            "description": "Store a new memory for future recall",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "content": {
+                        "type": "string",
+                        "description": "Memory content to store",
+                    },
+                    "importance": {
+                        "type": "number",
+                        "minimum": 0,
+                        "maximum": 1,
+                        "description": "Importance score 0.0-1.0",
+                    },
+                },
+                "required": ["content"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "memory_recall",
+            "description": "Search memories by query",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": "Search query",
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": 20,
+                        "description": "Max results",
+                    },
+                },
+                "required": ["query"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "memory_forget",
+            "description": "Delete a specific memory by ID",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "memory_id": {
+                        "type": "string",
+                        "description": "Memory UUID",
+                    },
+                },
+                "required": ["memory_id"],
+            },
+        },
+    },
+]
+
+
+class OpenAIMemoryPlugin:
+    """Plugin that handles OpenAI function call dispatch.
+
+    Usage::
+
+        from stellar_memory import StellarMemory
+        from stellar_memory.adapters.openai_plugin import OpenAIMemoryPlugin, STELLAR_TOOLS
+
+        memory = StellarMemory()
+        plugin = OpenAIMemoryPlugin(memory)
+        result = plugin.handle_call("memory_store", '{"content": "hello"}')
+    """
+
+    def __init__(self, stellar_memory: StellarMemory):
+        self._memory = stellar_memory
+
+    def get_tools(self) -> list[dict]:
+        """Return OpenAI tools schema."""
+        return STELLAR_TOOLS
+
+    def handle_call(self, function_name: str, arguments: str) -> str:
+        """Dispatch function call and return JSON result."""
+        args = json.loads(arguments)
+
+        if function_name == "memory_store":
+            item = self._memory.store(
+                content=args["content"],
+                importance=args.get("importance", 0.5),
+                auto_evaluate=True,
+            )
+            return json.dumps({"id": item.id, "zone": item.zone})
+
+        elif function_name == "memory_recall":
+            results = self._memory.recall(
+                args["query"], limit=args.get("limit", 5)
+            )
+            return json.dumps([{
+                "id": item.id, "content": item.content,
+                "zone": item.zone, "importance": item.arbitrary_importance,
+            } for item in results])
+
+        elif function_name == "memory_forget":
+            removed = self._memory.forget(args["memory_id"])
+            return json.dumps({"removed": removed})
+
+        else:
+            return json.dumps({"error": f"Unknown function: {function_name}"})

stellar_memory/adaptive_decay.py

@@ -0,0 +1,57 @@
+"""Adaptive decay - importance-based differential forgetting rates."""
+
+from __future__ import annotations
+
+import math
+
+from stellar_memory.config import DecayConfig
+from stellar_memory.models import MemoryItem
+
+SECONDS_PER_DAY = 86400
+
+
+class AdaptiveDecayManager:
+    """Manages importance-based differential decay rates."""
+
+    def __init__(self, decay_config: DecayConfig):
+        self._config = decay_config
+        self._adaptive = decay_config.adaptive
+
+    def effective_decay_days(self, item: MemoryItem) -> float:
+        """Calculate effective decay days based on importance.
+
+        Formula: base_days * (0.5 + importance * weight)
+        - importance=0.9, weight=1.0 → 30 * 1.4 = 42 days
+        - importance=0.3, weight=1.0 → 30 * 0.8 = 24 days
+        - importance=0.0, weight=1.0 → 30 * 0.5 = 15 days
+        """
+        base = self._config.decay_days
+        importance = item.arbitrary_importance
+        weight = self._adaptive.importance_weight
+        factor = 0.5 + importance * weight
+
+        if self._adaptive.zone_factor and item.zone > 0:
+            zone_multiplier = max(0.5, 2.0 - item.zone * 0.5)
+            factor *= zone_multiplier
+
+        return base * factor
+
+    def effective_forget_days(self, item: MemoryItem) -> float:
+        """Calculate effective auto-forget days."""
+        base = self._config.auto_forget_days
+        importance = item.arbitrary_importance
+        return base * (0.5 + importance * self._adaptive.importance_weight)
+
+    def apply_curve(self, elapsed_days: float, threshold_days: float) -> float:
+        """Apply decay curve. Returns 0.0 (no decay) to 1.0 (full decay)."""
+        if elapsed_days < threshold_days:
+            return 0.0
+        ratio = elapsed_days / threshold_days
+
+        if self._adaptive.decay_curve == "exponential":
+            return min(1.0, 1.0 - math.exp(-(ratio - 1.0)))
+        elif self._adaptive.decay_curve == "sigmoid":
+            x = (ratio - 1.0) * 5
+            return 1.0 / (1.0 + math.exp(-x))
+        else:  # linear
+            return min(1.0, ratio - 1.0)

stellar_memory/benchmark.py

@@ -0,0 +1,229 @@
+"""P9-F5: Memory Benchmark - quantitative performance measurement."""
+
+from __future__ import annotations
+
+import random
+import time
+from dataclasses import dataclass, field
+
+from stellar_memory.models import BenchmarkReport
+
+
+# Standard dataset categories with template content
+_CATEGORIES = ["daily", "work", "tech", "emotion", "code"]
+
+_TEMPLATES = {
+    "daily": [
+        "I had coffee with {name} at the cafe this morning",
+        "The weather today was {adj} and {adj2}",
+        "Went grocery shopping and bought {item} and {item2}",
+        "Watched a movie called {title} last night",
+        "Took a walk in the park near {place}",
+    ],
+    "work": [
+        "Meeting with {name} about the {topic} project",
+        "Deadline for {topic} report is next {day}",
+        "New team member {name} joined the {topic} team",
+        "Completed the {topic} feature implementation",
+        "Code review feedback on {topic} module was positive",
+    ],
+    "tech": [
+        "Learned about {tech} framework for building {topic}",
+        "{tech} version {ver} was released with new features",
+        "The {tech} documentation recommends using {pattern}",
+        "Benchmark shows {tech} is {num}x faster than alternatives",
+        "Migrated from {tech} to {tech2} for better performance",
+    ],
+    "emotion": [
+        "Felt really happy when {name} surprised me with {item}",
+        "Frustrated with the {topic} bug that took hours to fix",
+        "Excited about the upcoming {topic} conference",
+        "Anxious about the {topic} presentation tomorrow",
+        "Relieved that the {topic} deployment went smoothly",
+    ],
+    "code": [
+        "def calculate_{func}(data): return sum(data) / len(data)",
+        "class {cls}Manager: def __init__(self): self.items = []",
+        "async def fetch_{func}(url): return await client.get(url)",
+        "SELECT * FROM {table} WHERE status = 'active' ORDER BY created_at",
+        "const {func} = ({param}) => {{ return {param}.filter(x => x > 0) }}",
+    ],
+}
+
+_NAMES = ["Alice", "Bob", "Carol", "David", "Eve", "Frank", "Grace", "Henry"]
+_TOPICS = ["memory", "search", "auth", "deploy", "cache", "sync", "graph", "api"]
+_TECHS = ["React", "Python", "Rust", "Go", "Docker", "Redis", "PostgreSQL", "FastAPI"]
+_ITEMS = ["milk", "bread", "coffee", "laptop", "book", "headphones", "cake", "flowers"]
+_ADJS = ["sunny", "rainy", "cold", "warm", "windy", "cloudy", "beautiful", "foggy"]
+
+
+class StandardDataset:
+    """Reproducible benchmark dataset generator."""
+
+    SIZES = {
+        "small": (100, 20),
+        "standard": (1000, 100),
+        "large": (10000, 500),
+    }
+
+    def __init__(self, name: str = "standard", seed: int = 42):
+        self._name = name
+        self._seed = seed
+        self._rng = random.Random(seed)
+        count, query_count = self.SIZES.get(name, (1000, 100))
+        self._memory_count = count
+        self._query_count = query_count
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def generate_memories(self) -> list[dict]:
+        """Generate reproducible memory items."""
+        memories = []
+        for i in range(self._memory_count):
+            cat = _CATEGORIES[i % len(_CATEGORIES)]
+            template = self._rng.choice(_TEMPLATES[cat])
+            content = self._fill_template(template)
+            importance = self._rng.uniform(0.1, 0.9)
+            tags = [cat]
+            if cat == "code":
+                tags.append("code")
+            memories.append({
+                "content": content,
+                "importance": round(importance, 2),
+                "tags": tags,
+                "category": cat,
+                "id_hint": f"bench_{i}",
+            })
+        return memories
+
+    def generate_queries(self) -> list[dict]:
+        """Generate queries with expected category matches."""
+        queries = []
+        for i in range(self._query_count):
+            cat = _CATEGORIES[i % len(_CATEGORIES)]
+            keywords = {
+                "daily": ["coffee", "weather", "morning", "walk", "movie"],
+                "work": ["meeting", "deadline", "team", "project", "review"],
+                "tech": ["framework", "version", "documentation", "benchmark"],
+                "emotion": ["happy", "frustrated", "excited", "anxious", "relieved"],
+                "code": ["function", "class", "async", "SELECT", "const"],
+            }
+            query = self._rng.choice(keywords.get(cat, ["memory"]))
+            queries.append({
+                "query": query,
+                "expected_category": cat,
+            })
+        return queries
+
+    def _fill_template(self, template: str) -> str:
+        replacements = {
+            "{name}": self._rng.choice(_NAMES),
+            "{topic}": self._rng.choice(_TOPICS),
+            "{tech}": self._rng.choice(_TECHS),
+            "{tech2}": self._rng.choice(_TECHS),
+            "{item}": self._rng.choice(_ITEMS),
+            "{item2}": self._rng.choice(_ITEMS),
+            "{adj}": self._rng.choice(_ADJS),
+            "{adj2}": self._rng.choice(_ADJS),
+            "{place}": self._rng.choice(["river", "hill", "garden", "lake"]),
+            "{title}": self._rng.choice(["Inception", "Matrix", "Arrival", "Dune"]),
+            "{day}": self._rng.choice(["Monday", "Friday", "Wednesday"]),
+            "{ver}": f"{self._rng.randint(1,5)}.{self._rng.randint(0,9)}",
+            "{pattern}": self._rng.choice(["hooks", "middleware", "plugins"]),
+            "{num}": str(self._rng.randint(2, 10)),
+            "{func}": self._rng.choice(["average", "total", "count", "max"]),
+            "{cls}": self._rng.choice(["Data", "Task", "User", "Event"]),
+            "{table}": self._rng.choice(["users", "orders", "events", "logs"]),
+            "{param}": self._rng.choice(["items", "data", "values", "records"]),
+        }
+        result = template
+        for key, val in replacements.items():
+            result = result.replace(key, val, 1)
+        return result
+
+
+class MemoryBenchmark:
+    """Comprehensive memory system benchmark."""
+
+    def __init__(self, stellar):
+        self._stellar = stellar
+
+    def run(self, queries: int = 100, dataset: str = "standard",
+            seed: int = 42) -> BenchmarkReport:
+        ds = StandardDataset(dataset, seed)
+        memories = ds.generate_memories()
+        query_list = ds.generate_queries()[:queries]
+
+        # Measure store latency
+        store_times = []
+        stored_ids = []
+        for mem in memories:
+            t0 = time.perf_counter()
+            mid = self._stellar.store(
+                content=mem["content"],
+                importance=mem["importance"],
+                metadata={"category": mem["category"], "bench_id": mem["id_hint"]},
+            )
+            t1 = time.perf_counter()
+            store_times.append((t1 - t0) * 1000)
+            stored_ids.append(mid.id if hasattr(mid, 'id') else mid)
+
+        # Measure recall latency + accuracy
+        recall_times = []
+        hits_at_5 = 0
+        hits_at_10 = 0
+        precision_hits_5 = 0
+        for q in query_list:
+            t0 = time.perf_counter()
+            results = self._stellar.recall(q["query"], limit=10)
+            t1 = time.perf_counter()
+            recall_times.append((t1 - t0) * 1000)
+
+            # Check if any result matches expected category
+            top5 = results[:5]
+            top10 = results[:10]
+            cat = q["expected_category"]
+            if any(r.metadata.get("category") == cat for r in top5):
+                hits_at_5 += 1
+            if any(r.metadata.get("category") == cat for r in top10):
+                hits_at_10 += 1
+            precision_hits_5 += sum(
+                1 for r in top5 if r.metadata.get("category") == cat
+            )
+
+        # Measure reorbit latency
+        t0 = time.perf_counter()
+        self._stellar.reorbit()
+        t1 = time.perf_counter()
+        reorbit_ms = (t1 - t0) * 1000
+
+        # Stats
+        stats = self._stellar.stats()
+        import os
+        db_size = 0.0
+        if hasattr(self._stellar, 'config') and self._stellar.config.db_path != ":memory:":
+            try:
+                db_size = os.path.getsize(self._stellar.config.db_path) / (1024 * 1024)
+            except OSError:
+                pass
+
+        import sys
+        mem_usage = sys.getsizeof(self._stellar) / (1024 * 1024)
+
+        total_q = len(query_list) or 1
+        return BenchmarkReport(
+            recall_at_5=hits_at_5 / total_q,
+            recall_at_10=hits_at_10 / total_q,
+            precision_at_5=(precision_hits_5 / (total_q * 5)) if total_q else 0.0,
+            avg_store_latency_ms=sum(store_times) / len(store_times) if store_times else 0.0,
+            avg_recall_latency_ms=sum(recall_times) / len(recall_times) if recall_times else 0.0,
+            avg_reorbit_latency_ms=reorbit_ms,
+            memory_usage_mb=round(mem_usage, 2),
+            db_size_mb=round(db_size, 2),
+            total_memories=stats.total_memories,
+            zone_distribution=dict(stats.zone_counts),
+            dataset_name=dataset,
+            queries_run=total_q,
+        )