mnemos-continuity 0.2.0__py3-none-any.whl

mnemos/__init__.py

@@ -0,0 +1,63 @@
+"""
+Mnemos: Living Memory Architecture for Autonomous AI Agents
+
+Memory is not a feature of the agent. Memory IS the agent.
+
+Mnemos provides a cognitive memory layer that sits beneath agent platforms
+like OpenClaw, replacing passive note-storage with active, living memory
+that encodes at varying depths, forgets naturally, predicts what it'll need,
+and changes its memories every time it touches them.
+
+Core features (always active):
+- Engrams with dual-trace model (strength/stability/accessibility)
+- Typed connections (supports, contradicts, causes, elaborates, etc.)
+- Confidence scoring on every memory
+- Reconsolidation (every retrieval updates the memory)
+- Decay + softening (LLM-mediated lossy compression)
+- Emotional state (6 dimensions influencing retrieval)
+- Beliefs with confidence tracking and revision history
+- Narrative identity generation
+- OpenClaw-compatible file export
+
+Advanced modules (opt-in):
+- Working memory with soft attention gradient
+- Schemas and schema-based encoding
+- Attention-gated encoding
+- Predictive retrieval
+- Interference modeling
+- Prospective memory (intentions with triggers)
+- Metamemory (knowing what you know)
+- External multi-model observer
+- Multi-agent federation
+"""
+
+# Read from installed package metadata so there is exactly one source of
+# truth. Hardcoding it here meant this said 0.1.0 while the distribution
+# said 0.2.0, and nothing failed — a released package can misreport its own
+# version to every user and to every bug report, and PyPI versions cannot be
+# replaced once uploaded. The fallback covers running from a source tree
+# that was never installed.
+try:  # pragma: no cover - trivial branch
+    from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+    __version__ = _pkg_version("mnemos-continuity")
+except (ImportError, PackageNotFoundError):  # pragma: no cover
+    __version__ = "0.0.0+unknown"
+
+# Public API
+from .store.sqlite_store import EngramStore
+from .encoding.encoder import Encoder
+from .retrieval.reactive import ReactiveRetriever
+from .consolidation.daemon import ConsolidationDaemon
+from .bridge import MnemosBridge
+from .config.loader import load_config, save_config
+
+__all__ = [
+    "EngramStore",
+    "Encoder",
+    "ReactiveRetriever",
+    "ConsolidationDaemon",
+    "MnemosBridge",
+    "load_config",
+    "save_config",
+]

mnemos/advanced/__init__.py

@@ -0,0 +1,43 @@
+"""Advanced modules for Mnemos (opt-in).
+
+These modules extend the core memory system with more sophisticated
+cognitive capabilities. Each is independently toggleable via configuration.
+
+Modules:
+- working_memory: Soft attention gradient working memory (capacity ~7 items)
+- schema: Cognitive schemas for structured encoding and retrieval
+- attention_gate: Attention-gated encoding (filter what gets encoded)
+- schema_matcher: Match incoming content against active schemas
+- predictive: Predictive retrieval (pre-fetch likely-needed memories)
+- spreading_activation: Activation spreading through connection graph
+- interference: Interference modeling (similar memories competing)
+- intention: Prospective memory (future-directed intentions with triggers)
+- intention_sweep: Periodic check for triggered intentions
+- metamemory: Knowing what you know (and what you don't)
+- metamemory_update: Update metamemory state after cognitive events
+- schema_maintenance: Schema evolution and pruning
+- interference_resolution: Resolve interference between competing memories
+- observer: External multi-model observer for calibration
+- dreaming: Dream-like consolidation for creative connection discovery
+"""
+
+# All imports are lazy — modules are only loaded when enabled in config.
+# This avoids import-time costs for disabled features.
+
+__all__ = [
+    "working_memory",
+    "schema",
+    "attention_gate",
+    "schema_matcher",
+    "predictive",
+    "spreading_activation",
+    "interference",
+    "intention",
+    "intention_sweep",
+    "metamemory",
+    "metamemory_update",
+    "schema_maintenance",
+    "interference_resolution",
+    "observer",
+    "dreaming",
+]

mnemos/advanced/attention_gate.py

