cognitive-memory 0.2.0__tar.gz

cognitive_memory-0.2.0/.gitignore

@@ -0,0 +1,55 @@
+# Dependencies
+node_modules/
+.pnp/
+.pnp.js
+
+# Python
+.venv/
+venv/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# TypeScript / Node build
+dist/
+*.tsbuildinfo
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Coverage
+coverage/
+htmlcov/
+.coverage
+.nyc_output/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docs build
+docs/dist/
+docs/.astro/
+
+# Test artifacts
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Lockfiles (keep package-lock.json)
+!package-lock.json
+.vercel

cognitive_memory-0.2.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: cognitive-memory
+Version: 0.2.0
+Summary: Biologically-inspired agent memory with decay, consolidation, and tiered storage
+Project-URL: Homepage, https://github.com/bhekanik/cognitive-memory
+Project-URL: Documentation, https://bhekanik.github.io/cognitive-memory
+Project-URL: Repository, https://github.com/bhekanik/cognitive-memory
+Project-URL: Issues, https://github.com/bhekanik/cognitive-memory/issues
+Author: Bhekani Khumalo
+License-Expression: MIT
+Keywords: agents,ai,cognitive,decay,llm,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: all
+Requires-Dist: aiosqlite>=0.19; extra == 'all'
+Requires-Dist: asyncpg>=0.29; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Requires-Dist: redis[hiredis]>=5.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis[hiredis]>=5.0; extra == 'redis'
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.19; extra == 'sqlite'
+Description-Content-Type: text/markdown
+
+# cognitive-memory (Python)
+
+Biologically-inspired agent memory with decay, consolidation, and tiered storage.
+
+See [documentation](https://bhekanik.github.io/cognitive-memory) for details.

cognitive_memory-0.2.0/README.md

@@ -0,0 +1,5 @@
+# cognitive-memory (Python)
+
+Biologically-inspired agent memory with decay, consolidation, and tiered storage.
+
+See [documentation](https://bhekanik.github.io/cognitive-memory) for details.

cognitive_memory-0.2.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cognitive-memory"
+version = "0.2.0"
+description = "Biologically-inspired agent memory with decay, consolidation, and tiered storage"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Bhekani Khumalo" },
+]
+keywords = ["memory", "ai", "agents", "cognitive", "decay", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+sqlite = ["aiosqlite>=0.19"]
+postgres = ["asyncpg>=0.29"]
+redis = ["redis[hiredis]>=5.0"]
+all = ["cognitive-memory[openai,sqlite,postgres,redis]"]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/bhekanik/cognitive-memory"
+Documentation = "https://bhekanik.github.io/cognitive-memory"
+Repository = "https://github.com/bhekanik/cognitive-memory"
+Issues = "https://github.com/bhekanik/cognitive-memory/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cognitive_memory"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120

cognitive_memory-0.2.0/src/cognitive_memory/__init__.py

@@ -0,0 +1,70 @@
+"""
+cognitive-memory: A Python SDK for biologically-inspired agent memory.
+
+Implements decay floors, emergent core memory detection, two-tier
+retrieval boosting, associative linking, tiered hot/cold storage
+with TTL, and reversible consolidation.
+
+Quick start:
+    from cognitive_memory import SyncCognitiveMemory
+
+    mem = SyncCognitiveMemory(embedder="hash")
+    mem.add("User is allergic to shellfish", category="core", importance=0.95)
+    results = mem.search("what allergies does the user have?")
+"""
+
+from .core import CognitiveMemory
+from ._sync import SyncCognitiveMemory
+from .types import (
+    Memory,
+    MemoryCategory,
+    CognitiveMemoryConfig,
+    SearchResult,
+    SearchResponse,
+    SearchTrace,
+    StageTrace,
+    Association,
+)
+from .engine import CognitiveEngine
+from .extraction import MemoryExtractor
+from .embeddings import (
+    EmbeddingProvider,
+    OpenAIEmbeddings,
+    HashEmbeddings,
+    cosine_similarity,
+)
+from .adapters import MemoryAdapter, InMemoryAdapter
+
+# Backward compat
+from .store import MemoryStore
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main API
+    "CognitiveMemory",
+    "SyncCognitiveMemory",
+    # Types
+    "CognitiveMemoryConfig",
+    "Memory",
+    "MemoryCategory",
+    "SearchResult",
+    "SearchResponse",
+    "SearchTrace",
+    "StageTrace",
+    "Association",
+    # Engine
+    "CognitiveEngine",
+    # Extraction
+    "MemoryExtractor",
+    # Embeddings
+    "EmbeddingProvider",
+    "OpenAIEmbeddings",
+    "HashEmbeddings",
+    "cosine_similarity",
+    # Adapters
+    "MemoryAdapter",
+    "InMemoryAdapter",
+    # Backward compat
+    "MemoryStore",
+]

cognitive_memory-0.2.0/src/cognitive_memory/_sync.py

@@ -0,0 +1,135 @@
+"""
+Synchronous wrapper around async CognitiveMemory.
+
+Provides the same API but runs everything through asyncio.run().
+Useful for scripts, notebooks, and benchmark compatibility.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+from typing import Optional, Literal
+
+from .types import Memory, MemoryCategory, CognitiveMemoryConfig, SearchResult, SearchResponse
+from .adapters.base import MemoryAdapter
+from .embeddings import EmbeddingProvider
+from .core import CognitiveMemory
+
+
+def _run(coro):
+    """Run an async coroutine synchronously."""
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        loop = None
+
+    if loop and loop.is_running():
+        # We're inside an existing event loop (e.g., Jupyter).
+        # Create a new loop in a thread.
+        import concurrent.futures
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            return pool.submit(asyncio.run, coro).result()
+    else:
+        return asyncio.run(coro)
+
+
+class SyncCognitiveMemory:
+    """
+    Synchronous wrapper around CognitiveMemory.
+
+    Usage:
+        from cognitive_memory import SyncCognitiveMemory
+
+        mem = SyncCognitiveMemory(embedder="hash")
+        mem.add("User likes coffee", importance=0.5)
+        results = mem.search("coffee")
+    """
+
+    def __init__(
+        self,
+        config: Optional[CognitiveMemoryConfig] = None,
+        embedder: Optional[EmbeddingProvider | Literal["openai", "hash"]] = None,
+        adapter: Optional[MemoryAdapter] = None,
+    ):
+        self._async = CognitiveMemory(
+            config=config,
+            embedder=embedder,
+            adapter=adapter,
+        )
+
+    def add(
+        self,
+        content: str,
+        category: MemoryCategory = MemoryCategory.EPISODIC,
+        importance: float = 0.5,
+        session_id: Optional[str] = None,
+        timestamp: Optional[datetime] = None,
+    ) -> Memory:
+        return _run(self._async.add(
+            content=content,
+            category=category,
+            importance=importance,
+            session_id=session_id,
+            timestamp=timestamp,
+        ))
+
+    def add_memory_object(self, memory: Memory) -> Memory:
+        return _run(self._async.add_memory_object(memory))
+
+    def extract_and_store(
+        self,
+        conversation_text: str,
+        session_id: str,
+        timestamp: Optional[datetime] = None,
+        run_tick: bool = True,
+    ) -> list[Memory]:
+        return _run(self._async.extract_and_store(
+            conversation_text=conversation_text,
+            session_id=session_id,
+            timestamp=timestamp,
+            run_tick=run_tick,
+        ))
+
+    def search(
+        self,
+        query: str,
+        top_k: int = 10,
+        timestamp: Optional[datetime] = None,
+        session_id: Optional[str] = None,
+        deep_recall: bool = False,
+        trace: bool = False,
+    ) -> SearchResponse:
+        return _run(self._async.search(
+            query=query,
+            top_k=top_k,
+            timestamp=timestamp,
+            session_id=session_id,
+            deep_recall=deep_recall,
+            trace=trace,
+        ))
+
+    def tick(self, now: Optional[datetime] = None):
+        return _run(self._async.tick(now))
+
+    def get_stats(self) -> dict:
+        return _run(self._async.get_stats())
+
+    def clear(self):
+        return _run(self._async.clear())
+
+    @property
+    def adapter(self) -> MemoryAdapter:
+        return self._async.adapter
+
+    @property
+    def engine(self):
+        return self._async.engine
+
+    @property
+    def embedder(self) -> EmbeddingProvider:
+        return self._async.embedder
+
+    @property
+    def config(self) -> CognitiveMemoryConfig:
+        return self._async.config

cognitive_memory-0.2.0/src/cognitive_memory/adapters/__init__.py

@@ -0,0 +1,9 @@
+"""Adapter implementations for cognitive-memory storage backends."""
+
+from .base import MemoryAdapter
+from .memory import InMemoryAdapter
+
+__all__ = [
+    "MemoryAdapter",
+    "InMemoryAdapter",
+]

cognitive_memory-0.2.0/src/cognitive_memory/adapters/base.py

@@ -0,0 +1,235 @@
+"""
+Abstract base class for memory storage adapters.
+
+All adapters are async-first. Use SyncCognitiveMemory for sync wrappers.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Optional, Callable, TypeVar
+
+from ..types import Memory
+
+T = TypeVar("T")
+
+
+class MemoryAdapter(ABC):
+    """
+    Abstract adapter interface for cognitive-memory storage backends.
+
+    Implementations must provide async methods for CRUD, vector search,
+    tiered storage migration, associative links, and consolidation.
+    """
+
+    # ------------------------------------------------------------------
+    # CRUD
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def create(self, memory: Memory) -> None:
+        """Store a new memory."""
+        ...
+
+    @abstractmethod
+    async def get(self, memory_id: str) -> Optional[Memory]:
+        """Get a memory by ID from any tier."""
+        ...
+
+    @abstractmethod
+    async def get_batch(self, memory_ids: list[str]) -> list[Memory]:
+        """Get multiple memories by ID."""
+        ...
+
+    @abstractmethod
+    async def update(self, memory: Memory) -> None:
+        """Update an existing memory in place."""
+        ...
+
+    @abstractmethod
+    async def delete(self, memory_id: str) -> None:
+        """Hard delete from any tier."""
+        ...
+
+    @abstractmethod
+    async def delete_batch(self, memory_ids: list[str]) -> None:
+        """Hard delete multiple memories."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Vector search
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def search_similar(
+        self,
+        query_embedding: list[float],
+        top_k: int = 10,
+        include_superseded: bool = False,
+    ) -> list[tuple[Memory, float]]:
+        """
+        Search by cosine similarity.
+
+        Returns list of (memory, similarity_score) sorted descending.
+        Superseded memories are excluded by default.
+        """
+        ...
+
+    # ------------------------------------------------------------------
+    # Lexical search (optional, for hybrid retrieval)
+    # ------------------------------------------------------------------
+
+    async def search_lexical(
+        self,
+        query: str,
+        top_k: int = 10,
+        include_superseded: bool = False,
+    ) -> list[tuple["Memory", float]]:
+        """
+        BM25/lexical search. Override in adapters that support it.
+        Returns list of (memory, bm25_score) sorted descending.
+        Default: returns empty list (dense-only fallback).
+        """
+        return []
+
+    # ------------------------------------------------------------------
+    # Tiered storage
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def migrate_to_cold(self, memory_id: str, cold_since: "datetime") -> None:
+        """Move a memory from hot to cold store."""
+        ...
+
+    @abstractmethod
+    async def migrate_to_hot(self, memory_id: str) -> None:
+        """Reactivate a cold memory back to hot store."""
+        ...
+
+    @abstractmethod
+    async def convert_to_stub(self, memory_id: str, stub_content: str) -> None:
+        """Replace a memory with a lightweight stub (TTL expiry)."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Associative links
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def create_or_strengthen_link(
+        self, source_id: str, target_id: str, weight: float,
+    ) -> None:
+        """Create or strengthen a bidirectional association."""
+        ...
+
+    @abstractmethod
+    async def get_linked_memories(
+        self, memory_id: str, min_weight: float = 0.3,
+    ) -> list[tuple[Memory, float]]:
+        """Get memories linked to a given memory above threshold."""
+        ...
+
+    @abstractmethod
+    async def delete_link(self, source_id: str, target_id: str) -> None:
+        """Delete an association between two memories."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Consolidation helpers
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def find_fading(
+        self, threshold: float, exclude_core: bool = True,
+    ) -> list[Memory]:
+        """Find non-superseded memories with retention below threshold."""
+        ...
+
+    @abstractmethod
+    async def find_stable(
+        self, min_stability: float, min_access_count: int,
+    ) -> list[Memory]:
+        """Find highly stable, frequently accessed memories."""
+        ...
+
+    @abstractmethod
+    async def mark_superseded(
+        self, memory_ids: list[str], summary_id: str,
+    ) -> None:
+        """Mark memories as superseded by a consolidation summary."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Traversal
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def all_active(self) -> list[Memory]:
+        """All memories in hot + cold (not stubs)."""
+        ...
+
+    @abstractmethod
+    async def all_hot(self) -> list[Memory]:
+        """All memories in the hot store."""
+        ...
+
+    @abstractmethod
+    async def all_cold(self) -> list[Memory]:
+        """All memories in the cold store."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Counts
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def hot_count(self) -> int:
+        ...
+
+    @abstractmethod
+    async def cold_count(self) -> int:
+        ...
+
+    @abstractmethod
+    async def stub_count(self) -> int:
+        ...
+
+    @abstractmethod
+    async def total_count(self) -> int:
+        ...
+
+    # ------------------------------------------------------------------
+    # Batch operations
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def batch_update(self, memories: list[Memory]) -> None:
+        """Update multiple memories at once."""
+        ...
+
+    @abstractmethod
+    async def update_retention_scores(self, updates: dict[str, float]) -> None:
+        """Bulk update retention scores: {memory_id: new_retention}."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Transactions
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def transaction(self, callback: Callable[["MemoryAdapter"], T]) -> T:
+        """Execute callback within a transaction (adapter-specific)."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Reset
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def clear(self) -> None:
+        """Clear all data."""
+        ...
+
+
+# Avoid circular import — just for type hints
+from datetime import datetime  # noqa: E402

cognitive_memory-0.2.0/src/cognitive_memory/adapters/convex.py

@@ -0,0 +1,13 @@
+"""
+Convex adapter stub for cognitive-memory.
+
+The Convex adapter is TypeScript-primary. See the TypeScript SDK for the
+full implementation. This stub exists for cross-language parity.
+
+Status: Not yet implemented. See https://github.com/bhekanik/cognitive-memory/issues
+"""
+
+raise NotImplementedError(
+    "ConvexAdapter is TypeScript-primary. "
+    "See the TypeScript SDK for the full implementation."
+)

cognitive_memory-0.2.0/src/cognitive_memory/adapters/jsonl.py

@@ -0,0 +1,13 @@
+"""
+JSONL file adapter stub for cognitive-memory.
+
+The JSONL adapter is TypeScript-primary. See the TypeScript SDK for the
+full implementation. This stub exists for cross-language parity.
+
+Status: Not yet implemented. See https://github.com/bhekanik/cognitive-memory/issues
+"""
+
+raise NotImplementedError(
+    "JsonlFileAdapter is TypeScript-primary. "
+    "See the TypeScript SDK for the full implementation."
+)