feat: add memorize and retrieve methods

Author: ankaisen

src/memu/app/__init__.py

@@ -0,0 +1,4 @@
+from .service import MemoryService
+from .settings import AppSettings
+
+__all__ = ["AppSettings", "MemoryService"]

src/memu/app/service.py

@@ -0,0 +1,74 @@
+from pydantic import BaseModel, Field
+
+from memu.prompts.memory_type import DEFAULT_MEMORY_TYPES
+from memu.prompts.memory_type import PROMPTS as DEFAULT_MEMORY_TYPE_PROMPTS
+
+
+def _default_memory_types() -> list[str]:
+    return list(DEFAULT_MEMORY_TYPES)
+
+
+def _default_memory_type_prompts() -> dict[str, str]:
+    return dict(DEFAULT_MEMORY_TYPE_PROMPTS)
+
+
+def _default_memory_categories() -> list[dict[str, str]]:
+    return [
+        {"name": "personal_info", "description": "Personal information about the user"},
+        {"name": "preferences", "description": "User preferences, likes and dislikes"},
+        {"name": "relationships", "description": "Information about relationships with others"},
+        {"name": "activities", "description": "Activities, hobbies, and interests"},
+        {"name": "goals", "description": "Goals, aspirations, and objectives"},
+        {"name": "experiences", "description": "Past experiences and events"},
+        {"name": "knowledge", "description": "Knowledge, facts, and learned information"},
+        {"name": "opinions", "description": "Opinions, viewpoints, and perspectives"},
+        {"name": "habits", "description": "Habits, routines, and patterns"},
+        {"name": "work_life", "description": "Work-related information and professional life"},
+    ]
+
+
+class AppSettings(BaseModel):
+    # where to store raw resources
+    resources_dir: str = Field(default="./resources")
+    # openai base
+    openai_base: str = Field(default="https://api.openai.com/v1")
+    openai_api_key_env: str = Field(default="OPENAI_API_KEY")
+    # models
+    chat_model: str = Field(default="gpt-4o-mini")
+    embed_model: str = Field(default="text-embedding-3-small")
+    llm_client_backend: str = Field(
+        default="httpx",
+        description="Which OpenAI client backend to use: 'httpx' (httpx) or 'sdk' (official OpenAI).",
+    )
+    llm_http_provider: str = Field(
+        default="openai",
+        description="Name of the HTTP LLM provider implementation (e.g. 'openai').",
+    )
+    llm_http_endpoints: dict[str, str] = Field(
+        default_factory=dict,
+        description="Optional overrides for HTTP endpoints (keys: 'chat'/'summary', 'embeddings'/'embed').",
+    )
+    # thresholds
+    category_assign_threshold: float = Field(default=0.25)
+    # summarization prompts
+    default_summary_prompt: str = Field(default="Summarize the text in one short paragraph.")
+    summary_prompts: dict[str, str] = Field(
+        default_factory=dict,
+        description="Optional mapping of modality -> summary system prompt.",
+    )
+    memory_categories: list[dict[str, str]] = Field(
+        default_factory=_default_memory_categories,
+        description="Global memory category definitions embedded at service startup.",
+    )
+    category_summary_target_length: int = Field(
+        default=400,
+        description="Target max length for auto-generated category summaries.",
+    )
+    memory_types: list[str] = Field(
+        default_factory=_default_memory_types,
+        description="Ordered list of memory types (profile/event/knowledge/behavior by default).",
+    )
+    memory_type_prompts: dict[str, str] = Field(
+        default_factory=_default_memory_type_prompts,
+        description="System prompt overrides for each memory type extraction.",
+    )

src/memu/app/settings.py

@@ -0,0 +1,5 @@
+# Re-export common backends for convenience.
+from .base import HTTPBackend
+from .openai import OpenAIHTTPBackend
+
+__all__ = ["HTTPBackend", "OpenAIHTTPBackend"]

src/memu/llm/backends/__init__.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class HTTPBackend:
+    """Defines how to talk to a specific HTTP LLM provider."""
+
+    name: str = "base"
+    summary_endpoint: str = "/chat/completions"
+    embedding_endpoint: str = "/embeddings"
+
+    def build_summary_payload(
+        self, *, text: str, system_prompt: str | None, chat_model: str, max_tokens: int
+    ) -> dict[str, Any]:
+        raise NotImplementedError
+
+    def parse_summary_response(self, data: dict[str, Any]) -> str:
+        raise NotImplementedError
+
+    def build_embedding_payload(self, *, inputs: list[str], embed_model: str) -> dict[str, Any]:
+        raise NotImplementedError
+
+    def parse_embedding_response(self, data: dict[str, Any]) -> list[list[float]]:
+        raise NotImplementedError