@@ -0,0 +1,48 @@
+"""
+Attention gate: determines encoding depth based on salience signals.
+
+Not everything deserves deep encoding. The attention gate evaluates
+incoming content against multiple salience signals to determine how
+deeply it should be encoded:
+
+Signals:
+- Novelty: how different from existing memories
+- Emotional salience: emotional state amplification
+- Schema relevance: matches an active schema
+- Goal relevance: relates to current agent goals
+- WM load: cognitive load affects available encoding resources
+- User emphasis: explicit markers of importance
+
+Output: EncodingDepth (shallow | moderate | deep | elaborative)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..core.types import EncodingDepth
+
+
+def gate_attention(
+    content: str,
+    tags: list[str],
+    emotional_state: dict[str, float] | None = None,
+    wm_load: float = 0.5,
+    active_schemas: list[str] | None = None,
+    agent_goals: list[str] | None = None,
+) -> str:
+    """Determine encoding depth for incoming content.
+
+    Args:
+        content: The content to evaluate.
+        tags: Tags extracted from the content.
+        emotional_state: Current emotional state dimensions.
+        wm_load: Current working memory load (0-1+).
+        active_schemas: Currently active schema IDs.
+        agent_goals: Currently active agent goal descriptions.
+
+    Returns:
+        EncodingDepth value (shallow, moderate, deep, or elaborative).
+    """
+    # TODO: Implementation
+    return EncodingDepth.MODERATE

mnemos/advanced/dreaming.py

@@ -0,0 +1,56 @@
+"""
+Dreaming: creative connection discovery through free association.
+
+Dream consolidation uses LLM-mediated free association to find
+non-obvious connections between memories. Unlike regular connection
+discovery (which uses embedding similarity), dreaming explores
+metaphorical, analogical, and creative relationships.
+
+Dream-generated connections have source='dream' and often produce
+ANALOGOUS_TO connections that bridge different domains.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..store.sqlite_store import EngramStore
+
+
+def run_dream_cycle(
+    store: EngramStore,
+    llm_client: Any,
+    agent_id: str = "default",
+    seed_count: int = 3,
+) -> dict[str, Any]:
+    """Run a dream cycle for creative connection discovery.
+
+    Process:
+    1. Select random seed engrams from different domains
+    2. Ask the LLM to free-associate between them
+    3. Create ANALOGOUS_TO connections for valid associations
+    4. Generate dream-source engrams for novel insights
+
+    Args:
+        store: The engram store for reading and creating memories.
+        llm_client: LLM client for free association generation.
+        agent_id: Which agent is dreaming.
+        seed_count: Number of random seed engrams to select.
+
+    Returns:
+        Statistics dict:
+        {
+            "seeds_selected": int,
+            "associations_generated": int,
+            "connections_created": int,
+            "dream_engrams_created": int,
+        }
+    """
+    # TODO: Implementation
+    return {
+        "seeds_selected": 0,
+        "associations_generated": 0,
+        "connections_created": 0,
+        "dream_engrams_created": 0,
+    }

mnemos/advanced/intention.py

@@ -0,0 +1,82 @@
+"""
+Prospective memory: future-directed intentions with triggers.
+
+Intentions are memories about things the agent needs to do in the future.
+Each intention has trigger conditions that, when met, surface the intention
+to the agent's attention.
+
+Example:
+    "When the user mentions the project deadline, remind them about
+     the code review they requested."
+
+Intentions are stored as engrams with kind=PROSPECTIVE and linked
+to an Intention object that defines trigger conditions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class TriggerCondition:
+    """A condition that activates a prospective memory."""
+
+    type: str = "keyword"
+    """keyword | temporal | context | emotional"""
+
+    value: str = ""
+    """The trigger value (keyword, ISO timestamp, context pattern, emotion threshold)."""
+
+    met: bool = False
+    """Whether this condition has been met."""
+
+
+@dataclass
+class Intention:
+    """A future-directed memory with trigger conditions.
+
+    When all trigger conditions are met, the intention surfaces
+    to the agent's working memory.
+    """
+
+    id: str = ""
+    engram_id: str = ""
+    """The prospective engram this intention is linked to."""
+
+    description: str = ""
+    action: str = ""
+    triggers: list[TriggerCondition] = field(default_factory=list)
+    priority: float = 0.5
+    created_at: str = ""
+    fulfilled_at: str | None = None
+    expired: bool = False
+
+    def check_triggers(self, context: dict[str, Any]) -> bool:
+        """Check if all trigger conditions are met.
+
+        Args:
+            context: Current context dict with keys matching trigger types.
+
+        Returns:
+            True if all triggers are satisfied.
+        """
+        # TODO: Implementation
+        return False
+
+    def fulfill(self) -> None:
+        """Mark this intention as fulfilled."""
+        # TODO: Implementation
+        pass
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize intention to dict."""
+        # TODO: Implementation
+        return {}
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Intention:
+        """Deserialize intention from dict."""
+        # TODO: Implementation
+        return cls()

