mem01-engine 0.1.0__py3-none-any.whl

mem01/__init__.py

@@ -0,0 +1,51 @@
+"""mem01 — belief-based agent memory.
+
+See PRODUCT.md for product intent and IMPLEMENTATION_PLAN.md for build order.
+"""
+
+from mem01.client import MemoryClient, RememberResult
+from mem01.ids import new_belief_id
+from mem01.runtime import OpenAIRuntimeSettings, build_openai_memory_client
+from mem01.store import (
+    BeliefStore,
+    InMemoryBeliefStore,
+    ScopeFilter,
+    create_belief_store,
+)
+from mem01.types import (
+    Belief,
+    BeliefOp,
+    BeliefOpType,
+    BeliefSource,
+    BeliefStatus,
+    PackedMemory,
+    ScopeIds,
+    ScopeKind,
+    ScoredBelief,
+)
+from mem01.write.apply_ops import ApplyResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "Belief",
+    "ApplyResult",
+    "BeliefOp",
+    "BeliefOpType",
+    "BeliefSource",
+    "BeliefStatus",
+    "BeliefStore",
+    "InMemoryBeliefStore",
+    "MemoryClient",
+    "OpenAIRuntimeSettings",
+    "PackedMemory",
+    "RememberResult",
+    "ScopeFilter",
+    "ScopeIds",
+    "ScopeKind",
+    "ScoredBelief",
+    "create_belief_store",
+    "build_openai_memory_client",
+    "new_belief_id",
+]

mem01/api/__init__.py

@@ -0,0 +1 @@
+"""HTTP API package."""

mem01/api/app.py