src/memu/llm/backends/base.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any, cast
+
+from .base import HTTPBackend
+
+
+class OpenAIHTTPBackend(HTTPBackend):
+    name = "openai"
+    summary_endpoint = "/chat/completions"
+    embedding_endpoint = "/embeddings"
+
+    def build_summary_payload(
+        self, *, text: str, system_prompt: str | None, chat_model: str, max_tokens: int
+    ) -> dict[str, Any]:
+        prompt = system_prompt or "Summarize the text in one short paragraph."
+        return {
+            "model": chat_model,
+            "messages": [
+                {"role": "system", "content": prompt},
+                {"role": "user", "content": text},
+            ],
+            "temperature": 0.2,
+            "max_tokens": max_tokens,
+        }
+
+    def parse_summary_response(self, data: dict[str, Any]) -> str:
+        return cast(str, data["choices"][0]["message"]["content"])
+
+    def build_embedding_payload(self, *, inputs: list[str], embed_model: str) -> dict[str, Any]:
+        return {"model": embed_model, "input": inputs}
+
+    def parse_embedding_response(self, data: dict[str, Any]) -> list[list[float]]:
+        return [cast(list[float], d["embedding"]) for d in data["data"]]

src/memu/llm/backends/openai.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from typing import cast
+
+import httpx
+import numpy as np
+
+from memu.llm.backends.base import HTTPBackend
+from memu.llm.backends.openai import OpenAIHTTPBackend
+
+HTTP_BACKENDS: dict[str, Callable[[], HTTPBackend]] = {
+    OpenAIHTTPBackend.name: OpenAIHTTPBackend,
+}
+
+
+class HTTPLLMClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        chat_model: str,
+        embed_model: str,
+        provider: str = "openai",
+        endpoint_overrides: dict[str, str] | None = None,
+        timeout: int = 60,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key or ""
+        self.chat_model = chat_model
+        self.embed_model = embed_model
+        self.provider = provider.lower()
+        self.backend = self._load_backend(self.provider)
+        overrides = endpoint_overrides or {}
+        self.summary_endpoint = overrides.get("chat") or overrides.get("summary") or self.backend.summary_endpoint
+        self.embedding_endpoint = (
+            overrides.get("embeddings")
+            or overrides.get("embedding")
+            or overrides.get("embed")
+            or self.backend.embedding_endpoint
+        )
+        self.fake = bool(os.getenv("MEMUFLOW_FAKE_OPENAI")) or not bool(self.api_key)
+        self.timeout = timeout
+
+    async def summarize(self, text: str, max_tokens: int = 160, system_prompt: str | None = None) -> str:
+        if self.fake:
+            s = " ".join(text.strip().split())
+            return s[:200] + ("..." if len(s) > 200 else "")
+
+        payload = self.backend.build_summary_payload(
+            text=text, system_prompt=system_prompt, chat_model=self.chat_model, max_tokens=max_tokens
+        )
+        async with httpx.AsyncClient(base_url=self.base_url, timeout=self.timeout) as client:
+            resp = await client.post(self.summary_endpoint, json=payload, headers=self._headers())
+            resp.raise_for_status()
+            data = resp.json()
+        return self.backend.parse_summary_response(data)
+
+    async def embed(self, inputs: list[str]) -> list[list[float]]:
+        if self.fake:
+            return [self._fake_vec(x) for x in inputs]
+        payload = self.backend.build_embedding_payload(inputs=inputs, embed_model=self.embed_model)
+        async with httpx.AsyncClient(base_url=self.base_url, timeout=self.timeout) as client:
+            resp = await client.post(self.embedding_endpoint, json=payload, headers=self._headers())
+            resp.raise_for_status()
+            data = resp.json()
+        return self.backend.parse_embedding_response(data)
+
+    def _headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+    def _fake_vec(self, s: str, dim: int = 256) -> list[float]:
+        import hashlib
+
+        h = hashlib.sha256(s.encode("utf-8")).digest()
+        b = (h * (dim // len(h) + 1))[:dim]
+        arr = np.frombuffer(b, dtype=np.uint8).astype(np.float32)
+        arr = (arr - arr.mean()) / (arr.std() + 1e-6)
+        arr = arr / (np.linalg.norm(arr) + 1e-9)
+        return cast(list[float], arr.tolist())
+
+    def _load_backend(self, provider: str) -> HTTPBackend:
+        factory = HTTP_BACKENDS.get(provider)
+        if not factory:
+            msg = f"Unsupported HTTP LLM provider '{provider}'. Available: {', '.join(HTTP_BACKENDS.keys())}"
+            raise ValueError(msg)
+        return factory()

src/memu/llm/http_client.py

@@ -0,0 +1,77 @@
+import os
+from typing import TYPE_CHECKING, cast
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from openai import AsyncOpenAI  # 只给类型检查用
+
+try:
+    import openai
+except ImportError:
+    openai = None  # 运行时用来判断有没有这个库
+
+
+class OpenAISDKClient:
+    """OpenAI client that relies on the official Python SDK."""
+
+    def __init__(self, *, base_url: str, api_key: str, chat_model: str, embed_model: str):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key or ""
+        self.chat_model = chat_model
+        self.embed_model = embed_model
+        self.fake = bool(os.getenv("MEMUFLOW_FAKE_OPENAI")) or not bool(self.api_key)
+        self.client: AsyncOpenAI | None = None
+        if self.fake:
+            self.client = None
+        else:
+            if openai is None:
+                msg = "The 'openai' Python package is required for the SDK client. Install it via `pip install openai` or switch to the httpx backend."
+                raise RuntimeError(msg)
+            self.client = openai.AsyncOpenAI(api_key=self.api_key, base_url=self.base_url)
+
+    async def summarize(
+        self,
+        text: str,
+        *,
+        max_tokens: int = 160,
+        system_prompt: str | None = None,
+    ) -> str:
+        prompt = system_prompt or "Summarize the text in one short paragraph."
+        if self.fake:
+            s = " ".join(text.strip().split())
+            return s[:200] + ("..." if len(s) > 200 else "")
+        if self.client is None:
+            msg = "The 'openai' Python package is required for the SDK client. Install it via `pip install openai` or switch to the httpx backend."
+            raise RuntimeError(msg)
+        response = await self.client.chat.completions.create(
+            model=self.chat_model,
+            messages=[
+                {"role": "system", "content": prompt},
+                {"role": "user", "content": text},
+            ],
+            temperature=0.2,
+            max_tokens=max_tokens,
+        )
+        content = response.choices[0].message.content
+        return content or ""
+
+    async def embed(self, inputs: list[str]) -> list[list[float]]:
+        if self.fake:
+            return [self._fake_vec(x) for x in inputs]
+        if self.client is None:
+            msg = "The 'openai' Python package is required for the SDK client. Install it via `pip install openai` or switch to the httpx backend."
+            raise RuntimeError(msg)
+        response = await self.client.embeddings.create(model=self.embed_model, input=inputs)
+        return [cast(list[float], d.embedding) for d in response.data]
+
+    def _fake_vec(self, s: str, dim: int = 256) -> list[float]:
+        # deterministic pseudo-embedding for offline demo
+        import hashlib
+
+        h = hashlib.sha256(s.encode("utf-8")).digest()
+        b = (h * (dim // len(h) + 1))[:dim]
+        arr = np.frombuffer(b, dtype=np.uint8).astype(np.float32)
+        arr = (arr - arr.mean()) / (arr.std() + 1e-6)
+        arr = arr / (np.linalg.norm(arr) + 1e-9)
+        return arr.tolist()

src/memu/llm/openai_sdk.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import uuid
+
+from memu.models import CategoryItem, MemoryCategory, MemoryItem, MemoryType, Resource
+
+
+class InMemoryStore:
+    def __init__(self) -> None:
+        self.resources: dict[str, Resource] = {}
+        self.items: dict[str, MemoryItem] = {}
+        self.categories: dict[str, MemoryCategory] = {}
+        self.relations: list[CategoryItem] = []
+
+    def create_resource(self, *, url: str, modality: str, local_path: str) -> Resource:
+        rid = str(uuid.uuid7())
+        res = Resource(id=rid, url=url, modality=modality, local_path=local_path)
+        self.resources[rid] = res
+        return res
+
+    def get_or_create_category(self, *, name: str, description: str, embedding: list[float]) -> MemoryCategory:
+        for c in self.categories.values():
+            if c.name == name:
+                if not c.embedding:
+                    c.embedding = embedding
+                if not c.description:
+                    c.description = description
+                return c
+        cid = str(uuid.uuid7())
+        cat = MemoryCategory(id=cid, name=name, description=description, embedding=embedding)
+        self.categories[cid] = cat
+        return cat
+
+    def create_item(
+        self, *, resource_id: str, memory_type: MemoryType, summary: str, embedding: list[float]
+    ) -> MemoryItem:
+        mid = str(uuid.uuid7())
+        it = MemoryItem(
+            id=mid,
+            resource_id=resource_id,
+            memory_type=memory_type,
+            summary=summary,
+            embedding=embedding,
+            category_ids=[],
+        )
+        self.items[mid] = it
+        return it
+
+    def link_item_category(self, item_id: str, cat_id: str) -> CategoryItem:
+        it = self.items[item_id]
+        if cat_id not in it.category_ids:
+            it.category_ids.append(cat_id)
+        rel = CategoryItem(item_id=item_id, category_id=cat_id)
+        self.relations.append(rel)
+        return rel