agentic-memory-ai 0.1.0__py3-none-any.whl

agentic_memory/__init__.py

@@ -0,0 +1,49 @@
+"""agentic-memory: Framework-agnostic memory layer for AI agents."""
+
+from .memory import AgentMemory
+from .decay import DecayEngine
+from .types import (
+    MemoryEntry,
+    MemoryType,
+    ImportanceLevel,
+    DecayPolicy,
+    DecayConfig,
+    DecayTypeConfig,
+    RetrievalQuery,
+    RetrievalResult,
+    ConflictResult,
+    ConflictAction,
+    Checkpoint,
+    TaskNode,
+    TaskStatus,
+)
+from .store import LocalStore, FileStore
+from .retrieval import BuiltinEmbedder, MultiSignalRetriever, ConflictDetector
+from .utils import cosine_similarity, generate_id
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentMemory",
+    "DecayEngine",
+    "MemoryEntry",
+    "MemoryType",
+    "ImportanceLevel",
+    "DecayPolicy",
+    "DecayConfig",
+    "DecayTypeConfig",
+    "RetrievalQuery",
+    "RetrievalResult",
+    "ConflictResult",
+    "ConflictAction",
+    "Checkpoint",
+    "TaskNode",
+    "TaskStatus",
+    "LocalStore",
+    "FileStore",
+    "BuiltinEmbedder",
+    "MultiSignalRetriever",
+    "ConflictDetector",
+    "cosine_similarity",
+    "generate_id",
+]

agentic_memory/adapters/__init__.py

@@ -0,0 +1,4 @@
+from .openai import OpenAIEmbedder
+from .voyageai import VoyageEmbedder
+
+__all__ = ["OpenAIEmbedder", "VoyageEmbedder"]

agentic_memory/adapters/openai.py

@@ -0,0 +1,70 @@
+"""
+OpenAI embedder adapter.
+Requires: pip install httpx (or aiohttp)
+
+Usage:
+    from agentic_memory import AgentMemory
+    from agentic_memory.adapters import OpenAIEmbedder
+
+    memory = AgentMemory(
+        embedder=OpenAIEmbedder(api_key="sk-...")
+    )
+"""
+
+from __future__ import annotations
+
+import json
+from urllib.request import Request, urlopen
+from typing import Optional
+
+
+class OpenAIEmbedder:
+    def __init__(
+        self,
+        api_key: str,
+        model: str = "text-embedding-3-small",
+        dim: int = 1536,
+        base_url: str = "https://api.openai.com/v1",
+    ) -> None:
+        self._api_key = api_key
+        self._model = model
+        self._dim = dim
+        self._base_url = base_url
+
+    def dimensions(self) -> int:
+        return self._dim
+
+    async def embed(self, text: str) -> list[float]:
+        result = self._call([text])
+        return result[0]
+
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        if not texts:
+            return []
+        return self._call(texts)
+
+    def _call(self, input_texts: list[str]) -> list[list[float]]:
+        payload = json.dumps({
+            "model": self._model,
+            "input": input_texts,
+            "dimensions": self._dim,
+        }).encode("utf-8")
+
+        req = Request(
+            f"{self._base_url}/embeddings",
+            data=payload,
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self._api_key}",
+            },
+            method="POST",
+        )
+
+        with urlopen(req) as resp:
+            if resp.status != 200:
+                raise RuntimeError(f"OpenAI embedding failed ({resp.status})")
+            data = json.loads(resp.read())
+
+        # Sort by index (OpenAI may return out of order)
+        items = sorted(data["data"], key=lambda d: d["index"])
+        return [d["embedding"] for d in items]

agentic_memory/adapters/voyageai.py

@@ -0,0 +1,62 @@
+"""
+Voyage AI embedder adapter (high-quality, cheaper than OpenAI).
+Requires: VOYAGE_API_KEY
+
+Usage:
+    from agentic_memory import AgentMemory
+    from agentic_memory.adapters import VoyageEmbedder
+
+    memory = AgentMemory(
+        embedder=VoyageEmbedder(api_key="voyage-...")
+    )
+"""
+
+from __future__ import annotations
+
+import json
+from urllib.request import Request, urlopen
+
+
+class VoyageEmbedder:
+    def __init__(
+        self,
+        api_key: str,
+        model: str = "voyage-3-lite",
+    ) -> None:
+        self._api_key = api_key
+        self._model = model
+
+    def dimensions(self) -> int:
+        return 512 if "lite" in self._model else 1024
+
+    async def embed(self, text: str) -> list[float]:
+        result = self._call([text])
+        return result[0]
+
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        if not texts:
+            return []
+        return self._call(texts)
+
+    def _call(self, input_texts: list[str]) -> list[list[float]]:
+        payload = json.dumps({
+            "model": self._model,
+            "input": input_texts,
+        }).encode("utf-8")
+
+        req = Request(
+            "https://api.voyageai.com/v1/embeddings",
+            data=payload,
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self._api_key}",
+            },
+            method="POST",
+        )
+
+        with urlopen(req) as resp:
+            if resp.status != 200:
+                raise RuntimeError(f"Voyage AI embedding failed ({resp.status})")
+            data = json.loads(resp.read())
+
+        return [d["embedding"] for d in data["data"]]

