memcore-sdk 0.3.0__py3-none-any.whl

memcore/__init__.py

@@ -0,0 +1,15 @@
+"""memcore — 通用记忆内核的 Python SDK。
+
+    from memcore import Memcore
+    mc = Memcore(api_key="mk_live_...")
+    user = mc.subject("user-42")
+    user.remember("我住在上海")
+    print(user.recall("我住在哪").as_prompt())
+"""
+
+from memcore.client import AsyncMemcore, AsyncSubject, Memcore, Subject
+from memcore.models import MemcoreError, Memory, Profile, ProfileSlot, RecallResult, Why
+
+__version__ = "0.3.0"
+__all__ = ["Memcore", "AsyncMemcore", "Subject", "AsyncSubject", "Memory", "Profile",
+           "ProfileSlot", "RecallResult", "Why", "MemcoreError"]

memcore/client.py

@@ -0,0 +1,338 @@
+"""memcore Python SDK。
+
+    from memcore import Memcore
+
+    mc = Memcore(api_key="mk_live_...")
+    user = mc.subject("user-42")          # 绑定主体,省得每次都传
+
+    user.remember("我住在上海,在做数据库产品")
+    hits = user.recall("他住在哪", explain=True)
+    print(hits.as_prompt())               # 直接塞进你的 system prompt
+
+设计取舍:
+- 同步 `Memcore` 与异步 `AsyncMemcore` 对等,方法名完全一致
+- `subject()` 返回绑定主体的句柄——绝大多数调用都是"针对某个用户",不该重复传参
+- 只依赖 httpx;返回轻量 dataclass,不给调用方塞 pydantic
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from memcore.models import MemcoreError, Memory, Profile, RecallResult
+
+DEFAULT_BASE_URL = os.environ.get("MEMCORE_BASE_URL", "https://api.reglos.ai")
+_TIMEOUT = 30.0
+
+
+def _params(subject: str, **kw) -> dict:
+    out: dict[str, Any] = {"subject": subject}
+    for k, v in kw.items():
+        if v is None or v is False:
+            continue
+        out[k] = v.isoformat() if isinstance(v, datetime) else v
+    return out
+
+
+def _check(r: httpx.Response) -> dict:
+    if r.status_code >= 400:
+        try:
+            msg = r.json().get("detail", r.text)
+        except Exception:
+            msg = r.text
+        raise MemcoreError(r.status_code, str(msg))
+    return r.json()
+
+
+class _BaseSubject:
+    """绑定了某个主体的句柄。所有方法都不必再传 subject。"""
+
+    def __init__(self, client, subject_id: str, subject_type: str = "user"):
+        self._c = client
+        self.subject_id = subject_id
+        self.subject_type = subject_type
+
+    def _p(self, **kw) -> dict:
+        return _params(self.subject_id, subject_type=self.subject_type, **kw)
+
+
+class Subject(_BaseSubject):
+    """同步句柄。"""
+
+    # ---------------------------------------------------------- 写入
+    def remember(
+        self,
+        text: str | None = None,
+        *,
+        messages: list[dict] | None = None,
+        facts: list[dict] | None = None,
+        session_id: str | None = None,
+        sync: bool = False,
+    ) -> dict:
+        """写入记忆。
+
+        text     最常用:一段自然语言
+        messages 对话形式 [{"role","content","at"}];`at` 用于回灌历史(相对时间才解析得对)
+        facts    直接写结构化事实(客户已有自己的抽取时用)
+        sync     True = 同步抽取完再返回(写完立刻可查,代价是延迟)
+        """
+        body: dict[str, Any] = {}
+        if text is not None:
+            body["text"] = text
+        if messages:
+            body["messages"] = messages
+        if facts:
+            body["facts"] = facts
+        if session_id:
+            body["session_id"] = session_id
+        return _check(
+            self._c._http.post(
+                "/v1/remember", params=self._p(mode="sync" if sync else "async"), json=body
+            )
+        )
+
+    def remember_file(self, path: str | Path) -> dict:
+        """文档/图片入记忆。图片走 VLM 双路(描述 + OCR);
+        通用内容只进可检索索引,只有关于该主体的少量事实进画像。"""
+        p = Path(path)
+        with p.open("rb") as fh:
+            return _check(
+                self._c._http.post(
+                    "/v1/documents", params=self._p(), files={"file": (p.name, fh)}
+                )
+            )
+
+    # ---------------------------------------------------------- 检索
+    def recall(
+        self,
+        query: str,
+        *,
+        limit: int | None = None,
+        explain: bool = False,
+        topic: str | None = None,
+        since: datetime | None = None,
+        until: datetime | None = None,
+        source: str | None = None,
+        min_confidence: float | None = None,
+        layers: str = "facts,summaries,documents",
+    ) -> RecallResult:
+        """检索记忆。`explain=True` 会为每条附上"为什么被选中"(命中路径、排名、
+        RRF 贡献、有效期状态)与预算统计——调试与合规都用得上。"""
+        return RecallResult._from(
+            _check(
+                self._c._http.get(
+                    "/v1/recall",
+                    params=self._p(
+                        q=query, limit=limit, explain=explain, topic=topic, since=since,
+                        until=until, source=source, min_confidence=min_confidence,
+                        include_layers=layers,
+                    ),
+                )
+            )
+        )
+
+    def messages(self, *, limit: int = 50, session_id: str | None = None) -> list[dict]:
+        """按**时间顺序**读回最近的消息(旧 → 新)。
+
+        与 `recall` 的分野:`recall` 回答「关于这个问题,我们记得什么」
+        (抽取后的事实,按相关性排序);这里回答「这个人说过什么」
+        (原始消息,按时间排序)。**对话历史不能用检索排序冒充。**
+        """
+        return _check(
+            self._c._http.get(
+                "/v1/messages", params=self._p(limit=limit, session_id=session_id)
+            )
+        ).get("messages", [])
+
+    # ---------------------------------------------------------- 画像
+    def profile(self) -> Profile:
+        return Profile._from(_check(self._c._http.get("/v1/profile", params=self._p())))
+
+    def ask(self, question: str) -> dict:
+        """自然语言问画像:不必理解我们的槽位结构。返回 {answer, based_on}。"""
+        return _check(
+            self._c._http.post("/v1/profile/ask", params=self._p(), json={"question": question})
+        )
+
+    # ---------------------------------------------------------- 遗忘
+    def forget(
+        self,
+        memory_id: str | None = None,
+        *,
+        session_id: str | None = None,
+        everything: bool = False,
+        reason: str | None = None,
+    ) -> dict:
+        """三种语义严格区分:
+        memory_id  抽错了 → 作废,查询不再命中,但保留痕迹可回溯
+        session_id 删一整段会话 → 级联清掉派生事实与向量,不留幽灵
+        everything 全清(删除权)→ 返回可存档的删除回执
+        """
+        body: dict[str, Any] = {"reason": reason}
+        if memory_id:
+            body["memory_id"] = memory_id
+        elif session_id:
+            body["session_id"] = session_id
+        elif everything:
+            body.update({"all": True, "confirm": self.subject_id})
+        else:
+            raise ValueError("memory_id / session_id / everything 三选一")
+        return _check(self._c._http.post("/v1/forget", params=self._p(), json=body))
+
+    # ---------------------------------------------------------- 溯源与审计
+    def explain(self, memory_id: str) -> dict:
+        """这条记忆怎么来的:原始出处、生成记录(模型 + prompt 哈希)、被谁取代。"""
+        return _check(
+            self._c._http.get(f"/v1/memories/{memory_id}/explain", params=self._p())
+        )
+
+    def audit(self, *, since: datetime | None = None, action: str | None = None,
+              limit: int = 200) -> list[dict]:
+        """审计账本:谁在何时改了哪条、为什么。"""
+        return _check(
+            self._c._http.get("/v1/audit", params=self._p(since=since, action=action, limit=limit))
+        )["entries"]
+
+
+class Memcore:
+    """同步客户端。线程安全:内部 httpx.Client 可复用。"""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = _TIMEOUT,
+    ):
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers={"X-API-Key": api_key} if api_key else {},
+        )
+
+    def subject(self, subject_id: str, subject_type: str = "user") -> Subject:
+        """绑定一个记忆主体(终端用户 / Agent / 团队)。"""
+        return Subject(self, subject_id, subject_type)
+
+    def health(self) -> dict:
+        return _check(self._http.get("/healthz"))
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Memcore:
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+
+class AsyncSubject(_BaseSubject):
+    """异步句柄,方法与 Subject 一一对应。"""
+
+    async def remember(self, text=None, *, messages=None, facts=None,
+                       session_id=None, sync=False) -> dict:
+        body: dict[str, Any] = {}
+        if text is not None:
+            body["text"] = text
+        if messages:
+            body["messages"] = messages
+        if facts:
+            body["facts"] = facts
+        if session_id:
+            body["session_id"] = session_id
+        return _check(
+            await self._c._http.post(
+                "/v1/remember", params=self._p(mode="sync" if sync else "async"), json=body
+            )
+        )
+
+    async def remember_file(self, path: str | Path) -> dict:
+        p = Path(path)
+        with p.open("rb") as fh:
+            return _check(
+                await self._c._http.post(
+                    "/v1/documents", params=self._p(), files={"file": (p.name, fh)}
+                )
+            )
+
+    async def recall(self, query: str, *, limit=None, explain=False, topic=None, since=None,
+                     until=None, source=None, min_confidence=None,
+                     layers="facts,summaries,documents") -> RecallResult:
+        return RecallResult._from(
+            _check(
+                await self._c._http.get(
+                    "/v1/recall",
+                    params=self._p(q=query, limit=limit, explain=explain, topic=topic,
+                                   since=since, until=until, source=source,
+                                   min_confidence=min_confidence, include_layers=layers),
+                )
+            )
+        )
+
+    async def profile(self) -> Profile:
+        return Profile._from(_check(await self._c._http.get("/v1/profile", params=self._p())))
+
+    async def ask(self, question: str) -> dict:
+        return _check(
+            await self._c._http.post(
+                "/v1/profile/ask", params=self._p(), json={"question": question}
+            )
+        )
+
+    async def forget(self, memory_id=None, *, session_id=None, everything=False,
+                     reason=None) -> dict:
+        body: dict[str, Any] = {"reason": reason}
+        if memory_id:
+            body["memory_id"] = memory_id
+        elif session_id:
+            body["session_id"] = session_id
+        elif everything:
+            body.update({"all": True, "confirm": self.subject_id})
+        else:
+            raise ValueError("memory_id / session_id / everything 三选一")
+        return _check(await self._c._http.post("/v1/forget", params=self._p(), json=body))
+
+    async def explain(self, memory_id: str) -> dict:
+        return _check(
+            await self._c._http.get(f"/v1/memories/{memory_id}/explain", params=self._p())
+        )
+
+    async def audit(self, *, since=None, action=None, limit=200) -> list[dict]:
+        return _check(
+            await self._c._http.get(
+                "/v1/audit", params=self._p(since=since, action=action, limit=limit)
+            )
+        )["entries"]
+
+
+class AsyncMemcore:
+    def __init__(self, api_key: str | None = None, base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = _TIMEOUT):
+        self._http = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers={"X-API-Key": api_key} if api_key else {},
+        )
+
+    def subject(self, subject_id: str, subject_type: str = "user") -> AsyncSubject:
+        return AsyncSubject(self, subject_id, subject_type)
+
+    async def health(self) -> dict:
+        return _check(await self._http.get("/healthz"))
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncMemcore:
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.aclose()
+
+
+__all__ = ["Memcore", "AsyncMemcore", "Memory", "Profile", "RecallResult", "MemcoreError"]

memcore/integrations/__init__.py

@@ -0,0 +1,36 @@
+"""框架适配:LangChain / LlamaIndex。
+
+## 为什么单独放一个子包
+
+这些适配**不能**成为 SDK 的必需依赖 —— 装个记忆 SDK 顺带拖进整个 LangChain,
+对不用它的人是纯粹的负担。所以:
+
+- `pyproject.toml` 里做成 optional extras(`memcore-sdk[langchain]`)
+- 每个模块在**导入时**才 import 框架,没装就抛一句能读懂的话,
+  而不是 `ModuleNotFoundError: No module named 'langchain_core'` 让人自己猜
+
+## 两个框架各自的接入点
+
+| | LangChain | LlamaIndex |
+| --- | --- | --- |
+| 拿记忆当检索源 | `MemcoreRetriever`(`BaseRetriever`) | `MemcoreRetriever`(`BaseRetriever`) |
+| 拿记忆当对话历史 | `MemcoreChatMessageHistory` | `MemcoreMemory`(`BaseMemory`) |
+
+**两者的语义差别要清楚**:检索器回答"关于这个问题,我们记得什么";
+对话历史回答"这个人跟我说过什么"。前者是抽取后的事实,后者是原始消息。
+混用会让上下文里出现同一件事的两个版本。
+"""
+
+__all__ = ["require"]
+
+
+def require(module: str, extra: str) -> None:
+    """检查框架是否可用,不可用时抛一句能直接照做的话。"""
+    import importlib.util
+
+    if importlib.util.find_spec(module) is None:
+        raise ImportError(
+            f"需要 {module},但它没有安装。\n"
+            f"    pip install 'memcore-sdk[{extra}]'\n"
+            f"  或直接:pip install {module}"
+        )

memcore/integrations/langchain.py

@@ -0,0 +1,180 @@
+"""LangChain 适配。
+
+    pip install 'memcore-sdk[langchain]'
+
+两个接入点,语义不同,**别混用**:
+
+    MemcoreRetriever          「关于这个问题,我们记得什么」→ 抽取后的事实
+    MemcoreChatMessageHistory 「这个人跟我说过什么」        → 原始消息
+
+同时塞进上下文会让同一件事出现两个版本(一条事实 + 它的原始出处),
+既浪费预算又容易让模型自相矛盾。要长期记忆用前者,要多轮上下文用后者。
+
+## 用法
+
+```python
+from memcore import Memcore
+from memcore.integrations.langchain import MemcoreRetriever, MemcoreChatMessageHistory
+
+mc = Memcore(api_key="mk_live_…", base_url="https://your-host")
+
+# ① 当检索器用
+retriever = MemcoreRetriever(subject=mc.subject("alice"), k=8)
+chain = {"context": retriever, "question": RunnablePassthrough()} | prompt | llm
+
+# ② 当对话历史用
+chain_with_history = RunnableWithMessageHistory(
+    chain,
+    lambda sid: MemcoreChatMessageHistory(subject=mc.subject(sid)),
+    input_messages_key="question",
+    history_messages_key="history",
+)
+```
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from memcore.integrations import require
+
+require("langchain_core", "langchain")
+
+from langchain_core.callbacks import CallbackManagerForRetrieverRun  # noqa: E402
+from langchain_core.chat_history import BaseChatMessageHistory  # noqa: E402
+from langchain_core.documents import Document  # noqa: E402
+from langchain_core.messages import (  # noqa: E402
+    AIMessage,
+    BaseMessage,
+    HumanMessage,
+    SystemMessage,
+)
+from langchain_core.retrievers import BaseRetriever  # noqa: E402
+
+
+def _to_document(m: Any) -> Document:
+    """一条记忆 → 一个 Document。
+
+    **`page_content` 只放陈述本身**,时间、来源、为什么被选中全进 metadata ——
+    把它们拼进正文会污染下游的相似度计算与去重(很多链会对 page_content 做二次处理)。
+    """
+    meta: dict[str, Any] = {
+        "id": m.id,
+        "source": "memcore",
+        "topic": m.topic,
+        "valid_from": m.valid_from,
+        "valid_to": m.valid_to,
+        # 这条是不是仍然有效。False 表示已被更新的事实取代 ——
+        # 仍是历史真相,但下游若要"当前状态"就该过滤掉
+        "is_current": m.is_current,
+        "provenance": m.provenance,
+    }
+    if m.score is not None:
+        meta["score"] = m.score
+    if m.explain_url:
+        # 可解释性是我们的差异化 —— 把入口一路带到 Document 上,
+        # 下游要追"这条为什么被选中"时不用回头查
+        meta["explain_url"] = m.explain_url
+    return Document(page_content=m.statement, metadata=meta)
+
+
+class MemcoreRetriever(BaseRetriever):
+    """把 memcore 当 LangChain 检索器用。
+
+    与向量库检索器的区别:返回的是**抽取后的事实**,不是原文分块。
+    所以条数少、密度高,`k` 通常比向量库小一个量级。
+    """
+
+    subject: Any
+    """`memcore.Memcore(...).subject("alice")` 拿到的对象。"""
+
+    k: int = 8
+    """取多少条。"""
+
+    topic: str | None = None
+    """只取某个主题(可选)。"""
+
+    min_confidence: float | None = None
+
+    current_only: bool = True
+    """是否只要仍然有效的事实。**默认 True** —— 多数链要的是"现在是什么",
+    而账本里保留着被取代的历史版本;不过滤会让模型同时看到新旧两个说法。"""
+
+    # 允许 Subject 这种任意对象作为字段值
+    model_config = {"arbitrary_types_allowed": True}
+
+    def _get_relevant_documents(
+        self, query: str, *, run_manager: CallbackManagerForRetrieverRun
+    ) -> list[Document]:
+        res = self.subject.recall(
+            query, limit=self.k, topic=self.topic, min_confidence=self.min_confidence
+        )
+        facts = list(res.facts)
+        if self.current_only:
+            facts = [f for f in facts if f.is_current]
+        return [_to_document(f) for f in facts[: self.k]]
+
+
+class MemcoreChatMessageHistory(BaseChatMessageHistory):
+    """把 memcore 当 LangChain 的对话历史用(`RunnableWithMessageHistory`)。
+
+    ## 与普通历史存储的两点不同
+
+    **一、写入是异步抽取的。** `add_messages` 落库即返回,事实抽取在后台队列进行。
+    所以刚写完立刻 `recall` 未必查得到那条事实 —— 但 `messages` 读的是原始消息,
+    不受影响。要写完立刻可查,用 `sync=True`(代价是延迟)。
+
+    **二、`clear()` 是真的删。** 它调 `/v1/forget` 清掉该主体的全部记忆,
+    **不可撤销**。LangChain 的语义里 clear 只是清一个会话的历史,
+    而我们这里没有"只清历史不清记忆"的中间态 —— 所以默认**拒绝执行**,
+    必须显式 `allow_destructive_clear=True` 才动手。
+    宁可让人多写一个参数,也不能让一次误调用清空某个人的全部记忆。
+    """
+
+    def __init__(
+        self,
+        subject: Any,
+        *,
+        limit: int = 50,
+        sync: bool = False,
+        allow_destructive_clear: bool = False,
+    ) -> None:
+        self.subject = subject
+        self.limit = limit
+        self.sync = sync
+        self.allow_destructive_clear = allow_destructive_clear
+
+    @property
+    def messages(self) -> list[BaseMessage]:
+        """读回原始消息。取不到就返回空 —— 历史缺失不该让整条链挂掉。"""
+        try:
+            raw = self.subject.messages(limit=self.limit)
+        except Exception:  # noqa: BLE001
+            # 历史读不回来不该让整条链挂掉 —— 退化成"没有历史"
+            return []
+        out: list[BaseMessage] = []
+        for m in raw:
+            role, content = m.get("role"), m.get("content") or ""
+            if role == "assistant":
+                out.append(AIMessage(content=content))
+            elif role == "system":
+                out.append(SystemMessage(content=content))
+            else:
+                out.append(HumanMessage(content=content))
+        return out
+
+    def add_messages(self, messages: list[BaseMessage]) -> None:
+        payload = []
+        for m in messages:
+            role = {"ai": "assistant", "human": "user", "system": "system"}.get(m.type, "user")
+            payload.append({"role": role, "content": str(m.content)})
+        if payload:
+            self.subject.remember(messages=payload, sync=self.sync)
+
+    def clear(self) -> None:
+        if not self.allow_destructive_clear:
+            raise RuntimeError(
+                "clear() 会清空该主体的**全部记忆**(不只是本次会话的历史),且不可撤销。\n"
+                "确实要这么做,请构造时传 allow_destructive_clear=True。"
+            )
+        self.subject.forget(everything=True)

