voltmem 0.1.0__py3-none-any.whl

voltmem/__init__.py

@@ -0,0 +1,68 @@
+"""
+VoltMem — Volatility-Adjusted Persistent Memory Layer
+======================================================
+
+A pluggable memory layer for LLM applications and any system that needs
+persistent context with principled staleness handling.
+
+Core idea: not all memories age at the same rate. Stable knowledge
+(personality traits, core preferences) should be protected strongly
+against overwriting. Volatile knowledge (current tasks, emotional context,
+location) should be held loosely and updated readily.
+
+Quick start:
+    from voltmem import MemoryLayer
+
+    mem = MemoryLayer("my_app.db")
+
+    mem.write("User prefers direct communication", domain="core_preference")
+    mem.write("User is currently job hunting", domain="current_project")
+
+    # New observation — may or may not update existing memory
+    result = mem.observe(
+        content="User mentioned they accepted a job offer",
+        domain="current_project",
+        mismatch_magnitude=0.8,
+        source="explicit_statement",
+    )
+    print(result.action)  # "audited" — volatile domain, high mismatch → updated
+
+    # Retrieve relevant memories for a query
+    results = mem.retrieve("career and work context")
+    for item, score in zip(results.items, results.scores):
+        print(f"[{score:.2f}] {item.content}")
+"""
+
+from .memory import MemoryLayer, WriteResult, RetrieveResult
+from .client import Memory, create_memory
+from .domains import MemoryItem, DOMAIN_VOLATILITY, SOURCE_RELIABILITY
+from .embeddings import EmbeddingSimilarity
+from .extract import HeuristicExtractor, LLMExtractor, HeuristicFactExtractor, LLMFactExtractor
+from .scoring import (
+    escalation_score,
+    retrieval_score,
+    staleness,
+    protection_weight,
+)
+
+__all__ = [
+    "Memory",
+    "create_memory",
+    "MemoryLayer",
+    "WriteResult",
+    "RetrieveResult",
+    "MemoryItem",
+    "DOMAIN_VOLATILITY",
+    "SOURCE_RELIABILITY",
+    "EmbeddingSimilarity",
+    "HeuristicExtractor",
+    "LLMExtractor",
+    "HeuristicFactExtractor",
+    "LLMFactExtractor",
+    "escalation_score",
+    "retrieval_score",
+    "staleness",
+    "protection_weight",
+]
+
+__version__ = "0.1.0"

voltmem/client.py