agentic_memory/decay.py

@@ -0,0 +1,93 @@
+"""Typed decay engine - different memory types decay at different rates."""
+
+from __future__ import annotations
+
+import math
+from datetime import datetime, timezone
+
+from .types import (
+    MemoryEntry,
+    MemoryType,
+    ImportanceLevel,
+    DecayPolicy,
+    DecayConfig,
+    DecayTypeConfig,
+)
+
+DAY_MS = 24 * 60 * 60 * 1000
+
+DEFAULT_DECAY_CONFIG = DecayConfig(
+    policies={
+        MemoryType.CONSTRAINT: DecayTypeConfig(policy=DecayPolicy.NONE),
+        MemoryType.PREFERENCE: DecayTypeConfig(policy=DecayPolicy.EXPONENTIAL, half_life=30 * DAY_MS),
+        MemoryType.FACT: DecayTypeConfig(policy=DecayPolicy.EXPONENTIAL, half_life=90 * DAY_MS),
+        MemoryType.TASK: DecayTypeConfig(policy=DecayPolicy.STEP, max_age=7 * DAY_MS),
+        MemoryType.EPISODIC: DecayTypeConfig(policy=DecayPolicy.EXPONENTIAL, half_life=14 * DAY_MS),
+    },
+    default_policy=DecayPolicy.EXPONENTIAL,
+    default_half_life=30 * DAY_MS,
+)
+
+
+class DecayEngine:
+    """
+    Typed decay engine.
+    Different memory types decay at different rates.
+    Hard constraints (allergies, legal requirements) never decay.
+    """
+
+    def __init__(self, config: DecayConfig | None = None) -> None:
+        if config is None:
+            self._config = DEFAULT_DECAY_CONFIG
+        else:
+            # Merge with defaults
+            merged_policies = {**DEFAULT_DECAY_CONFIG.policies, **config.policies}
+            self._config = DecayConfig(
+                policies=merged_policies,
+                default_policy=config.default_policy,
+                default_half_life=config.default_half_life,
+            )
+
+    def compute_decayed_confidence(self, entry: MemoryEntry) -> float:
+        """Compute effective confidence after temporal decay."""
+        if entry.importance == ImportanceLevel.HARD:
+            return entry.confidence
+
+        type_config = self._config.policies.get(entry.type)
+        policy = type_config.policy if type_config else self._config.default_policy
+
+        dt = datetime.fromisoformat(entry.updated_at)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        age_ms = (datetime.now(timezone.utc) - dt).total_seconds() * 1000
+
+        if policy == DecayPolicy.NONE:
+            return entry.confidence
+
+        if policy == DecayPolicy.LINEAR:
+            rate = type_config.rate_per_day if type_config and type_config.rate_per_day else 0.01
+            age_days = age_ms / DAY_MS
+            return max(0.0, entry.confidence - rate * age_days)
+
+        if policy == DecayPolicy.EXPONENTIAL:
+            half_life = (
+                type_config.half_life
+                if type_config and type_config.half_life
+                else self._config.default_half_life
+            )
+            decay_factor = math.exp(-0.693 * age_ms / half_life)
+            return entry.confidence * decay_factor
+
+        if policy == DecayPolicy.STEP:
+            max_age = type_config.max_age if type_config and type_config.max_age else 7 * DAY_MS
+            return 0.0 if age_ms > max_age else entry.confidence
+
+        return entry.confidence
+
+    def filter_decayed(self, entries: list[MemoryEntry], threshold: float = 0.05) -> list[MemoryEntry]:
+        """Filter out memories that have decayed below threshold."""
+        return [e for e in entries if self.compute_decayed_confidence(e) >= threshold]
+
+    def get_expired(self, entries: list[MemoryEntry], threshold: float = 0.01) -> list[MemoryEntry]:
+        """Get entries that should be cleaned up."""
+        return [e for e in entries if self.compute_decayed_confidence(e) < threshold]