mnemos/advanced/intention_sweep.py

@@ -0,0 +1,35 @@
+"""
+Intention sweep: periodic check for triggered intentions.
+
+Runs during consolidation or at session start to check all active
+intentions against the current context. Triggered intentions are
+surfaced to the agent's working memory or prompt.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .intention import Intention
+
+if TYPE_CHECKING:
+    from ..store.sqlite_store import EngramStore
+
+
+def sweep_intentions(
+    store: EngramStore,
+    context: dict[str, Any],
+    agent_id: str = "default",
+) -> list[Intention]:
+    """Check all active intentions against current context.
+
+    Args:
+        store: The engram store for loading intentions.
+        context: Current context (keywords, time, emotional state, etc.).
+        agent_id: Which agent's intentions to check.
+
+    Returns:
+        List of triggered intentions that should be surfaced.
+    """
+    # TODO: Implementation
+    return []

mnemos/advanced/interference.py

@@ -0,0 +1,53 @@
+"""
+Interference modeling: similar memories competing for retrieval.
+
+When multiple similar memories exist, they can interfere with each other:
+- Proactive interference: old memories block retrieval of new ones
+- Retroactive interference: new memories make old ones harder to access
+
+Interference reduces accessibility of competing memories and can trigger
+interference resolution during consolidation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..core.engram import Engram
+    from ..store.sqlite_store import EngramStore
+
+
+def calculate_interference(
+    target: Engram,
+    competitors: list[Engram],
+) -> float:
+    """Calculate interference level for a target engram.
+
+    Args:
+        target: The engram being retrieved.
+        competitors: Similar engrams that may interfere.
+
+    Returns:
+        Interference level (0.0 = no interference, 1.0 = maximum).
+    """
+    # TODO: Implementation
+    return 0.0
+
+
+def apply_interference(
+    store: EngramStore,
+    target_id: str,
+    competitor_ids: list[str],
+    interference_level: float,
+) -> None:
+    """Apply interference effects to competing engrams.
+
+    Args:
+        store: The engram store.
+        target_id: The successfully retrieved engram.
+        competitor_ids: Engrams that competed with the target.
+        interference_level: The calculated interference level.
+    """
+    # TODO: Implementation
+    pass

mnemos/advanced/interference_resolution.py

@@ -0,0 +1,48 @@
+"""
+Interference resolution: resolve competition between similar memories.
+
+Runs during consolidation to handle cases where multiple similar memories
+interfere with each other. Resolution strategies:
+
+1. Merge: combine highly similar memories into a single stronger one
+2. Differentiate: add distinguishing connections to reduce confusion
+3. Suppress: lower accessibility of the weaker competitor
+4. Preserve: keep both with explicit contradiction/elaboration connections
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..store.sqlite_store import EngramStore
+
+
+def resolve_interference(
+    store: EngramStore,
+    config: dict[str, Any],
+) -> dict[str, Any]:
+    """Find and resolve interference between competing memories.
+
+    Args:
+        store: The engram store for finding and updating engrams.
+        config: Configuration for interference thresholds.
+
+    Returns:
+        Statistics dict:
+        {
+            "pairs_evaluated": int,
+            "merged": int,
+            "differentiated": int,
+            "suppressed": int,
+            "preserved": int,
+        }
+    """
+    # TODO: Implementation
+    return {
+        "pairs_evaluated": 0,
+        "merged": 0,
+        "differentiated": 0,
+        "suppressed": 0,
+        "preserved": 0,
+    }