@@ -0,0 +1,239 @@
+"""
+Product-facing API — Mem0-shaped surface over MemoryLayer.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable, Optional, Union
+
+from .embeddings import EmbeddingSimilarity
+from .extract import HeuristicFactExtractor, LLMFactExtractor
+from .memory import MemoryLayer, RetrieveResult, WriteResult
+
+Message = dict[str, str]
+AddInput = Union[str, Message, list[Message]]
+
+
+def create_memory(
+    db_path: str | Path = "voltmem.db",
+    user_id: str = "default",
+    *,
+    embeddings: bool = True,
+    verbose: bool = False,
+    llm_extract: bool = False,
+    llm_domain: bool = False,
+    **kwargs: Any,
+) -> "Memory":
+    """Create a production-ready memory instance with sensible defaults.
+
+    Auto-detects an embedding backend when ``embeddings=True``
+    (sentence-transformers → Ollama → offline hashing fallback).
+
+    Parameters
+    ----------
+    llm_extract : bool
+        Use Ollama to extract atomic facts from conversation message lists.
+    llm_domain : bool
+        Use Ollama for domain classification and contradiction detection
+        inside ``remember()`` (passed to ``MemoryLayer`` as ``extractor``).
+    """
+    similarity_fn = kwargs.pop("similarity_fn", None)
+    if embeddings and similarity_fn is None:
+        similarity_fn = EmbeddingSimilarity(verbose=verbose)
+
+    fact_extractor = LLMFactExtractor() if llm_extract else HeuristicFactExtractor()
+
+    layer_kwargs = dict(kwargs)
+    if llm_domain:
+        from .extract import LLMExtractor
+        layer_kwargs["extractor"] = LLMExtractor()
+
+    return Memory(
+        user_id=user_id,
+        db_path=db_path,
+        similarity_fn=similarity_fn,
+        fact_extractor=fact_extractor,
+        **layer_kwargs,
+    )
+
+
+class Memory:
+    """Current-truth memory for LLM agents.
+
+    Familiar ``add`` / ``search`` surface; VoltMem volatility engine underneath.
+    Volatile facts update; stable facts resist corruption; stale volatile memories
+    rank lower at retrieval.
+    """
+
+    def __init__(
+        self,
+        user_id: str = "default",
+        db_path: str | Path = ":memory:",
+        *,
+        layer: Optional[MemoryLayer] = None,
+        similarity_fn: Optional[Callable[[str, str], float]] = None,
+        fact_extractor: Optional[HeuristicFactExtractor] = None,
+        **kwargs: Any,
+    ):
+        self.user_id = user_id
+        self._fact_extractor = fact_extractor or HeuristicFactExtractor()
+        if layer is not None:
+            self._layer = (
+                layer if layer.namespace == user_id else layer.for_user(user_id)
+            )
+            self._owns_layer = False
+        else:
+            self._layer = MemoryLayer(
+                db_path,
+                similarity_fn=similarity_fn,
+                namespace=user_id,
+                **kwargs,
+            )
+            self._owns_layer = True
+
+    @property
+    def layer(self) -> MemoryLayer:
+        """Low-level ``MemoryLayer`` for advanced control."""
+        return self._layer
+
+    def add(
+        self,
+        data: AddInput,
+        *,
+        source: str = "explicit_statement",
+        extract: bool | None = None,
+    ) -> Union[dict[str, Any], list[dict[str, Any]]]:
+        """Store a fact or conversation turn(s).
+
+        Accepts a plain string, one message dict ``{"role": ..., "content": ...}``,
+        or a list of message dicts. For message lists, ``extract=True`` (default)
+        pulls atomic user facts before storing.
+        """
+        if isinstance(data, str):
+            return self._format_write(self._layer.remember(data, source=source))
+        if isinstance(data, dict):
+            return self._add_message(data, source=source)
+        if isinstance(data, list):
+            if not data:
+                return []
+            do_extract = extract if extract is not None else True
+            if do_extract:
+                return self._add_extracted_facts(data, source=source)
+            out = []
+            for msg in data:
+                if not isinstance(msg, dict):
+                    raise TypeError("each message must be a dict with role/content")
+                result = self._add_message(msg, source=source)
+                if result is not None:
+                    out.append(result)
+            return out
+        raise TypeError("add() expects str, message dict, or list of message dicts")
+
+    def search(
+        self,
+        query: str,
+        *,
+        limit: int = 5,
+        min_score: float = 0.0,
+    ) -> list[dict[str, Any]]:
+        """Retrieve current-truth memories ranked by relevance and freshness."""
+        result = self._layer.retrieve(
+            query, top_k=limit, min_score=min_score)
+        return self._format_retrieve(result)
+
+    def get_all(self) -> list[dict[str, Any]]:
+        """Return all active memories for this user."""
+        return [
+            self._format_item(item)
+            for item in self._layer._active()
+        ]
+
+    def get(self, memory_id: str) -> Optional[dict[str, Any]]:
+        """Return one memory by id, or None."""
+        info = self._layer.inspect(memory_id)
+        if info.get("error"):
+            return None
+        return info
+
+    def delete(self, memory_id: str) -> bool:
+        """Remove a memory by id. Returns True if deleted."""
+        item = self._layer._store.get(memory_id)
+        if not item or item.namespace != self.user_id:
+            return False
+        self._layer._store.delete(memory_id, namespace=self.user_id)
+        return True
+
+    def clear(self) -> None:
+        """Remove all memories for this user."""
+        self._layer.clear()
+
+    def summary(self) -> dict[str, Any]:
+        return self._layer.summary()
+
+    def close(self) -> None:
+        if self._owns_layer:
+            self._layer.close()
+
+    def __enter__(self) -> "Memory":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    # ── helpers ───────────────────────────────────────────────────────────────
+
+    def _add_extracted_facts(
+        self, messages: list[Message], *, source: str
+    ) -> list[dict[str, Any]]:
+        facts = self._fact_extractor.extract(messages)
+        out: list[dict[str, Any]] = []
+        for fact in facts:
+            src = fact.source or source
+            if fact.domain:
+                result = self._layer.remember(
+                    fact.content, domain=fact.domain, source=src)
+            else:
+                result = self._layer.remember(fact.content, source=src)
+            out.append(self._format_write(result))
+        return out
+
+    def _add_message(
+        self, msg: Message, *, source: str
+    ) -> Optional[dict[str, Any]]:
+        role = msg.get("role", "user")
+        content = str(msg.get("content", "")).strip()
+        if not content:
+            return None
+        src = source if role == "user" else "assistant_response"
+        return self._format_write(self._layer.remember(content, source=src))
+
+    @staticmethod
+    def _format_write(result: WriteResult) -> dict[str, Any]:
+        item = result.item
+        return {
+            "id": item.id,
+            "memory": item.content,
+            "action": result.action,
+            "domain": item.domain,
+            "detail": result.detail,
+        }
+
+    @staticmethod
+    def _format_item(item: Any) -> dict[str, Any]:
+        return {
+            "id": item.id,
+            "memory": item.content,
+            "domain": item.domain,
+            "source": item.source,
+            "created_at": item.created_at,
+            "last_confirmed_at": item.last_confirmed_at,
+        }
+
+    def _format_retrieve(self, result: RetrieveResult) -> list[dict[str, Any]]:
+        out = []
+        for item, score in zip(result.items, result.scores):
+            row = self._format_item(item)
+            row["score"] = round(score, 4)
+            out.append(row)
+        return out

voltmem/domains.py

@@ -0,0 +1,102 @@
+"""
+Domain volatility priors.
+
+V_d is the expected rate of change for a given memory domain.
+Higher = more volatile = weaker protection = lower mismatch threshold
+to trigger an audit/update.
+
+Scale: 0.0 (never changes) → 1.0 (changes very fast).
+These are defaults; callers can override per-item or register custom domains.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+# ── built-in domain priors ────────────────────────────────────────────────────
+
+DOMAIN_VOLATILITY: dict[str, float] = {
+    # Slow-changing — protect hard
+    "personality_trait":    0.05,   # how the user fundamentally operates
+    "core_preference":      0.08,   # deep aesthetic / communication preferences
+    "biographical":         0.10,   # birthplace, native language, background
+    "long_term_goal":       0.15,   # career direction, life goals
+
+    # Medium — moderate protection
+    "professional_context": 0.30,   # job, company, role (changes every few years)
+    "skill":                0.25,   # competencies the user has
+    "relationship":         0.35,   # people they work with / are close to
+
+    # Fast-changing — hold loosely
+    "current_project":      0.55,   # what they're working on right now
+    "stated_preference":    0.45,   # preferences stated in this period
+    "opinion":              0.50,   # views that may shift
+    "location":             0.60,   # where they are / living situation
+    "emotional_context":    0.80,   # current mood, stress level
+    "current_task":         0.90,   # immediate to-do
+    "transient_fact":       0.95,   # anything clearly moment-specific
+}
+
+# Domains that usually hold a single "current truth" slot (mood, city, task).
+# remember() uses a lower in-slot linking threshold for these.
+SLOT_DOMAINS: frozenset[str] = frozenset({
+    "emotional_context",
+    "location",
+    "current_task",
+    "transient_fact",
+})
+
+# Related domains searched together when linking a new statement to existing
+# memories (e.g. paraphrased prefs split across classifiers).
+DOMAIN_SIBLINGS: dict[str, frozenset[str]] = {
+    "core_preference": frozenset({"core_preference", "stated_preference"}),
+    "stated_preference": frozenset({"core_preference", "stated_preference"}),
+}
+
+# Minimum semantic overlap to link a lone item in a volatile slot when the
+# volatility-scaled threshold is not quite met.
+SLOT_LINK_FLOOR: float = 0.30
+
+# Source reliability weights (R_t in the escalation equation)
+# Higher = more trustworthy signal for both write and mismatch detection
+SOURCE_RELIABILITY: dict[str, float] = {
+    "explicit_statement":   1.0,    # user directly stated it
+    "repeated_confirmation":1.2,    # confirmed across multiple turns
+    "strong_inference":     0.7,    # clearly implied
+    "weak_inference":       0.4,    # loosely inferred from behaviour
+    "system_generated":     0.3,    # injected by the wrapping system
+}
+
+
+@dataclass
+class MemoryItem:
+    """A single unit of persistent memory."""
+    id:               str
+    content:          str                    # the actual stored fact/preference
+    domain:           str                    # one of DOMAIN_VOLATILITY keys
+    source:           str                    # one of SOURCE_RELIABILITY keys
+    namespace:        str   = "default"      # tenant/user isolation key
+
+    # Equation terms — updated over time
+    repetition_count: int   = 1             # C: how many times confirmed
+    volatility_ema:   float = -1.0          # V_d EMA; -1 means use domain prior
+    mismatch_count:   int   = 0             # cumulative mismatch events
+    goal_delta:       float = 0.0           # G_t: positive = helps goal, neg = hurts
+
+    # Timestamps (unix seconds)
+    created_at:       float = 0.0
+    last_confirmed_at:float = 0.0
+    last_audited_at:  float = 0.0
+
+    # Metadata
+    tags:             list[str] = field(default_factory=list)
+    superseded_by:    Optional[str] = None  # id of item that replaced this one
+
+    @property
+    def is_active(self) -> bool:
+        return self.superseded_by is None
+
+    @property
+    def effective_volatility(self) -> float:
+        if self.volatility_ema >= 0:
+            return self.volatility_ema
+        return DOMAIN_VOLATILITY.get(self.domain, 0.5)

