Skip to content

memv

memv

Structured, temporal memory for AI agents

PyPI Python 3.13+ License Pydantic AI

memv (/mɛm-viː/) extracts knowledge from conversations using a predict-calibrate approach: importance emerges from prediction error, not upfront LLM scoring.

Why memv?

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

Quick Start

Bash
uv add memvee
# or: pip install memvee
Python
from memv import Memory
from memv.embeddings import OpenAIEmbedAdapter
from memv.llm import PydanticAIAdapter

memory = Memory(
    db_url="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())

Core Capabilities

Capability Description
Predict-Calibrate Extract only what the model failed to predict (Nemori)
Bi-Temporal Event time + transaction time for point-in-time queries (Graphiti)
Hybrid Retrieval Vector similarity + BM25 text search with RRF fusion
Episode Segmentation Groups messages into coherent episodes
Contradiction Handling New facts invalidate conflicting old facts, full audit trail preserved
Async Processing Background processing via process_async() with configurable auto-trigger
SQLite + PostgreSQL SQLite for local dev, PostgreSQL with pgvector for production
Multiple Embeddings OpenAI, Voyage, Cohere, or local via fastembed. Dimensions detected from adapter

Architecture

flowchart TD
    M[Messages] --> E[Episodes]
    E --> K[Knowledge]
    K --> VI[Vector Index]
    K --> TI[Text Index]
    VI -.- S1[sqlite-vec / pgvector]
    TI -.- S2[FTS5 / tsvector]

See Core Concepts for details, or Backends for storage setup.

Framework Integration

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

See Examples for integrations with PydanticAI, LangGraph, LlamaIndex, CrewAI, and AutoGen.

Next Steps