memcore/integrations/llama_index.py

@@ -0,0 +1,198 @@
+"""LlamaIndex 适配。
+
+    pip install 'memcore-sdk[llamaindex]'
+
+两个接入点,语义不同,**别混用**(同 LangChain 那边):
+
+    MemcoreRetriever 「关于这个问题,我们记得什么」→ 抽取后的事实,按相关性
+    MemcoreMemory    「这个人说过什么」            → 原始消息,按时间
+
+## 用法
+
+```python
+from memcore import Memcore
+from memcore.integrations.llama_index import MemcoreRetriever, MemcoreMemory
+
+mc = Memcore(api_key="mk_live_…", base_url="https://your-host")
+subject = mc.subject("alice")
+
+# ① 当检索器用(可直接进 RetrieverQueryEngine)
+retriever = MemcoreRetriever(subject=subject, k=8)
+nodes = retriever.retrieve("我最喜欢什么乐器?")
+
+# ② 当 ChatEngine 的记忆用
+memory = MemcoreMemory.from_defaults(subject=subject)
+```
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from memcore.integrations import require
+
+require("llama_index.core", "llamaindex")
+
+from llama_index.core.base.llms.types import ChatMessage, MessageRole  # noqa: E402
+from llama_index.core.memory import BaseMemory  # noqa: E402
+from llama_index.core.retrievers import BaseRetriever  # noqa: E402
+from llama_index.core.schema import NodeWithScore, QueryBundle, TextNode  # noqa: E402
+
+_ROLE_IN = {"assistant": MessageRole.ASSISTANT, "system": MessageRole.SYSTEM,
+            "user": MessageRole.USER}
+_ROLE_OUT = {MessageRole.ASSISTANT: "assistant", MessageRole.SYSTEM: "system",
+             MessageRole.USER: "user"}
+
+
+def _to_node(m: Any) -> NodeWithScore:
+    """一条记忆 → 一个 NodeWithScore。
+
+    `text` 只放陈述本身,其余进 metadata —— 与 LangChain 那边同样的理由:
+    把时间、来源拼进正文会污染下游的相似度与去重。
+
+    **`excluded_llm_metadata_keys` 要设。** LlamaIndex 默认会把 metadata
+    一并渲染进给 LLM 的文本里,`id` / `explain_url` 这些对回答毫无帮助,
+    白占上下文预算;但它们要留给调用方做溯源,所以是"排除渲染"而不是不写。
+    """
+    meta = {
+        "id": m.id,
+        "source": "memcore",
+        "topic": m.topic,
+        "valid_from": m.valid_from,
+        "valid_to": m.valid_to,
+        "is_current": m.is_current,
+        "explain_url": m.explain_url,
+    }
+    node = TextNode(
+        id_=m.id or None,
+        text=m.statement,
+        metadata={k: v for k, v in meta.items() if v is not None},
+        excluded_llm_metadata_keys=["id", "explain_url", "source"],
+        excluded_embed_metadata_keys=["id", "explain_url", "source"],
+    )
+    return NodeWithScore(node=node, score=m.score)
+
+
+class MemcoreRetriever(BaseRetriever):
+    """把 memcore 当 LlamaIndex 检索器用。
+
+    与向量索引检索器的区别:返回的是**抽取后的事实**,不是原文分块 ——
+    条数少、密度高,`k` 通常比向量库小一个量级。
+    """
+
+    def __init__(
+        self,
+        subject: Any,
+        *,
+        k: int = 8,
+        topic: str | None = None,
+        min_confidence: float | None = None,
+        current_only: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        self._subject = subject
+        self._k = k
+        self._topic = topic
+        self._min_confidence = min_confidence
+        # 只要仍然有效的事实。**默认 True** —— 账本里保留着被取代的历史版本,
+        # 不过滤会让模型同时看到新旧两个说法。
+        self._current_only = current_only
+        super().__init__(**kwargs)
+
+    def _retrieve(self, query_bundle: QueryBundle) -> list[NodeWithScore]:
+        res = self._subject.recall(
+            query_bundle.query_str, limit=self._k,
+            topic=self._topic, min_confidence=self._min_confidence,
+        )
+        facts = list(res.facts)
+        if self._current_only:
+            facts = [f for f in facts if f.is_current]
+        return [_to_node(f) for f in facts[: self._k]]
+
+
+class MemcoreMemory(BaseMemory):
+    """把 memcore 当 LlamaIndex 的对话记忆用。
+
+    ## 与 `ChatMemoryBuffer` 的三点不同
+
+    **一、跨进程、跨设备。** 记忆在服务端,换台机器、换个端都还在 ——
+    `ChatMemoryBuffer` 是进程内的。
+
+    **二、`put` 是异步抽取的。** 落库即返回,事实抽取在后台队列进行。
+    `get()` 读的是原始消息,不受影响。
+
+    **三、`reset()` 默认拒绝执行。** LlamaIndex 的语义里 reset 只是清一段会话,
+    而我们这里它会清掉该主体的**全部记忆**且不可撤销。所以必须显式
+    `allow_destructive_reset=True`。宁可让人多写一个参数,
+    也不能让一次误调用清空某个人的全部记忆。
+    """
+
+    # BaseMemory 是 pydantic 模型;这些字段要声明才存得住
+    subject: Any = None
+    limit: int = 50
+    sync: bool = False
+    allow_destructive_reset: bool = False
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    @classmethod
+    def class_name(cls) -> str:
+        return "MemcoreMemory"
+
+    @classmethod
+    def from_defaults(cls, **kwargs: Any) -> MemcoreMemory:  # type: ignore[override]
+        subject = kwargs.pop("subject", None)
+        if subject is None:
+            raise ValueError("MemcoreMemory 需要 subject=Memcore(...).subject('<id>')")
+        return cls(subject=subject, **kwargs)
+
+    def get(self, input: str | None = None, **kwargs: Any) -> list[ChatMessage]:
+        """LlamaIndex 会用它取"要喂给模型的历史"。这里按时间顺序返回原始消息。
+
+        `input` 参数没用上是**有意的**:它是给"按当前输入裁剪历史"这类实现用的,
+        而我们这里若按 input 去检索,返回的就不是历史而是检索结果 ——
+        那正是 `MemcoreRetriever` 的活。两者混在一个对象里会让上下文出现
+        同一件事的两个版本。
+        """
+        return self.get_all()
+
+    def get_all(self) -> list[ChatMessage]:
+        try:
+            raw = self.subject.messages(limit=self.limit)
+        except Exception:  # noqa: BLE001
+            # 历史读不回来不该让整个 ChatEngine 挂掉 —— 退化成"没有历史"
+            return []
+        return [
+            ChatMessage(
+                role=_ROLE_IN.get(m.get("role") or "user", MessageRole.USER),
+                content=m.get("content") or "",
+            )
+            for m in raw
+        ]
+
+    def put(self, message: ChatMessage) -> None:
+        role = _ROLE_OUT.get(message.role, "user")
+        content = message.content or ""
+        if not content:
+            return
+        self.subject.remember(messages=[{"role": role, "content": content}], sync=self.sync)
+
+    def set(self, messages: list[ChatMessage]) -> None:
+        """LlamaIndex 用它整体覆盖历史。
+
+        **我们做不到"覆盖"** —— 账本是 ADD-only,事实永不改写。
+        所以这里退化成"把这些消息追加进去",并且**只追加库里还没有的那些**
+        (按内容比对最近一段),避免每轮把整段历史重复写一遍。
+        """
+        existing = {(m.role, m.content) for m in self.get_all()}
+        for m in messages:
+            if (m.role, m.content or "") not in existing:
+                self.put(m)
+
+    def reset(self) -> None:
+        if not self.allow_destructive_reset:
+            raise RuntimeError(
+                "reset() 会清空该主体的**全部记忆**(不只是本次会话),且不可撤销。\n"
+                "确实要这么做,请构造时传 allow_destructive_reset=True。"
+            )
+        self.subject.forget(everything=True)

memcore/models.py

@@ -0,0 +1,131 @@
+"""SDK 返回类型。用轻量 dataclass 而非 pydantic——SDK 不该给调用方塞依赖。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Why:
+    """一条记忆"为什么被检索到"。只有 explain=True 时才有。"""
+
+    matched_paths: dict[str, Any] = field(default_factory=dict)  # 命中的检索路及排名
+    rrf_contribution: dict[str, float] = field(default_factory=dict)  # 各路对最终分的贡献
+    validity: dict[str, Any] = field(default_factory=dict)  # current / superseded + 有效期
+    confidence: float | None = None
+    confirmed_times: int | None = None
+
+
+@dataclass
+class Memory:
+    id: str
+    statement: str
+    score: float | None = None
+    topic: str | None = None
+    valid_from: str | None = None
+    valid_to: str | None = None
+    provenance: str | None = None
+    why: Why | None = None
+    explain_url: str | None = None
+
+    @property
+    def is_current(self) -> bool:
+        """False 表示这条已被更新的事实取代(但仍是历史真相,可用于回溯查询)。"""
+        return self.valid_to is None
+
+    @classmethod
+    def _from(cls, d: dict) -> Memory:
+        why = d.get("why")
+        return cls(
+            id=d.get("id", ""),
+            statement=d.get("statement", ""),
+            score=d.get("score"),
+            topic=d.get("topic"),
+            valid_from=d.get("valid_from"),
+            valid_to=d.get("valid_to"),
+            provenance=d.get("provenance"),
+            why=Why(**{k: v for k, v in why.items() if k in Why.__annotations__}) if why else None,
+            explain_url=d.get("explain_url"),
+        )
+
+    def __str__(self) -> str:
+        mark = "" if self.is_current else " (已被取代)"
+        return f"{self.statement}{mark}"
+
+
+@dataclass
+class RecallResult:
+    facts: list[Memory] = field(default_factory=list)
+    summaries: list[dict] = field(default_factory=list)  # L1 会话摘要
+    documents: list[dict] = field(default_factory=list)  # 文档分块
+    messages: list[dict] = field(default_factory=list)  # L0 原文片段
+    budget: dict | None = None  # explain=True 时:用了多少预算、裁掉多少
+    timed_out_paths: list[str] = field(default_factory=list)
+
+    def __iter__(self):
+        return iter(self.facts)
+
+    def __len__(self) -> int:
+        return len(self.facts)
+
+    def as_prompt(self, header: str = "关于该用户你已知的:") -> str:
+        """拼成可直接塞进 system prompt 的文本——最常见的用法,省得每家自己写一遍。"""
+        if not self.facts:
+            return ""
+        lines = [f"- {m.statement}" for m in self.facts]
+        return f"{header}\n" + "\n".join(lines)
+
+    @classmethod
+    def _from(cls, d: dict) -> RecallResult:
+        return cls(
+            facts=[Memory._from(x) for x in d.get("facts", [])],
+            summaries=d.get("summaries", []) or [],
+            documents=d.get("documents", []) or [],
+            messages=d.get("messages", []) or [],
+            budget=d.get("budget"),
+            timed_out_paths=d.get("timed_out_paths", []) or [],
+        )
+
+
+@dataclass
+class ProfileSlot:
+    topic: str
+    sub_topic: str
+    projection: str
+    update_hits: int = 1
+    source_fact_ids: list[str] = field(default_factory=list)  # 可下钻:这条画像由哪些事实支撑
+
+
+@dataclass
+class Profile:
+    slots: list[ProfileSlot] = field(default_factory=list)
+    markdown: str | None = None  # 叙事版画像(Dream 全量重写)
+
+    def get(self, topic: str) -> list[ProfileSlot]:
+        return [s for s in self.slots if s.topic == topic]
+
+    def as_prompt(self) -> str:
+        return "\n".join(f"- [{s.topic}] {s.projection}" for s in self.slots)
+
+    @classmethod
+    def _from(cls, d: dict) -> Profile:
+        return cls(
+            slots=[
+                ProfileSlot(
+                    topic=s.get("topic", ""),
+                    sub_topic=s.get("sub_topic", ""),
+                    projection=s.get("projection", ""),
+                    update_hits=s.get("update_hits", 1),
+                    source_fact_ids=s.get("source_fact_ids", []) or [],
+                )
+                for s in d.get("slots", [])
+            ],
+            markdown=d.get("markdown"),
+        )
+
+
+class MemcoreError(Exception):
+    def __init__(self, status: int, message: str):
+        self.status, self.message = status, message
+        super().__init__(f"[{status}] {message}")