voltmem/embeddings.py

@@ -0,0 +1,161 @@
+"""
+Pluggable embedding-based similarity for VoltMem retrieval.
+==========================================================
+
+VoltMem's contribution is the volatility/freshness weighting applied *on top of*
+a semantic-similarity signal. The core library ships with a dependency-free
+keyword scorer; this module provides a drop-in embedding scorer for real semantic
+retrieval:
+
+    from voltmem import MemoryLayer
+    from voltmem.embeddings import EmbeddingSimilarity
+
+    sim = EmbeddingSimilarity()            # auto-detects the best available backend
+    mem = MemoryLayer(":memory:", similarity_fn=sim)
+
+Backend auto-detection (first that works wins), overridable via backend=...:
+
+  1. "sentence-transformers"  — local, high quality (all-MiniLM-L6-v2 by default)
+  2. "ollama"                 — local daemon at http://localhost:11434
+                               (nomic-embed-text by default)
+  3. "hashing"               — deterministic, dependency-free fallback so the
+                               library and benchmarks ALWAYS run offline. Lower
+                               quality (bag-of-hashed-tokens), but reproducible.
+
+The returned callable maps a (query, content) pair to a similarity in [0, 1]
+(cosine similarity rescaled from [-1, 1]). Embeddings are cached per text.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+import time
+import urllib.error
+import urllib.request
+from typing import Callable, Optional
+
+
+def _cosine(a: list[float], b: list[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    if na == 0.0 or nb == 0.0:
+        return 0.0
+    return dot / (na * nb)
+
+
+class EmbeddingSimilarity:
+    """Callable (query, content) -> similarity in [0, 1] backed by embeddings."""
+
+    def __init__(
+        self,
+        backend: Optional[str] = None,
+        model: Optional[str] = None,
+        ollama_url: str = "http://localhost:11434",
+        dim: int = 256,
+        verbose: bool = False,
+    ):
+        self.model = model
+        self.ollama_url = ollama_url.rstrip("/")
+        self.dim = dim
+        self.verbose = verbose
+        self._cache: dict[str, list[float]] = {}
+        self._embed_fn: Callable[[str], list[float]]
+
+        # Try backends in order; a backend counts as usable only if it can
+        # actually produce an embedding (a running Ollama daemon with no embed
+        # model pulled, for example, must NOT win — it 404s on first use).
+        candidates = [backend] if backend else [
+            "sentence-transformers", "ollama", "hashing"]
+        errors = []
+        user_model = model
+        for cand in candidates:
+            try:
+                self.model = user_model   # reset per attempt; don't leak labels
+                fn = self._make_backend(cand)
+                _ = fn("voltmem backend probe")   # trial embed; raises if broken
+                self.backend = cand
+                self._embed_fn = fn
+                if self.verbose:
+                    print(f"[EmbeddingSimilarity] using backend={cand} "
+                          f"model={self.model}")
+                return
+            except Exception as e:                 # noqa: BLE001
+                errors.append(f"{cand}: {type(e).__name__}: {e}")
+                if self.verbose:
+                    print(f"[EmbeddingSimilarity] backend {cand} unavailable "
+                          f"({type(e).__name__})")
+        # hashing never fails, so we only get here if an explicit backend was bad
+        raise RuntimeError("No usable embedding backend. Tried:\n  " +
+                           "\n  ".join(errors))
+
+    def _make_backend(self, backend: str) -> Callable[[str], list[float]]:
+        if backend == "sentence-transformers":
+            from sentence_transformers import SentenceTransformer
+            model_name = self.model or "all-MiniLM-L6-v2"
+            st = SentenceTransformer(model_name)
+            self.model = model_name
+
+            def embed(text: str) -> list[float]:
+                return [float(x) for x in st.encode(text, normalize_embeddings=False)]
+
+            return embed
+
+        if backend == "ollama":
+            model_name = self.model or "nomic-embed-text"
+            self.model = model_name
+            url = f"{self.ollama_url}/api/embeddings"
+
+            def embed(text: str) -> list[float]:
+                payload = json.dumps({"model": model_name, "prompt": text}).encode()
+                req = urllib.request.Request(
+                    url, data=payload, headers={"Content-Type": "application/json"})
+                last_err: Exception | None = None
+                for attempt in range(5):
+                    try:
+                        with urllib.request.urlopen(req, timeout=60) as resp:
+                            data = json.loads(resp.read().decode())
+                        return [float(x) for x in data["embedding"]]
+                    except urllib.error.HTTPError as e:
+                        last_err = e
+                        if e.code in (429, 500, 502, 503) and attempt < 4:
+                            time.sleep(2 ** attempt)
+                            continue
+                        raise
+                raise last_err  # type: ignore[misc]
+
+            return embed
+
+        # ── hashing fallback ──────────────────────────────────────────────────
+        self.model = self.model or f"hashing-{self.dim}"
+
+        def embed(text: str) -> list[float]:
+            vec = [0.0] * self.dim
+            tokens = text.lower().split()
+            for tok in tokens:
+                h = int(hashlib.md5(tok.encode()).hexdigest(), 16)
+                idx = h % self.dim
+                sign = 1.0 if (h >> 8) & 1 else -1.0
+                vec[idx] += sign
+            return vec
+
+        return embed
+
+    # ── public API ────────────────────────────────────────────────────────────
+    def embed(self, text: str) -> list[float]:
+        if text not in self._cache:
+            self._cache[text] = self._embed_fn(text)
+        return self._cache[text]
+
+    def __call__(self, query: str, content: str) -> float:
+        if not query or not content:
+            return 0.0
+        cos = _cosine(self.embed(query), self.embed(content))
+        # Return clamped raw cosine. We deliberately do NOT rescale [-1,1]->[0,1]:
+        # that compresses the dynamic range and collapses the gap between
+        # "related" and "unrelated" (which breaks similarity thresholds used by
+        # remember()). Clamping negatives to 0 is fine for retrieval and matching.
+        return max(0.0, min(1.0, cos))