@@ -0,0 +1,247 @@
+"""HTTP API for self-hosted mem01 (remember / recall / correct / forget).
+
+Run via Docker Compose or:
+  uvicorn mem01.api.app:app --host 0.0.0.0 --port 8080
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel, Field
+
+from mem01.client import MemoryClient
+from mem01.env import load_env
+from mem01.runtime import build_openai_memory_client
+from mem01.store.factory import create_belief_store
+
+
+class RememberBody(BaseModel):
+    messages: list[dict[str, str]]
+    user_id: str
+    project_id: str | None = None
+    session_id: str | None = None
+    agent_id: str | None = None
+
+
+class RecallBody(BaseModel):
+    query: str
+    user_id: str
+    project_id: str | None = None
+    session_id: str | None = None
+    agent_id: str | None = None
+    max_memory_tokens: int = Field(default=800, ge=0)
+    k: int = Field(default=20, ge=1, le=200)
+    # False = current truth only; True = include superseded/invalidated (labeled)
+    include_history: bool = False
+
+
+class HistoryBody(BaseModel):
+    user_id: str
+    project_id: str | None = None
+    session_id: str | None = None
+    agent_id: str | None = None
+    include_invalidated: bool = True
+    limit: int = Field(default=100, ge=1, le=500)
+
+
+class CorrectBody(BaseModel):
+    user_id: str
+    memory_id: str
+    new_value: str
+    confidence: float = Field(default=0.95, ge=0.0, le=1.0)
+
+
+class ForgetBody(BaseModel):
+    user_id: str
+    memory_id: str
+    reason: str | None = None
+
+
+def _build_client() -> MemoryClient:
+    load_env()
+    # Prefer real OpenAI when key present; else Fake for health-only deploys
+    import os
+
+    key = os.environ.get("OPENAI_API_KEY", "").strip()
+    if key:
+        return build_openai_memory_client()
+
+    store = create_belief_store()
+    from mem01.embeddings.fake import FakeEmbedder
+    from mem01.llm.fake import FakeLLM
+
+    dim = int(os.environ.get("MEM01_EMBEDDING_DIM", "1536"))
+    embedder = FakeEmbedder(dimensions=dim)
+    llm = FakeLLM("[]")
+    return MemoryClient(store=store, embedder=embedder, llm=llm)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    app.state.client = _build_client()
+    yield
+    close = getattr(app.state.client.store, "close", None)
+    if callable(close):
+        close()
+
+
+app = FastAPI(
+    title="mem01",
+    description="Belief-based agent memory (self-hosted)",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    llm = app.state.client.llm
+    extraction_model = getattr(llm, "model", None)
+    if not isinstance(extraction_model, str) or not extraction_model:
+        extraction_model = "fake" if type(llm).__name__ == "FakeLLM" else "unknown"
+    return {
+        "status": "ok",
+        "service": "mem01",
+        "extraction_model": extraction_model,
+    }
+
+
+@app.post("/v1/remember")
+def remember(body: RememberBody) -> dict[str, Any]:
+    client: MemoryClient = app.state.client
+    try:
+        result = client.remember(
+            body.messages,
+            user_id=body.user_id,
+            project_id=body.project_id,
+            session_id=body.session_id,
+            agent_id=body.agent_id,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+    return {
+        "ok": result.apply.ok,
+        "created_ids": result.apply.created_ids,
+        "updated_ids": result.apply.updated_ids,
+        "superseded_ids": result.apply.superseded_ids,
+        "invalidated_ids": result.apply.invalidated_ids,
+        "errors": result.apply.errors,
+        "llm_calls": result.llm_calls,
+        "latency_ms": result.latency_ms,
+    }
+
+
+@app.post("/v1/recall")
+def recall(body: RecallBody) -> dict[str, Any]:
+    client: MemoryClient = app.state.client
+    try:
+        packed = client.recall(
+            body.query,
+            user_id=body.user_id,
+            project_id=body.project_id,
+            session_id=body.session_id,
+            agent_id=body.agent_id,
+            max_memory_tokens=body.max_memory_tokens,
+            k=body.k,
+            include_history=body.include_history,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+    return {
+        "text": packed.text,
+        "tokens_used": packed.tokens_used,
+        "max_memory_tokens": packed.max_memory_tokens,
+        "candidate_count": packed.candidate_count,
+        "latency_ms": packed.latency_ms,
+        "include_history": body.include_history,
+        "beliefs": [
+            {
+                "id": b.id,
+                "content": b.content,
+                "status": b.status.value,
+                "supersedes_id": b.supersedes_id,
+                "source": b.source.value,
+                "valid_from": b.valid_from.isoformat() if b.valid_from else None,
+                "valid_to": b.valid_to.isoformat() if b.valid_to else None,
+                "created_at": b.created_at.isoformat(),
+                "updated_at": b.updated_at.isoformat(),
+            }
+            for b in packed.beliefs
+        ],
+    }
+
+
+@app.post("/v1/history")
+def history(body: HistoryBody) -> dict[str, Any]:
+    """Full belief timeline for a scope — audit / “let me see previous facts”."""
+    client: MemoryClient = app.state.client
+    try:
+        beliefs = client.history(
+            user_id=body.user_id,
+            project_id=body.project_id,
+            session_id=body.session_id,
+            agent_id=body.agent_id,
+            include_invalidated=body.include_invalidated,
+            limit=body.limit,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+    return {
+        "count": len(beliefs),
+        "beliefs": [
+            {
+                "id": b.id,
+                "content": b.content,
+                "status": b.status.value,
+                "confidence": b.confidence,
+                "supersedes_id": b.supersedes_id,
+                "source": b.source.value,
+                "valid_from": b.valid_from.isoformat() if b.valid_from else None,
+                "valid_to": b.valid_to.isoformat() if b.valid_to else None,
+                "created_at": b.created_at.isoformat(),
+                "updated_at": b.updated_at.isoformat(),
+            }
+            for b in beliefs
+        ],
+    }
+
+
+@app.post("/v1/correct")
+def correct(body: CorrectBody) -> dict[str, Any]:
+    client: MemoryClient = app.state.client
+    try:
+        result = client.correct(
+            body.memory_id,
+            body.new_value,
+            user_id=body.user_id,
+            confidence=body.confidence,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+    return {
+        "ok": result.ok,
+        "created_ids": result.created_ids,
+        "superseded_ids": result.superseded_ids,
+        "errors": result.errors,
+    }
+
+
+@app.post("/v1/forget")
+def forget(body: ForgetBody) -> dict[str, Any]:
+    client: MemoryClient = app.state.client
+    try:
+        result = client.forget(
+            body.memory_id,
+            user_id=body.user_id,
+            reason=body.reason,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+    return {
+        "ok": result.ok,
+        "invalidated_ids": result.invalidated_ids,
+        "errors": result.errors,
+    }

mem01/client.py

@@ -0,0 +1,240 @@
+"""MemoryClient — public facade (mem0-class four verbs).
+
+remember / recall / correct / forget wire write + read pipelines.
+Users and later HTTP/MCP should depend on this, not internal modules.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from mem01.embeddings.base import Embedder
+from mem01.llm.base import LLMClient
+from mem01.metrics import timer
+from mem01.read.recall import recall as recall_pipeline
+from mem01.store.base import BeliefStore
+from mem01.types import (
+    Belief,
+    BeliefOp,
+    BeliefOpType,
+    BeliefSource,
+    BeliefStatus,
+    PackedMemory,
+    ScopeIds,
+    ScopeKind,
+)
+from mem01.write.apply_ops import ApplyResult, apply_ops
+from mem01.write.extractor import extract_ops
+
+
+@dataclass
+class RememberResult:
+    """Outcome of remember()."""
+
+    apply: ApplyResult
+    ops: list[BeliefOp]
+    llm_calls: int
+    latency_ms: float
+    existing_considered: int = 0
+
+
+@dataclass
+class MemoryClient:
+    """High-level memory API.
+
+    Defaults match product direction: inject real OpenAI (or other) LLM/embedder
+    for real use; tests can pass scripted/fake implementations.
+    """
+
+    store: BeliefStore
+    embedder: Embedder
+    llm: LLMClient
+    default_user_id: str | None = None
+    # How many existing actives to show the extractor for SUPERSEDE decisions
+    existing_for_extract_k: int = 15
+
+    def _scope_ids(
+        self,
+        user_id: str | None = None,
+        *,
+        project_id: str | None = None,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+    ) -> ScopeIds:
+        uid = user_id if user_id is not None else self.default_user_id
+        return ScopeIds(
+            user_id=uid,
+            project_id=project_id,
+            session_id=session_id,
+            agent_id=agent_id,
+        )
+
+    def remember(
+        self,
+        messages: list[dict[str, str]],
+        *,
+        user_id: str | None = None,
+        project_id: str | None = None,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+        scope: ScopeKind = ScopeKind.USER,
+    ) -> RememberResult:
+        """Extract belief ops from messages (1 LLM call) and apply them."""
+        scope_ids = self._scope_ids(
+            user_id,
+            project_id=project_id,
+            session_id=session_id,
+            agent_id=agent_id,
+        )
+        with timer() as t:
+            existing = self._existing_snippets(scope_ids)
+            ops = extract_ops(
+                messages,
+                llm=self.llm,
+                existing_beliefs=existing,
+                scope=scope,
+                scope_ids=scope_ids,
+            )
+            apply_result = apply_ops(
+                self.store,
+                ops,
+                self.embedder,
+                default_source=BeliefSource.EXTRACTION,
+                expected_user_id=scope_ids.user_id,
+            )
+        return RememberResult(
+            apply=apply_result,
+            ops=ops,
+            llm_calls=1,
+            latency_ms=t.latency_ms,
+            existing_considered=len(existing),
+        )
+
+    def recall(
+        self,
+        query: str,
+        *,
+        user_id: str | None = None,
+        project_id: str | None = None,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+        max_memory_tokens: int = 800,
+        k: int = 20,
+        include_history: bool = False,
+    ) -> PackedMemory:
+        """Hot-path retrieve — 0 LLM calls.
+
+        Default: active beliefs only (current truth).
+        include_history=True: also return superseded/invalidated, labeled in text
+        (use for “before SF?” / medical audit style questions).
+        """
+        scope_ids = self._scope_ids(
+            user_id,
+            project_id=project_id,
+            session_id=session_id,
+            agent_id=agent_id,
+        )
+        return recall_pipeline(
+            self.store,
+            self.embedder,
+            query,
+            scope_ids,
+            max_memory_tokens=max_memory_tokens,
+            k=k,
+            include_history=include_history,
+        )
+
+    def history(
+        self,
+        *,
+        user_id: str | None = None,
+        project_id: str | None = None,
+        session_id: str | None = None,
+        agent_id: str | None = None,
+        include_invalidated: bool = True,
+        limit: int = 100,
+    ) -> list[Belief]:
+        """Chronological belief timeline for a scope (audit / “let me see”).
+
+        Includes active + superseded (+ invalidated by default). Newest first.
+        Does not call an LLM or run vector search.
+        """
+        scope_ids = self._scope_ids(
+            user_id,
+            project_id=project_id,
+            session_id=session_id,
+            agent_id=agent_id,
+        )
+        statuses = {
+            BeliefStatus.ACTIVE,
+            BeliefStatus.SUPERSEDED,
+        }
+        if include_invalidated:
+            statuses.add(BeliefStatus.INVALIDATED)
+        beliefs = self.store.list_by_scope(scope_ids, statuses=statuses)
+        beliefs.sort(key=lambda b: b.updated_at, reverse=True)
+        return beliefs[: max(1, limit)]
+
+    def correct(
+        self,
+        memory_id: str,
+        new_value: str,
+        *,
+        user_id: str | None = None,
+        confidence: float = 0.95,
+    ) -> ApplyResult:
+        """Human/agent fix: SUPERSEDE by id (no LLM)."""
+        op = BeliefOp(
+            op=BeliefOpType.SUPERSEDE,
+            target_id=memory_id,
+            content=new_value,
+            confidence=confidence,
+        )
+        return apply_ops(
+            self.store,
+            [op],
+            self.embedder,
+            default_source=BeliefSource.CORRECTION,
+            expected_user_id=self._scope_ids(user_id).user_id,
+        )
+
+    def forget(
+        self,
+        memory_id: str,
+        *,
+        user_id: str | None = None,
+        reason: str | None = None,
+    ) -> ApplyResult:
+        """Invalidate a belief by id (no LLM)."""
+        op = BeliefOp(
+            op=BeliefOpType.INVALIDATE,
+            target_id=memory_id,
+            reason=reason,
+        )
+        return apply_ops(
+            self.store,
+            [op],
+            self.embedder,
+            default_source=BeliefSource.FORGET,
+            expected_user_id=self._scope_ids(user_id).user_id,
+        )
+
+    def clear_user(self, *, user_id: str | None = None) -> int:
+        """Hard-delete all stored beliefs for one user."""
+        resolved_user_id = user_id if user_id is not None else self.default_user_id
+        if resolved_user_id is None or not resolved_user_id.strip():
+            raise ValueError("user_id must be non-empty")
+        return self.store.delete_by_user(resolved_user_id)
+
+    def get(self, memory_id: str) -> Belief | None:
+        return self.store.get(memory_id)
+
+    def _existing_snippets(self, scope_ids: ScopeIds) -> list[Belief]:
+        """Active beliefs for extractor context (SUPERSEDE targets)."""
+        active = self.store.list_by_scope(
+            scope_ids,
+            statuses={BeliefStatus.ACTIVE},
+        )
+        # Prefer recently updated
+        active.sort(key=lambda b: b.updated_at, reverse=True)
+        return active[: self.existing_for_extract_k]

