memvee 0.1.0__tar.gz

memvee-0.1.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: memvee
+Version: 0.1.0
+Summary: Structured, temporal memory for AI agents.
+Keywords: ai,agents,memory,llm,rag,temporal
+Author: bartosz roguski
+Author-email: bartosz roguski <bartosz.k.roguski@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Dist: aiosqlite>=0.22.1
+Requires-Dist: openai>=2.15.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-ai>=1.43.0
+Requires-Dist: sqlite-vec>=0.1.6
+Requires-Dist: textual>=3.5.0
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/vstorm-co/memv
+Project-URL: Documentation, https://vstorm-co.github.io/memv/
+Project-URL: Repository, https://github.com/vstorm-co/memv
+Project-URL: Issues, https://github.com/vstorm-co/memv/issues
+Project-URL: Changelog, https://github.com/vstorm-co/memv/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/banner.png" alt="memv" width="600">
+</p>
+
+<h1 align="center">memv</h1>
+
+<p align="center">
+  <b>Structured, Temporal Memory for AI Agents</b>
+</p>
+
+<p align="center">
+  <a href="https://vstorm-co.github.io/memv/">Docs</a> •
+  <a href="https://vstorm-co.github.io/memv/getting-started/">Getting Started</a> •
+  <a href="https://pypi.org/project/memvee/">PyPI</a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/memvee/"><img src="https://img.shields.io/pypi/v/memvee.svg" alt="PyPI version"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.13+-blue.svg" alt="Python 3.13+"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://github.com/pydantic/pydantic-ai"><img src="https://img.shields.io/badge/Powered%20by-Pydantic%20AI-E92063?logo=pydantic&logoColor=white" alt="Pydantic AI"></a>
+</p>
+
+<p align="center">
+  <b>🧠 Predict-Calibrate</b> extraction
+  &nbsp;•&nbsp;
+  <b>⏱️ Bi-Temporal</b> validity
+  &nbsp;•&nbsp;
+  <b>🔍 Hybrid</b> retrieval
+  &nbsp;•&nbsp;
+  <b>📦 SQLite</b> default
+</p>
+
+---
+
+## Why memv?
+
+Most memory systems extract everything and hope retrieval sorts it out. memv is different:
+
+| Typical Approach | memv |
+|------------------|--------|
+| Extract all facts upfront | Extract only what we **failed to predict** |
+| Overwrite old facts | **Invalidate** with temporal bounds |
+| Retrieve by similarity | **Hybrid** vector + BM25 + RRF |
+| Timestamps only | **Bi-temporal**: event time + transaction time |
+
+**Result:** Less noise, better retrieval, accurate history.
+
+---
+
+## Get Started in 60 Seconds
+
+```bash
+pip install memvee
+```
+
+```python
+from memv import Memory
+from memv.embeddings import OpenAIEmbedAdapter
+from memv.llm import PydanticAIAdapter
+
+memory = Memory(
+    db_path="memory.db",
+    embedding_client=OpenAIEmbedAdapter(),
+    llm_client=PydanticAIAdapter("openai:gpt-4o-mini"),
+)
+
+async with memory:
+    # Store conversation
+    await memory.add_exchange(
+        user_id="user-123",
+        user_message="I just started at Anthropic as a researcher.",
+        assistant_message="Congrats! What's your focus area?",
+    )
+    
+    # Extract knowledge
+    await memory.process("user-123")
+    
+    # Retrieve context
+    result = await memory.retrieve("What does the user do?", user_id="user-123")
+    print(result.to_prompt())
+```
+
+**That's it.** Your agent now has:
+
+- ✅ **Episodic memory** — conversations grouped into coherent episodes
+- ✅ **Semantic knowledge** — facts extracted via predict-calibrate
+- ✅ **Temporal awareness** — knows when facts were true
+- ✅ **Hybrid retrieval** — vector + text search with RRF fusion
+
+---
+
+## Features
+
+🧠 **Predict-Calibrate Extraction**
+> Only extracts what the model failed to predict. Importance emerges from prediction error, not upfront scoring. Based on [Nemori](https://arxiv.org/abs/2508.03341).
+
+⏱️ **Bi-Temporal Validity**
+> Track when facts were true (event time) vs when you learned them (transaction time). Query history at any point in time. Based on [Graphiti](https://github.com/getzep/graphiti).
+
+🔍 **Hybrid Retrieval**
+> Combines vector similarity and BM25 text search with Reciprocal Rank Fusion. Configurable weighting.
+
+📝 **Episode Segmentation**
+> Automatically groups messages into coherent conversation episodes. Handles interleaved topics.
+
+🔄 **Contradiction Handling**
+> New facts automatically invalidate conflicting old facts. Full history preserved.
+
+📅 **Temporal Parsing**
+> Relative dates ("last week", "yesterday") resolved to absolute timestamps at extraction time.
+
+⚡ **Async Processing**
+> Non-blocking `process_async()` with auto-processing when message threshold is reached.
+
+🗄️ **SQLite Default**
+> Zero-config local storage with sqlite-vec for vectors and FTS5 for text search.
+
+---
+
+## Point-in-Time Queries
+
+memv's bi-temporal model lets you query knowledge as it was at any moment:
+
+```python
+from datetime import datetime
+
+# What did we know about user's job in January 2024?
+result = await memory.retrieve(
+    "Where does user work?",
+    user_id="user-123",
+    at_time=datetime(2024, 1, 1),
+)
+
+# Show full history including superseded facts
+result = await memory.retrieve(
+    "Where does user work?",
+    user_id="user-123",
+    include_expired=True,
+)
+```
+
+---
+
+## Architecture
+
+```
+Messages (append-only)
+    │
+    ▼
+Episodes (segmented conversations)
+    │
+    ▼
+Knowledge (extracted facts with bi-temporal validity)
+    │
+    ├── Vector Index (sqlite-vec)
+    └── Text Index (FTS5)
+```
+
+**Extraction Flow:**
+1. Messages buffered until threshold
+2. Boundary detection segments into episodes
+3. Episode narrative generated
+4. Predict what episode should contain (given existing KB)
+5. Compare prediction vs actual → extract gaps
+6. Store with embeddings + temporal bounds
+
+---
+
+## Framework Integration
+
+memv works with any agent framework:
+
+```python
+class MyAgent:
+    def __init__(self, memory: Memory):
+        self.memory = memory
+    
+    async def run(self, user_input: str, user_id: str) -> str:
+        # 1. Retrieve relevant context
+        context = await self.memory.retrieve(user_input, user_id=user_id)
+        
+        # 2. Generate response with context
+        response = await self.llm.generate(
+            f"{context.to_prompt()}\n\nUser: {user_input}"
+        )
+        
+        # 3. Store the exchange
+        await self.memory.add_exchange(user_id, user_input, response)
+        
+        return response
+```
+
+---
+
+## Documentation
+
+- [Getting Started](https://vstorm-co.github.io/memv/getting-started/) — Installation, setup, first example
+- [Core Concepts](https://vstorm-co.github.io/memv/concepts/) — Predict-calibrate, episodes, bi-temporal, retrieval
+- [API Reference](https://vstorm-co.github.io/memv/api/) — All public classes and methods
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/vstorm-co/memv.git
+cd memv
+make install
+make all
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+<p align="center">
+  <sub>Built with ❤️ by <a href="https://github.com/vstorm-co">vstorm</a></sub>
+</p>

memvee-0.1.0/README.md

@@ -0,0 +1,223 @@
+<p align="center">
+  <img src="assets/banner.png" alt="memv" width="600">
+</p>
+
+<h1 align="center">memv</h1>
+
+<p align="center">
+  <b>Structured, Temporal Memory for AI Agents</b>
+</p>
+
+<p align="center">
+  <a href="https://vstorm-co.github.io/memv/">Docs</a> •
+  <a href="https://vstorm-co.github.io/memv/getting-started/">Getting Started</a> •
+  <a href="https://pypi.org/project/memvee/">PyPI</a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/memvee/"><img src="https://img.shields.io/pypi/v/memvee.svg" alt="PyPI version"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.13+-blue.svg" alt="Python 3.13+"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://github.com/pydantic/pydantic-ai"><img src="https://img.shields.io/badge/Powered%20by-Pydantic%20AI-E92063?logo=pydantic&logoColor=white" alt="Pydantic AI"></a>
+</p>
+
+<p align="center">
+  <b>🧠 Predict-Calibrate</b> extraction
+  &nbsp;•&nbsp;
+  <b>⏱️ Bi-Temporal</b> validity
+  &nbsp;•&nbsp;
+  <b>🔍 Hybrid</b> retrieval
+  &nbsp;•&nbsp;
+  <b>📦 SQLite</b> default
+</p>
+
+---
+
+## Why memv?
+
+Most memory systems extract everything and hope retrieval sorts it out. memv is different:
+
+| Typical Approach | memv |
+|------------------|--------|
+| Extract all facts upfront | Extract only what we **failed to predict** |
+| Overwrite old facts | **Invalidate** with temporal bounds |
+| Retrieve by similarity | **Hybrid** vector + BM25 + RRF |
+| Timestamps only | **Bi-temporal**: event time + transaction time |
+
+**Result:** Less noise, better retrieval, accurate history.
+
+---
+
+## Get Started in 60 Seconds
+
+```bash
+pip install memvee
+```
+
+```python
+from memv import Memory
+from memv.embeddings import OpenAIEmbedAdapter
+from memv.llm import PydanticAIAdapter
+
+memory = Memory(
+    db_path="memory.db",
+    embedding_client=OpenAIEmbedAdapter(),
+    llm_client=PydanticAIAdapter("openai:gpt-4o-mini"),
+)
+
+async with memory:
+    # Store conversation
+    await memory.add_exchange(
+        user_id="user-123",
+        user_message="I just started at Anthropic as a researcher.",
+        assistant_message="Congrats! What's your focus area?",
+    )
+    
+    # Extract knowledge
+    await memory.process("user-123")
+    
+    # Retrieve context
+    result = await memory.retrieve("What does the user do?", user_id="user-123")
+    print(result.to_prompt())
+```
+
+**That's it.** Your agent now has:
+
+- ✅ **Episodic memory** — conversations grouped into coherent episodes
+- ✅ **Semantic knowledge** — facts extracted via predict-calibrate
+- ✅ **Temporal awareness** — knows when facts were true
+- ✅ **Hybrid retrieval** — vector + text search with RRF fusion
+
+---
+
+## Features
+
+🧠 **Predict-Calibrate Extraction**
+> Only extracts what the model failed to predict. Importance emerges from prediction error, not upfront scoring. Based on [Nemori](https://arxiv.org/abs/2508.03341).
+
+⏱️ **Bi-Temporal Validity**
+> Track when facts were true (event time) vs when you learned them (transaction time). Query history at any point in time. Based on [Graphiti](https://github.com/getzep/graphiti).
+
+🔍 **Hybrid Retrieval**
+> Combines vector similarity and BM25 text search with Reciprocal Rank Fusion. Configurable weighting.
+
+📝 **Episode Segmentation**
+> Automatically groups messages into coherent conversation episodes. Handles interleaved topics.
+
+🔄 **Contradiction Handling**
+> New facts automatically invalidate conflicting old facts. Full history preserved.
+
+📅 **Temporal Parsing**
+> Relative dates ("last week", "yesterday") resolved to absolute timestamps at extraction time.
+
+⚡ **Async Processing**
+> Non-blocking `process_async()` with auto-processing when message threshold is reached.
+
+🗄️ **SQLite Default**
+> Zero-config local storage with sqlite-vec for vectors and FTS5 for text search.
+
+---
+
+## Point-in-Time Queries
+
+memv's bi-temporal model lets you query knowledge as it was at any moment:
+
+```python
+from datetime import datetime
+
+# What did we know about user's job in January 2024?
+result = await memory.retrieve(
+    "Where does user work?",
+    user_id="user-123",
+    at_time=datetime(2024, 1, 1),
+)
+
+# Show full history including superseded facts
+result = await memory.retrieve(
+    "Where does user work?",
+    user_id="user-123",
+    include_expired=True,
+)
+```
+
+---
+
+## Architecture
+
+```
+Messages (append-only)
+    │
+    ▼
+Episodes (segmented conversations)
+    │
+    ▼
+Knowledge (extracted facts with bi-temporal validity)
+    │
+    ├── Vector Index (sqlite-vec)
+    └── Text Index (FTS5)
+```
+
+**Extraction Flow:**
+1. Messages buffered until threshold
+2. Boundary detection segments into episodes
+3. Episode narrative generated
+4. Predict what episode should contain (given existing KB)
+5. Compare prediction vs actual → extract gaps
+6. Store with embeddings + temporal bounds
+
+---
+
+## Framework Integration
+
+memv works with any agent framework:
+
+```python
+class MyAgent:
+    def __init__(self, memory: Memory):
+        self.memory = memory
+    
+    async def run(self, user_input: str, user_id: str) -> str:
+        # 1. Retrieve relevant context
+        context = await self.memory.retrieve(user_input, user_id=user_id)
+        
+        # 2. Generate response with context
+        response = await self.llm.generate(
+            f"{context.to_prompt()}\n\nUser: {user_input}"
+        )
+        
+        # 3. Store the exchange
+        await self.memory.add_exchange(user_id, user_input, response)
+        
+        return response
+```
+
+---
+
+## Documentation
+
+- [Getting Started](https://vstorm-co.github.io/memv/getting-started/) — Installation, setup, first example
+- [Core Concepts](https://vstorm-co.github.io/memv/concepts/) — Predict-calibrate, episodes, bi-temporal, retrieval
+- [API Reference](https://vstorm-co.github.io/memv/api/) — All public classes and methods
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/vstorm-co/memv.git
+cd memv
+make install
+make all
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+<p align="center">
+  <sub>Built with ❤️ by <a href="https://github.com/vstorm-co">vstorm</a></sub>
+</p>

memvee-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "memvee"
+version = "0.1.0"
+description = "Structured, temporal memory for AI agents."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "bartosz roguski", email = "bartosz.k.roguski@gmail.com" }
+]
+requires-python = ">=3.13"
+keywords = ["ai", "agents", "memory", "llm", "rag", "temporal"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aiosqlite>=0.22.1",
+    "openai>=2.15.0",
+    "pydantic>=2.12.5",
+    "pydantic-ai>=1.43.0",
+    "sqlite-vec>=0.1.6",
+    "textual>=3.5.0",
+]
+
+[project.scripts]
+memv = "memv:main"
+
+[project.urls]
+Homepage = "https://github.com/vstorm-co/memv"
+Documentation = "https://vstorm-co.github.io/memv/"
+Repository = "https://github.com/vstorm-co/memv"
+Issues = "https://github.com/vstorm-co/memv/issues"
+Changelog = "https://github.com/vstorm-co/memv/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.9.21,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "memv"
+
+[dependency-groups]
+dev = [
+    "ipython>=9.9.0",
+    "pre-commit>=4.5.1",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.14.10",
+    "ty>=0.0.1a7",
+]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.6",
+    "mkdocstrings[python]>=0.28",
+]
+examples = [
+    "autogen-agentchat>=0.7",
+    "autogen-ext[openai]>=0.7",
+    "crewai>=0.11",
+    "langchain-openai>=1.0",
+    "langgraph>=1.0",
+    "llama-index>=0.14",
+    "llama-index-llms-openai>=0.6",
+    "rich>=13.0",
+    "typer>=0.15",
+]
+
+[tool.ruff]
+line-length = 135
+
+[tool.ruff.lint]
+select = [
+    "I",        # isort
+    "ERA",      # dead code
+    "F401",     # unused imports
+    "E",        # pycodestyle error
+    "W",        # pycodestyle warning
+    "B",        # flake8-bugbear
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

memvee-0.1.0/src/memv/__init__.py

@@ -0,0 +1,52 @@
+"""memv - Structured, temporal memory for AI agents.
+
+Example:
+    ```python
+    from memv import Memory, Message, MessageRole
+    from memv.embeddings import OpenAIEmbedAdapter
+    from memv.llm import PydanticAIAdapter
+
+    memory = Memory(
+        db_path="memory.db",
+        embedding_client=OpenAIEmbedAdapter(),
+        llm_client=PydanticAIAdapter("openai:gpt-4o-mini"),
+    )
+
+    async with memory:
+        await memory.add_exchange(user_id, user_msg, assistant_msg)
+        await memory.process(user_id)
+        result = await memory.retrieve("query", user_id=user_id)
+        print(result.to_prompt())
+    ```
+"""
+
+from memv.config import MemoryConfig
+from memv.memory import Memory
+from memv.models import (
+    Episode,
+    ExtractedKnowledge,
+    Message,
+    MessageRole,
+    ProcessStatus,
+    ProcessTask,
+    RetrievalResult,
+    SemanticKnowledge,
+)
+
+__all__ = [
+    "Memory",
+    "MemoryConfig",
+    "Message",
+    "MessageRole",
+    "Episode",
+    "SemanticKnowledge",
+    "ExtractedKnowledge",
+    "RetrievalResult",
+    "ProcessTask",
+    "ProcessStatus",
+]
+
+
+def main() -> None:
+    print("memv - Structured, temporal memory for AI agents.")
+    print("See examples/ for usage demos.")

memvee-0.1.0/src/memv/cache.py

@@ -0,0 +1,94 @@
+"""Caching utilities for AgentMemory."""
+
+import hashlib
+from collections import OrderedDict
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+
+@dataclass
+class CacheEntry:
+    """Entry in the embedding cache with expiration."""
+
+    value: list[float]
+    expires_at: datetime
+
+
+class EmbeddingCache:
+    """LRU cache for query embeddings with TTL.
+
+    Caches embedding vectors by text content hash to avoid redundant API calls.
+    Thread-safe for single-threaded async usage (no locks needed).
+
+    Example:
+        ```python
+        cache = EmbeddingCache(max_size=1000, ttl_seconds=600)
+
+        # Check cache first
+        embedding = cache.get("query text")
+        if embedding is None:
+            embedding = await embedder.embed("query text")
+            cache.set("query text", embedding)
+        ```
+    """
+
+    def __init__(self, max_size: int = 1000, ttl_seconds: int = 600):
+        """
+        Initialize the cache.
+
+        Args:
+            max_size: Maximum number of entries to cache
+            ttl_seconds: Time-to-live for entries in seconds
+        """
+        self.max_size = max_size
+        self.ttl = timedelta(seconds=ttl_seconds)
+        self._cache: OrderedDict[str, CacheEntry] = OrderedDict()
+
+    def _key(self, text: str) -> str:
+        """Generate cache key from text content."""
+        return hashlib.sha256(text.encode()).hexdigest()
+
+    def get(self, text: str) -> list[float] | None:
+        """
+        Get cached embedding for text.
+
+        Returns None if not found or expired.
+        """
+        key = self._key(text)
+        entry = self._cache.get(key)
+
+        if entry is None:
+            return None
+
+        # Check expiration
+        if datetime.now(timezone.utc) > entry.expires_at:
+            del self._cache[key]
+            return None
+
+        # Move to end (most recently used)
+        self._cache.move_to_end(key)
+        return entry.value
+
+    def set(self, text: str, embedding: list[float]) -> None:
+        """
+        Cache embedding for text.
+
+        Evicts oldest entry if cache is full.
+        """
+        # Evict if at capacity
+        while len(self._cache) >= self.max_size:
+            self._cache.popitem(last=False)  # Remove oldest
+
+        key = self._key(text)
+        self._cache[key] = CacheEntry(
+            value=embedding,
+            expires_at=datetime.now(timezone.utc) + self.ttl,
+        )
+
+    def clear(self) -> None:
+        """Clear all cached entries."""
+        self._cache.clear()
+
+    def __len__(self) -> int:
+        """Return number of cached entries."""
+        return len(self._cache)