agentic_memory/memory.py

@@ -0,0 +1,243 @@
+"""AgentMemory - the main entry point."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .types import (
+    MemoryEntry,
+    MemoryType,
+    ImportanceLevel,
+    RetrievalQuery,
+    RetrievalResult,
+    ConflictResult,
+    Checkpoint,
+    TaskNode,
+    DecayConfig,
+)
+from .utils import generate_id, now
+from .store.local import LocalStore
+from .retrieval.embedder import BuiltinEmbedder
+from .retrieval.multi_signal import MultiSignalRetriever
+from .retrieval.conflict import ConflictDetector
+from .decay import DecayEngine
+
+
+class AgentMemory:
+    """
+    Framework-agnostic memory layer for AI agents.
+
+    Example::
+
+        memory = AgentMemory()
+
+        await memory.store(
+            content="User prefers dark mode",
+            type=MemoryType.PREFERENCE,
+            scope="user:123",
+        )
+
+        results = await memory.retrieve(RetrievalQuery(query="UI preferences"))
+        conflicts = await memory.check_conflicts("User prefers light mode", "user:123")
+    """
+
+    def __init__(
+        self,
+        *,
+        store: Any = None,
+        embedder: Any = None,
+        decay: DecayConfig | None = None,
+        default_scope: str = "default",
+        max_checkpoints: int = 10,
+    ) -> None:
+        self._backend = store if store is not None else LocalStore()
+        self._embedder = embedder if embedder is not None else BuiltinEmbedder()
+        self._retriever = MultiSignalRetriever(self._backend, self._embedder)
+        self._conflict_detector = ConflictDetector(self._backend, self._embedder)
+        self._decay_engine = DecayEngine(decay)
+        self._checkpoints: dict[str, Checkpoint] = {}
+        self._default_scope = default_scope
+        self._max_checkpoints = max_checkpoints
+
+    # ─── Store ───
+
+    async def store(
+        self,
+        content: str,
+        *,
+        type: MemoryType = MemoryType.FACT,
+        scope: Optional[str] = None,
+        importance: ImportanceLevel = ImportanceLevel.SOFT,
+        confidence: float = 1.0,
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> MemoryEntry:
+        """Store a new memory entry."""
+        if not content or not content.strip():
+            raise ValueError("Memory content cannot be empty")
+
+        # Train before embed so IDF stats include this document
+        if isinstance(self._embedder, BuiltinEmbedder):
+            self._embedder.train([content])
+
+        embedding = await self._embedder.embed(content)
+
+        entry = MemoryEntry(
+            id=generate_id(),
+            content=content,
+            type=type,
+            scope=scope or self._default_scope,
+            importance=importance,
+            confidence=confidence,
+            embedding=embedding,
+            metadata=metadata or {},
+            created_at=now(),
+            updated_at=now(),
+            version=1,
+        )
+
+        await self._backend.set(entry)
+        return entry
+
+    async def update(
+        self,
+        id: str,
+        *,
+        content: Optional[str] = None,
+        type: Optional[MemoryType] = None,
+        importance: Optional[ImportanceLevel] = None,
+        confidence: Optional[float] = None,
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> Optional[MemoryEntry]:
+        """Update an existing memory entry."""
+        entry = await self._backend.get(id)
+        if entry is None:
+            return None
+
+        if content is not None:
+            if not content.strip():
+                raise ValueError("Memory content cannot be empty")
+            entry.content = content
+
+        if type is not None:
+            entry.type = type
+        if importance is not None:
+            entry.importance = importance
+        if confidence is not None:
+            entry.confidence = confidence
+        if metadata is not None:
+            entry.metadata = metadata
+
+        entry.updated_at = now()
+        entry.version += 1
+
+        # Re-embed if content changed
+        if content is not None:
+            if isinstance(self._embedder, BuiltinEmbedder):
+                self._embedder.train([content])
+            entry.embedding = await self._embedder.embed(content)
+
+        await self._backend.set(entry)
+        return entry
+
+    async def get(self, id: str) -> Optional[MemoryEntry]:
+        """Get a memory by ID."""
+        return await self._backend.get(id)
+
+    async def delete(self, id: str) -> bool:
+        """Delete a memory by ID."""
+        return await self._backend.delete(id)
+
+    async def get_all(self, scope: Optional[str] = None) -> list[MemoryEntry]:
+        """Get all memories, optionally filtered by scope."""
+        return await self._backend.get_all(scope)
+
+    async def clear(self, scope: Optional[str] = None) -> None:
+        """Clear all memories, optionally for a specific scope."""
+        return await self._backend.clear(scope)
+
+    # ─── Retrieve ───
+
+    async def retrieve(self, query: RetrievalQuery) -> list[RetrievalResult]:
+        """Multi-signal retrieval."""
+        return await self._retriever.retrieve(query)
+
+    # ─── Conflict Detection ───
+
+    async def check_conflicts(
+        self, content: str, scope: Optional[str] = None
+    ) -> list[ConflictResult]:
+        """Check if content conflicts with stored memories."""
+        return await self._conflict_detector.check(
+            content, scope or self._default_scope
+        )
+
+    # ─── Decay ───
+
+    def get_decayed_confidence(self, entry: MemoryEntry) -> float:
+        """Get the current effective confidence after decay."""
+        return self._decay_engine.compute_decayed_confidence(entry)
+
+    async def cleanup(
+        self, scope: Optional[str] = None, threshold: float = 0.01
+    ) -> int:
+        """Clean up expired memories. Returns count deleted."""
+        entries = await self._backend.get_all(scope)
+        expired = self._decay_engine.get_expired(entries, threshold)
+        for entry in expired:
+            await self._backend.delete(entry.id)
+        return len(expired)
+
+    # ─── Checkpointing ───
+
+    async def checkpoint(
+        self,
+        *,
+        task_graph: list[TaskNode],
+        summary: str,
+        tool_outputs: Optional[dict[str, Any]] = None,
+        active_memory_ids: Optional[list[str]] = None,
+    ) -> Checkpoint:
+        """Create a checkpoint of current task state."""
+        cp = Checkpoint(
+            id=generate_id(),
+            task_graph=task_graph,
+            summary=summary,
+            tool_outputs=tool_outputs or {},
+            active_memory_ids=active_memory_ids or [],
+            created_at=now(),
+        )
+
+        self._checkpoints[cp.id] = cp
+
+        # Enforce max checkpoints (LRU eviction)
+        if len(self._checkpoints) > self._max_checkpoints:
+            oldest_key = next(iter(self._checkpoints))
+            del self._checkpoints[oldest_key]
+
+        return cp
+
+    async def rehydrate(
+        self, checkpoint_id: str
+    ) -> Optional[dict[str, Any]]:
+        """Rehydrate from a checkpoint. Returns checkpoint + memories."""
+        cp = self._checkpoints.get(checkpoint_id)
+        if cp is None:
+            return None
+
+        memories: list[MemoryEntry] = []
+        for mid in cp.active_memory_ids:
+            entry = await self._backend.get(mid)
+            if entry is not None:
+                memories.append(entry)
+
+        return {"checkpoint": cp, "memories": memories}
+
+    def get_latest_checkpoint(self) -> Optional[Checkpoint]:
+        """Get the latest checkpoint."""
+        if not self._checkpoints:
+            return None
+        return list(self._checkpoints.values())[-1]
+
+    def list_checkpoints(self) -> list[Checkpoint]:
+        """List all checkpoints."""
+        return list(self._checkpoints.values())

agentic_memory/retrieval/__init__.py

@@ -0,0 +1,5 @@
+from .embedder import BuiltinEmbedder
+from .multi_signal import MultiSignalRetriever
+from .conflict import ConflictDetector
+
+__all__ = ["BuiltinEmbedder", "MultiSignalRetriever", "ConflictDetector"]

agentic_memory/retrieval/conflict.py

@@ -0,0 +1,145 @@
+"""Conflict detector for finding contradictions in stored memories."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+from ..types import MemoryEntry, ConflictResult, ConflictAction, ImportanceLevel
+from ..utils import cosine_similarity
+
+NEGATION_PATTERNS = [
+    re.compile(p, re.IGNORECASE) for p in [
+        r"\bnot\b", r"\bnever\b", r"\bno\b", r"\bdon't\b", r"\bdoesn't\b",
+        r"\bwon't\b", r"\bcan't\b", r"\bhate\b", r"\bdislike\b", r"\bavoid\b",
+        r"\bstop\b", r"\bquit\b", r"\bremove\b", r"\bdelete\b",
+        r"\binstead of\b", r"\brather than\b", r"\bno longer\b",
+    ]
+]
+
+CHANGE_PATTERNS = [
+    re.compile(p, re.IGNORECASE) for p in [
+        r"\bnow\b", r"\bactually\b", r"\bchanged?\b", r"\bswitch",
+        r"\bprefer\b", r"\bwant\b", r"\bused to\b", r"\banymore\b",
+    ]
+]
+
+ANTONYM_PAIRS: list[tuple[re.Pattern, re.Pattern]] = [
+    (re.compile(a, re.IGNORECASE), re.compile(b, re.IGNORECASE))
+    for a, b in [
+        (r"\blike\b", r"\bdislike\b"),
+        (r"\blove\b", r"\bhate\b"),
+        (r"\byes\b", r"\bno\b"),
+        (r"\btrue\b", r"\bfalse\b"),
+        (r"\bvegetarian\b", r"\bmeat\b"),
+        (r"\bvegan\b", r"\bmeat\b|\bdairy\b"),
+        (r"\bmorning\b", r"\bevening\b|\bnight\b"),
+        (r"\blight\b", r"\bdark\b"),
+        (r"\bhot\b", r"\bcold\b"),
+        (r"\bfast\b", r"\bslow\b"),
+        (r"\benable\b", r"\bdisable\b"),
+        (r"\ballow\b", r"\bblock\b|\bdeny\b"),
+        (r"\baccept\b", r"\breject\b"),
+    ]
+]
+
+
+class ConflictDetector:
+    """
+    Conflict detector.
+    Compares new content against stored memories to find contradictions.
+    Uses semantic similarity + negation detection.
+    """
+
+    def __init__(
+        self,
+        store: Any,
+        embedder: Any,
+        topic_threshold: float = 0.6,
+    ) -> None:
+        self._store = store
+        self._embedder = embedder
+        self._topic_threshold = topic_threshold
+
+    async def check(self, content: str, scope: Optional[str] = None) -> list[ConflictResult]:
+        entries = await self._store.get_all(scope)
+        if not entries:
+            return []
+
+        content_embedding = await self._embedder.embed(content)
+        conflicts: list[ConflictResult] = []
+
+        for entry in entries:
+            entry_embedding = entry.embedding or await self._embedder.embed(entry.content)
+            similarity = cosine_similarity(content_embedding, entry_embedding)
+
+            if similarity < self._topic_threshold:
+                continue
+
+            contradiction_score = self._score_contradiction(content, entry.content)
+            if contradiction_score <= 0:
+                continue
+
+            confidence = min(1.0, similarity * 0.5 + contradiction_score * 0.5)
+
+            conflicts.append(ConflictResult(
+                incoming=content,
+                stored=entry,
+                confidence=confidence,
+                action=self._suggest_action(entry, confidence),
+                reason=self._generate_reason(content, entry, contradiction_score),
+            ))
+
+        conflicts.sort(key=lambda c: c.confidence, reverse=True)
+        return conflicts
+
+    def _score_contradiction(self, incoming: str, stored: str) -> float:
+        score = 0.0
+
+        incoming_negated = any(p.search(incoming) for p in NEGATION_PATTERNS)
+        stored_negated = any(p.search(stored) for p in NEGATION_PATTERNS)
+
+        if incoming_negated != stored_negated:
+            score += 0.5
+
+        if any(p.search(incoming) for p in CHANGE_PATTERNS):
+            score += 0.3
+
+        score += self._check_antonyms(incoming, stored) * 0.4
+
+        return min(1.0, score)
+
+    @staticmethod
+    def _check_antonyms(a: str, b: str) -> float:
+        matches = 0
+        for word1, word2 in ANTONYM_PAIRS:
+            if (word1.search(a) and word2.search(b)) or (word2.search(a) and word1.search(b)):
+                matches += 1
+        return min(1.0, matches * 0.5)
+
+    @staticmethod
+    def _suggest_action(stored: MemoryEntry, confidence: float) -> ConflictAction:
+        if stored.importance == ImportanceLevel.HARD:
+            return ConflictAction.CLARIFY
+        if confidence > 0.7 and stored.importance == ImportanceLevel.SOFT:
+            return ConflictAction.OVERRIDE
+        if stored.importance == ImportanceLevel.EPHEMERAL:
+            return ConflictAction.OVERRIDE
+        return ConflictAction.CLARIFY
+
+    @staticmethod
+    def _generate_reason(incoming: str, stored: MemoryEntry, contradiction_score: float) -> str:
+        if stored.importance == ImportanceLevel.HARD:
+            return (
+                f'Conflicts with a hard constraint: "{stored.content}". '
+                "This memory was marked as non-negotiable - please confirm the change."
+            )
+        if contradiction_score > 0.7:
+            return (
+                f'Directly contradicts stored memory: "{stored.content}". '
+                "The new statement appears to reverse a previous preference."
+            )
+        return (
+            f'Potentially conflicts with: "{stored.content}". '
+            "The statements may be inconsistent."
+        )