mem01/embeddings/__init__.py

@@ -0,0 +1,7 @@
+"""Embedding providers. Read and write paths depend only on Embedder."""
+
+from mem01.embeddings.base import Embedder
+from mem01.embeddings.fake import FakeEmbedder
+from mem01.embeddings.openai_embedder import OpenAIEmbedder
+
+__all__ = ["Embedder", "FakeEmbedder", "OpenAIEmbedder"]

mem01/embeddings/base.py

@@ -0,0 +1,22 @@
+"""Embedder protocol — text → vector.
+
+Why an interface:
+- Tests use FakeEmbedder (no network, deterministic)
+- Production can use OpenAI / local models without changing apply_ops
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Embedder(Protocol):
+    def embed(self, text: str) -> list[float]:
+        """Return a fixed-dimension embedding for *text*."""
+        ...
+
+    @property
+    def dimensions(self) -> int:
+        """Vector size this embedder produces."""
+        ...

mem01/embeddings/fake.py

@@ -0,0 +1,40 @@
+"""Deterministic embedder for tests (no API keys).
+
+Maps text to a stable unit-ish vector via hashing tokens into buckets.
+Similar strings are not guaranteed close — for tests we often set expectations
+on ops/status, not semantic neighbors. When search order matters, tests can
+hand-seed embeddings via the store.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+
+
+class FakeEmbedder:
+    def __init__(self, dimensions: int = 32) -> None:
+        if dimensions < 4:
+            raise ValueError("dimensions must be >= 4")
+        self._dimensions = dimensions
+
+    @property
+    def dimensions(self) -> int:
+        return self._dimensions
+
+    def embed(self, text: str) -> list[float]:
+        tokens = re.findall(r"[a-z0-9]+", text.lower())
+        vec = [0.0] * self._dimensions
+        if not tokens:
+            # empty → tiny bias so vector is non-zero
+            vec[0] = 1.0
+            return vec
+        for tok in tokens:
+            h = hashlib.sha256(tok.encode("utf-8")).digest()
+            idx = int.from_bytes(h[:4], "big") % self._dimensions
+            sign = 1.0 if h[4] % 2 == 0 else -1.0
+            vec[idx] += sign
+        # L2 normalize
+        norm = math.sqrt(sum(x * x for x in vec)) or 1.0
+        return [x / norm for x in vec]