memcore_sdk-0.3.0.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.5
+Name: memcore-sdk
+Version: 0.3.0
+Summary: Python SDK for memcore — a universal memory kernel with explainable, auditable retrieval
+Project-URL: Homepage, https://reglos.ai
+License: Proprietary
+Keywords: agents,llm,memory,rag
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.3; extra == 'all'
+Requires-Dist: llama-index-core>=0.12; extra == 'all'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.12; extra == 'llamaindex'
+Description-Content-Type: text/markdown
+
+# memcore Python SDK
+
+给你的 AI 应用加一层**可解释、可审计**的长期记忆。
+
+```bash
+pip install memcore-sdk
+```
+
+## 10 分钟上手
+
+```python
+from memcore import Memcore
+
+mc = Memcore(api_key="mk_live_...")        # tenant/project 由 key 决定,你不用管
+user = mc.subject("your-user-42")          # 绑定记忆主体,后续调用不必再传
+
+# 1. 记住
+user.remember("我叫 Richard,住在上海,在做数据库产品,周末喜欢爬山。")
+
+# 2. 想起来 —— 直接拼进你的 prompt
+hits = user.recall("他住在哪里")
+system_prompt = "你是一个助手。\n" + hits.as_prompt()
+```
+
+就这样。抽取、去重、冲突消解、时效管理都在服务端完成。
+
+## 五个动词
+
+| 动词 | 用途 |
+| --- | --- |
+| `remember` | 写入:自然语言 / 对话消息 / 直接写事实 / 文档与图片 |
+| `recall` | 检索:多路融合 + 过滤 + **解释** |
+| `profile` / `ask` | 画像:结构化槽位 + 自然语言问答 |
+| `forget` | 遗忘:否决单条 / 删会话 / 全清(带删除回执) |
+| `explain` / `audit` | 溯源:这条记忆怎么来的 + 审计账本 |
+
+## 写入的三种形态
+
+```python
+# 自然语言(最常用)
+user.remember("我下个月要去日本出差")
+
+# 对话消息 —— `at` 用于回灌历史,相对时间("三年前")才能被正确解析
+user.remember(messages=[
+    {"role": "user", "content": "我三年前搬到杭州", "at": "2023-05-01T10:00:00Z"},
+    {"role": "assistant", "content": "杭州挺好的"},
+])
+
+# 你已有自己的抽取,直接写结构化事实
+user.remember(facts=[{"statement": "用户的租约 2027 年 8 月到期",
+                      "topic": "lifestyle", "confidence": 0.95}])
+
+# 文档与图片:PDF / Word / 文本直接解析;图片走 VLM 双路(描述 + OCR)
+user.remember_file("contract.pdf")
+user.remember_file("whiteboard.png")
+
+# 需要"写完立刻可查"?
+user.remember("...", sync=True)   # 默认异步:落库即返回,抽取在后台
+```
+
+## 检索与解释
+
+```python
+hits = user.recall("他住在哪里", explain=True)
+
+for m in hits:
+    print(m.statement, m.is_current)          # is_current=False 表示已被更新的事实取代
+    print(m.why.matched_paths)                # {'vector': {'rank': 1}, 'keyword': {'rank': 3}}
+    print(m.why.rrf_contribution)             # 各路对最终排名的贡献
+    print(m.why.validity)                     # current / superseded + 有效期
+
+print(hits.budget)   # 考虑了多少条、返回多少、裁掉多少、用了多少 token
+```
+
+**为什么要 explain**:调试召回质量时你能看到"为什么是这条";合规审查时你能证明答案有据可依。
+
+过滤:
+
+```python
+user.recall("最近的工作", topic="work", since=datetime(2026, 1, 1),
+            source="document", min_confidence=0.8, limit=20)
+```
+
+## 记忆是有时间的
+
+同一件事变了,旧记忆**不会被覆盖**,而是标记失效并保留:
+
+```python
+user.remember("我搬到上海了")
+user.recall("住在哪里")            # → 上海(当前有效)
+# 历史仍在:m.is_current == False 的那条记录着"曾经住在杭州"
+```
+
+这让"我 2023 年住哪"这类问题也答得出来,也让画像的每次变化都有据可查。
+
+## 遗忘的三种语义
+
+```python
+user.forget(memory_id, reason="抽错了")   # 作废:查询不再命中,留痕可回溯
+user.forget(session_id="...")             # 级联:消息 + 派生事实 + 向量一起清
+receipt = user.forget(everything=True)    # 全清:返回可存档的删除回执(合规举证)
+```
+
+## 溯源与审计
+
+```python
+lineage = user.explain(memory_id)
+# → 原始消息原文、生成记录(模型 + prompt 哈希)、被哪条新事实取代
+
+for e in user.audit(since=last_week):
+    print(e["at"], e["action"], e["record_id"])
+```
+
+## 异步
+
+方法名完全一致:
+
+```python
+from memcore import AsyncMemcore
+
+async with AsyncMemcore(api_key="...") as mc:
+    user = mc.subject("user-42")
+    await user.remember("...")
+    hits = await user.recall("...")
+```
+
+## 记忆主体不只是"用户"
+
+```python
+mc.subject("user-42")                            # 终端用户
+mc.subject("agent-researcher", "agent")          # 给 Agent 的记忆
+mc.subject("team-growth", "team")                # 团队共享记忆
+```
+
+## 错误处理
+
+```python
+from memcore import MemcoreError
+
+try:
+    user.remember("...")
+except MemcoreError as e:
+    print(e.status, e.message)     # 401 鉴权 / 400 参数 / 404 不存在
+```

memcore_sdk-0.3.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+memcore/__init__.py,sha256=IHh2Ky2ie_DtCPLt8YZZdS5c2eYEMt_kypSk3kesFy0,585
+memcore/client.py,sha256=c_7kiAvkw_0Cv_x_nqfXtBwvkFbs6_nq2gRNqImqcJE,12175
+memcore/models.py,sha256=p7e98XvKV2Z5EfUTfKbX-J6OM9Jx3t-4bd5VvFUBy0c,4471
+memcore/integrations/__init__.py,sha256=DjOvTXbvPhkuzcm65tA_Al-U65NiVHtMuX4dj5aXf8c,1429
+memcore/integrations/langchain.py,sha256=kS51KJioF_h2ZJ2uDBXMrMz95nxeNFy5IwO2PvNcVsY,6788
+memcore/integrations/llama_index.py,sha256=9evACVho1KcS0pm-0ZAGK68gHNB1J63m3-n8iA5Is5c,7554
+memcore_sdk-0.3.0.dist-info/METADATA,sha256=WOSZv-AHudYoT5BVWsFZfRuJ8a4rF8CZWDfFXGpOe5k,5086
+memcore_sdk-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+memcore_sdk-0.3.0.dist-info/RECORD,,

memcore_sdk-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any