mem01/embeddings/openai_embedder.py

@@ -0,0 +1,83 @@
+"""OpenAI embeddings — mem0-style default embedder for real use.
+
+Uses POST /v1/embeddings (stdlib urllib). Requires OPENAI_API_KEY.
+Not free (usage-based); typically very cheap at small scale.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+
+
+class OpenAIEmbedder:
+    """text-embedding-3-small by default (same class of model mem0 uses)."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        model: str = "text-embedding-3-small",
+        base_url: str = "https://api.openai.com/v1",
+        dimensions: int | None = None,
+    ) -> None:
+        if api_key is None:
+            try:
+                from mem01.env import load_env
+
+                load_env()
+            except Exception:
+                pass
+            self.api_key = os.environ.get("OPENAI_API_KEY") or ""
+        else:
+            self.api_key = api_key
+        self.model = model
+        self.base_url = base_url.rstrip("/")
+        # text-embedding-3-small default dim is 1536; optional API matryoshka trim
+        self._dimensions = dimensions
+        self._resolved_dim: int | None = dimensions
+
+    @property
+    def dimensions(self) -> int:
+        if self._resolved_dim is not None:
+            return self._resolved_dim
+        # Known default until first call
+        return 1536
+
+    def embed(self, text: str) -> list[float]:
+        if not self.api_key:
+            raise RuntimeError("OpenAIEmbedder requires api_key or OPENAI_API_KEY")
+        body: dict = {
+            "model": self.model,
+            "input": text,
+        }
+        if self._dimensions is not None:
+            body["dimensions"] = self._dimensions
+
+        url = f"{self.base_url}/embeddings"
+        data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=data,
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.api_key}",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=60) as resp:
+                payload = json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", errors="replace")
+            raise RuntimeError(f"OpenAI embeddings error {e.code}: {detail}") from e
+
+        try:
+            vec = list(payload["data"][0]["embedding"])
+        except (KeyError, IndexError, TypeError) as e:
+            raise RuntimeError(f"unexpected embeddings response: {payload!r}") from e
+
+        self._resolved_dim = len(vec)
+        return vec