n1mem 0.1.3__tar.gz

n1mem-0.1.3/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: n1mem
+Version: 0.1.3
+Summary: N1Mem memory API client (BYOK, zero hard dependencies)
+Author: N1Mem (powered by T1Mem engine)
+License: Proprietary
+Project-URL: Homepage, https://www.n1mem.com
+Keywords: memory,llm,rag,agent,n1mem,t1mem
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: async
+Requires-Dist: httpx>=0.24; extra == "async"
+
+# n1mem · N1Mem 记忆 API Python SDK
+
+> powered by T1Mem engine · BYOK（自带 Key）· 同步零依赖
+
+## 安装
+
+```bash
+pip install n1mem            # 同步版，零硬依赖
+pip install n1mem[async]     # 需要异步客户端时（依赖 httpx）
+```
+
+## 10 行代码跑通
+
+```python
+from n1mem import N1Mem
+
+m = N1Mem(api_key="tk_xxx")        # 或设环境变量 N1MEM_API_KEY 后不传参
+
+print(m.health())                  # 服务健康 + provider 可用性
+m.ingest("我今天换了新工位，在 3 楼靠窗")
+print(m.recall("我坐哪儿"))
+```
+
+## API
+
+| 方法 | 对应端点 | 说明 |
+|---|---|---|
+| 方法 | 对应端点 | 说明 |
+|---|---|---|
+| `health()` | `GET /health` | 健康与 provider 状态，无需鉴权 |
+| `metrics()` | `GET /metrics` | Prometheus 文本指标 |
+| `ingest(text, purpose="recall")` | `POST /v1/ingest` | 写入一段记忆（持久化 + 建向量，写入即可召回） |
+| `recall(prompt, purpose="recall")` | `POST /v1/recall` | 按提示召回；返回 `answer`（已基于命中记忆接地）与 `retrieved`（命中明文） |
+| `ask / update / forget / list` | — | **尚未提供**，调用会明确抛 `NotImplementedError` |
+
+异步版 `AsyncN1Mem` 接口完全一致：
+
+```python
+async with AsyncN1Mem(api_key="tk_xxx") as m:
+    await m.ingest("…")
+```
+
+## 错误处理
+
+上游 4xx/5xx 统一抛 `N1MemError`，带 `status` / `message` / `endpoint`：
+
+```python
+from n1mem import N1MemError
+try:
+    m.ingest("x")
+except N1MemError as e:
+    print(e.status, e.endpoint, e.message)   # 401 /v1/ingest {"detail":"invalid api key"}
+```
+
+## 当前能力边界
+
+- `ingest()` 会把内容持久化到 N1Mem 存储层并生成向量，返回 `{stored, embedded, memory_id}`；写入后即可被召回。
+- `recall()` 走关键词 + 向量混合检索（hybrid），返回 `{answer, retrieved, recall_mode, ...}`。其中 `answer` 已基于命中的记忆做接地生成；若未命中任何记忆，会诚实返回未命中。
+- `ask / update / forget / list` 尚未提供，SDK 会明确抛 `NotImplementedError`，而不是静默返回空。
+
+> 历史勘误：v0.1.2 及更早 README 写「Phase 0 不持久化、recall 取不回」，该描述已随 C-2 存储层和召回接地修复而过时，请勿再引用。
+
+## 与 `t1mem_sdk` 的区别
+
+本目录有两个包，**不要混用**：
+
+| 包 | 对接对象 | 用途 |
+|---|---|---|
+| `n1mem` | 线上 C-2 API（`https://api.n1mem.com`） | **对外发布**，本 README 描述的对象 |
+| `t1mem_sdk` | 本地 t1mem-core API（`http://127.0.0.1:8080`） | 内部使用，接口为 `/memories`、`/sessions`、`/stats` |
+
+## 相关：MCP Server
+
+想让 Claude / Cursor 直连，见 `src/t1mem-core/mcp_server/`（C-3）。

n1mem-0.1.3/README.md

@@ -0,0 +1,134 @@
+# t1mem-sdk-py · v0.3.0 发布说明
+
+> ⚠ 本目录现有**两个包**，请勿混用：
+> - **`t1mem_sdk`**（本文件描述）—— **内部** SDK，对接本地 t1mem-core API
+>   （`http://127.0.0.1:8080`，端点为 `/memories`、`/sessions`、`/stats`）
+> - **`n1mem`** —— **对外** SDK，对接线上 C-2 API（`https://api.n1mem.com`），
+>   文档见 **[README.n1mem.md](README.n1mem.md)**
+
+> 发布日期：2026-06-20 · W9.2 阶段 · 负责人：祝融·Vulcan
+
+## 🎯 概览
+
+T1Mem Python SDK v0.3.0 — 零依赖同步客户端，10 分钟接入 T1Mem Core API。
+
+| 指标 | v0.2.0 | v0.3.0 | 提升 |
+|------|--------|--------|------|
+| API 方法数 | 9 | **11** | +22% |
+| 测试用例 | 6 | **24** | +300% |
+| 测试覆盖 | 端到端 6 类 | **端到端 24 类 + SDK ↔ TS e2e** | 完整 |
+| 鉴权支持 | api_key 参数 | **api_key 参数 + 自动 Bearer** | OK |
+| 错误类型 | T1MemError(status, body) | **同左 + 详细断言** | 增强 |
+| 外部依赖 | 0（纯 urllib） | **0（纯 urllib）** | 保持 |
+
+## 📦 安装
+
+```bash
+pip install t1mem-sdk
+# 或
+pip install git+https://gitee.com/suyupeng/t1mem-sdk-py.git@v0.3.0
+```
+
+## 🚀 5 分钟上手
+
+```python
+from t1mem_sdk import T1MemClient
+
+# 1. 创建客户端
+client = T1MemClient(
+    base_url="http://127.0.0.1:8080",
+    api_key="tk_xxx",  # dev 模式可省略
+    timeout=10.0,
+)
+
+# 2. 写入一条 memory
+m = client.ingest(
+    session_id="user-123",
+    role="user",
+    content="用户偏好：深色模式 + 中文",
+    tags=["preference", "ui"],
+    metadata={"source": "onboarding"},
+)
+print(f"saved: {m.id}")
+
+# 3. 批量写入
+items = [
+    {"session_id": "user-123", "role": "user", "content": "msg-1"},
+    {"session_id": "user-123", "role": "assistant", "content": "msg-2"},
+]
+results = client.ingest_batch(items)
+
+# 4. 列出 session
+for m in client.list_session("user-123", limit=50):
+    print(f"[{m.role}] {m.content}")
+
+# 5. 检索（text/vec/hybrid 三种模式）
+hits = client.search("user-123", "深色模式", mode="hybrid", limit=5)
+for h in hits:
+    print(f"hit: {h.id} - {h.content}")
+
+# 6. 单条查询
+m = client.get(m.id)
+
+# 7. 统计
+print(client.stats())
+```
+
+## 📚 API 完整列表
+
+| 方法 | 用途 | 返回 |
+|------|------|------|
+| `health()` | 健康检查 | `dict` |
+| `whoami()` | 当前 API key 信息 | `dict` |
+| `stats()` | 系统统计 | `Stats` |
+| `ingest(sid, role, content, **)` | 写入单条 | `Memory` |
+| `ingest_batch(items)` | 批量写入 | `list[Memory]` |
+| `get(memory_id)` | 单条查询 | `Memory` |
+| `list_session(sid, limit, offset)` | 列出 session | `list[Memory]` |
+| `search(sid, query, limit, *, mode)` | 检索（text/vec/hybrid） | `list[Memory]` |
+
+## 🧪 测试矩阵（24/24 全过）
+
+```
+tests/test_sdk.py           ·  6 项 · 原 SDK 集成
+tests/test_w92_sdk.py       · 12 项 · W9.2 增强
+tests/test_w10_e2e.py       ·  6 项 · 跨 SDK e2e
+```
+
+**关键场景**：
+- ✅ 4 种 role（user/assistant/system/tool）全过
+- ✅ 中文 + emoji + 特殊字符 round-trip
+- ✅ 批量 50 条 < 5s
+- ✅ 跨 SDK 互通（Py 写 → TS 读 ID 一致）
+- ✅ 跨 SDK 检索一致（同 query ID 集合相同）
+- ✅ 鉴权/错误（401/404/422 抛 T1MemError）
+
+## 🔄 W9.2 关键变更
+
+### 新增
+- `Memory.org_id` 字段（`v0.2.0` 缺）
+- `search(..., *, mode="hybrid")` 参数（`text`/`vec`/`hybrid`）
+- `test_w92_sdk.py` · 12 项 SDK 单元测试
+- `test_w10_e2e.py` · 6 项跨 SDK 集成测试
+
+### 改进
+- 错误信息更详细（T1MemError.code + T1MemError.body）
+- `list_session` 支持 `offset` 分页
+- `ingest` 支持 `metadata` 合并 `tags`（自动去重）
+
+## 🚧 已知限制
+
+- 同步客户端（无 async/await）— 后续可加 aiohttp 版本
+- 不支持流式响应（write/read 都是完整 JSON）
+- retry/backoff 需调用方自行处理
+- 批量上限 1000 条/次（受 API 限制）
+
+## 📅 下一步
+
+- W10.1：TypeScript SDK 同等增强（仓颉·Cangjie 已在做）
+- W10.2：发布到 Gitee 私有仓（`t1mem-sdk-py`）
+- W11：Phase 2 闸门验收（Lead）
+
+---
+
+Made with ❤️ by 祝融·Vulcan (T1Mem AI 团队 · backend)

n1mem-0.1.3/README.n1mem.md

@@ -0,0 +1,74 @@
+# n1mem · N1Mem 记忆 API Python SDK
+
+> powered by T1Mem engine · BYOK（自带 Key）· 同步零依赖
+
+## 安装
+
+```bash
+pip install n1mem            # 同步版，零硬依赖
+pip install n1mem[async]     # 需要异步客户端时（依赖 httpx）
+```
+
+## 10 行代码跑通
+
+```python
+from n1mem import N1Mem
+
+m = N1Mem(api_key="tk_xxx")        # 或设环境变量 N1MEM_API_KEY 后不传参
+
+print(m.health())                  # 服务健康 + provider 可用性
+m.ingest("我今天换了新工位，在 3 楼靠窗")
+print(m.recall("我坐哪儿"))
+```
+
+## API
+
+| 方法 | 对应端点 | 说明 |
+|---|---|---|
+| 方法 | 对应端点 | 说明 |
+|---|---|---|
+| `health()` | `GET /health` | 健康与 provider 状态，无需鉴权 |
+| `metrics()` | `GET /metrics` | Prometheus 文本指标 |
+| `ingest(text, purpose="recall")` | `POST /v1/ingest` | 写入一段记忆（持久化 + 建向量，写入即可召回） |
+| `recall(prompt, purpose="recall")` | `POST /v1/recall` | 按提示召回；返回 `answer`（已基于命中记忆接地）与 `retrieved`（命中明文） |
+| `ask / update / forget / list` | — | **尚未提供**，调用会明确抛 `NotImplementedError` |
+
+异步版 `AsyncN1Mem` 接口完全一致：
+
+```python
+async with AsyncN1Mem(api_key="tk_xxx") as m:
+    await m.ingest("…")
+```
+
+## 错误处理
+
+上游 4xx/5xx 统一抛 `N1MemError`，带 `status` / `message` / `endpoint`：
+
+```python
+from n1mem import N1MemError
+try:
+    m.ingest("x")
+except N1MemError as e:
+    print(e.status, e.endpoint, e.message)   # 401 /v1/ingest {"detail":"invalid api key"}
+```
+
+## 当前能力边界
+
+- `ingest()` 会把内容持久化到 N1Mem 存储层并生成向量，返回 `{stored, embedded, memory_id}`；写入后即可被召回。
+- `recall()` 走关键词 + 向量混合检索（hybrid），返回 `{answer, retrieved, recall_mode, ...}`。其中 `answer` 已基于命中的记忆做接地生成；若未命中任何记忆，会诚实返回未命中。
+- `ask / update / forget / list` 尚未提供，SDK 会明确抛 `NotImplementedError`，而不是静默返回空。
+
+> 历史勘误：v0.1.2 及更早 README 写「Phase 0 不持久化、recall 取不回」，该描述已随 C-2 存储层和召回接地修复而过时，请勿再引用。
+
+## 与 `t1mem_sdk` 的区别
+
+本目录有两个包，**不要混用**：
+
+| 包 | 对接对象 | 用途 |
+|---|---|---|
+| `n1mem` | 线上 C-2 API（`https://api.n1mem.com`） | **对外发布**，本 README 描述的对象 |
+| `t1mem_sdk` | 本地 t1mem-core API（`http://127.0.0.1:8080`） | 内部使用，接口为 `/memories`、`/sessions`、`/stats` |
+
+## 相关：MCP Server
+
+想让 Claude / Cursor 直连，见 `src/t1mem-core/mcp_server/`（C-3）。

n1mem-0.1.3/n1mem/__init__.py

@@ -0,0 +1,21 @@
+"""N1Mem —— 记忆 API 的 Python SDK（BYOK，零硬依赖）。
+
+快速开始::
+
+    from n1mem import N1Mem
+    m = N1Mem(api_key="tk_xxx")
+    m.ingest("我今天换了新工位，在 3 楼靠窗")
+    m.recall("我坐哪儿")
+
+⚠ 当前 C-2 处于 Phase 0：写入尚未落真实存储层，召回不到刚写入的内容。
+   存储层（Phase 1）接入后本说明会更新。
+"""
+from .client import (
+    DEFAULT_BASE_URL,
+    AsyncN1Mem,
+    N1Mem,
+    N1MemError,
+)
+
+__version__ = "0.1.2"
+__all__ = ["N1Mem", "AsyncN1Mem", "N1MemError", "DEFAULT_BASE_URL", "__version__"]

n1mem-0.1.3/n1mem/client.py

@@ -0,0 +1,244 @@
+"""N1Mem 对外 Python SDK —— 对接线上 C-2 API。
+
+设计原则：
+  * **零硬依赖**：同步客户端只用标准库 urllib，`pip install n1mem` 不拖任何包。
+  * **异步可选**：`pip install n1mem[async]` 才装 httpx；不装也能用同步版。
+  * **BYOK**：api_key 由调用方提供，SDK 不存储、不上传任何凭据。
+  * **诚实**：线上暂未提供的能力（ask/update/forget/list）**明确抛 NotImplementedError**，
+    绝不伪装成"已支持"。这是本项目「可信第一」定位的底线。
+
+C-2 当前已提供：/health、/metrics、/v1/ingest（持久化 + 向量化）、/v1/recall
+（hybrid 检索 + 基于命中记忆接地的 answer）。
+"""
+from __future__ import annotations
+
+import json as _json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+__all__ = ["N1Mem", "AsyncN1Mem", "N1MemError", "DEFAULT_BASE_URL"]
+
+# 默认指向官方品牌域名 api.n1mem.com（已绑定到 live C-2 公网端点：阿里云 FC 香港，免备案）。
+# 该域名是项目自有的稳定入口，优于 FC 自动生成的默认域名（重建函数可能变更）。
+DEFAULT_BASE_URL = "https://api.n1mem.com"
+
+# 线上 C-2 当前具备的业务端点（Phase 0）
+_SUPPORTED = ("/health", "/metrics", "/v1/ingest", "/v1/recall")
+
+# 规划中、线上尚未提供的能力（C-2 Phase 1 待接入）
+_NOT_READY = {
+    "ask": "需 C-2 提供 /v1/ask（规划中）",
+    "update": "需 C-2 提供 /v1/memories/{id} 更新（规划中，且依赖存储层）",
+    "forget": "需 C-2 提供 /v1/memories/{id} 删除（规划中，且依赖存储层）",
+    "list": "需 C-2 提供 /v1/memories 列表（规划中，且依赖存储层）",
+}
+
+
+class N1MemError(Exception):
+    """API 返回错误。"""
+
+    def __init__(self, status: int, message: str, endpoint: str = ""):
+        super().__init__(f"[{status}] {message}" + (f" ({endpoint})" if endpoint else ""))
+        self.status = status
+        self.message = message
+        self.endpoint = endpoint
+
+
+class _Base:
+    def __init__(self, api_key: str | None = None,
+                 base_url: str = DEFAULT_BASE_URL, timeout: float = 30.0):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # ---- 内部：请求构造 ----
+    def _url(self, path: str, params: dict | None = None) -> str:
+        u = self.base_url + path
+        if params:
+            u += "?" + urllib.parse.urlencode(params)
+        return u
+
+    def _headers(self, with_body: bool = False) -> dict:
+        h = {"Accept": "application/json"}
+        if with_body:
+            h["Content-Type"] = "application/json"
+        if self.api_key:
+            h["Authorization"] = f"Bearer {self.api_key}"
+        return h
+
+    @staticmethod
+    def _raise_from(exc: urllib.error.HTTPError, path: str):
+        try:
+            body = exc.read().decode("utf-8", "replace")
+        except Exception:
+            body = ""
+        raise N1MemError(exc.code, body or exc.reason, path) from exc
+
+
+class N1Mem(_Base):
+    """同步客户端。
+
+    用法::
+
+        from n1mem import N1Mem
+        m = N1Mem(api_key="tk_xxx")          # 或环境变量 N1MEM_API_KEY
+        m.health()
+        m.ingest("我今天换了新工位")
+        m.recall("我坐哪儿")
+    """
+
+    def __init__(self, api_key: str | None = None, **kw):
+        import os
+        super().__init__(api_key or os.environ.get("N1MEM_API_KEY"), **kw)
+
+    # ---- 低层 ----
+    def _request(self, method: str, path: str, body: dict | None = None,
+                 params: dict | None = None) -> Any:
+        data = _json.dumps(body, ensure_ascii=False).encode("utf-8") if body is not None else None
+        req = urllib.request.Request(
+            self._url(path, params), data=data, method=method,
+            headers=self._headers(with_body=data is not None))
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                raw = r.read().decode("utf-8", "replace")
+                return _json.loads(raw) if raw else {}
+        except urllib.error.HTTPError as e:
+            self._raise_from(e, path)
+        except urllib.error.URLError as e:
+            raise N1MemError(0, f"connection error: {e.reason}", path) from e
+
+    # ---- 已支持 ----
+    def health(self) -> dict:
+        """服务健康与 provider 可用性。无需鉴权。"""
+        return self._request("GET", "/health")
+
+    def metrics(self) -> str:
+        """Prometheus 文本指标。无需鉴权。"""
+        req = urllib.request.Request(self._url("/metrics"),
+                                     headers=self._headers())
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                return r.read().decode("utf-8", "replace")
+        except urllib.error.HTTPError as e:
+            self._raise_from(e, "/metrics")
+        except urllib.error.URLError as e:
+            raise N1MemError(0, f"connection error: {e.reason}", "/metrics") from e
+
+    def ingest(self, text: str, *, purpose: str = "recall") -> dict:
+        """写入一段记忆。
+
+        内容会持久化到 N1Mem 存储层并生成向量，返回 `{stored, embedded, memory_id}`。
+        写入后即可被 `recall()` 召回。
+        """
+        return self._request("POST", "/v1/ingest", {"text": text, "purpose": purpose})
+
+    def recall(self, prompt: str, *, purpose: str = "recall", mode: str | None = None) -> dict:
+        """按提示召回记忆。
+
+        返回体含 `answer`（已基于命中记忆接地的生成回答）、`retrieved`（命中的明文记忆
+        列表），以及 `recall_mode`（keyword|semantic|hybrid）等路由信息。
+
+        mode=None 时用服务端默认（hybrid：关键词 + 向量 RRF 融合，可召回改写问法）；
+        显式传 "keyword" 则回到纯关键词口径（用于回归对比）。
+        """
+        body = {"prompt": prompt, "purpose": purpose}
+        if mode:
+            body["mode"] = mode
+        return self._request("POST", "/v1/recall", body)
+
+    # ---- 规划中（明确报错，不伪装）----
+    def ask(self, *a, **kw):
+        raise NotImplementedError(_NOT_READY["ask"])
+
+    def update(self, *a, **kw):
+        raise NotImplementedError(_NOT_READY["update"])
+
+    def forget(self, *a, **kw):
+        raise NotImplementedError(_NOT_READY["forget"])
+
+    def list(self, *a, **kw):
+        raise NotImplementedError(_NOT_READY["list"])
+
+    def __repr__(self) -> str:
+        key = (self.api_key[:6] + "…") if self.api_key else "None"
+        return f"N1Mem(base_url={self.base_url!r}, api_key={key!r})"
+
+
+class AsyncN1Mem(_Base):
+    """异步客户端（需 `pip install n1mem[async]`）。
+
+    用法::
+
+        async with AsyncN1Mem(api_key="tk_xxx") as m:
+            await m.ingest("…")
+    """
+
+    def __init__(self, api_key: str | None = None, **kw):
+        import os
+        super().__init__(api_key or os.environ.get("N1MEM_API_KEY"), **kw)
+        try:
+            import httpx  # noqa: F401
+        except ImportError as e:  # pragma: no cover
+            raise ImportError(
+                "AsyncN1Mem 需要 httpx：`pip install n1mem[async]`") from e
+        self._client = None
+
+    async def __aenter__(self):
+        import httpx
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url, timeout=self.timeout,
+            headers=self._headers(with_body=True))
+        return self
+
+    async def __aexit__(self, *exc):
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    async def _arequest(self, method: str, path: str,
+                        body: dict | None = None) -> Any:
+        import httpx
+        own = self._client is None
+        if own:
+            await self.__aenter__()
+        try:
+            r = await self._client.request(method, path, json=body)
+            if r.status_code >= 400:
+                raise N1MemError(r.status_code, r.text[:400], path)
+            ct = r.headers.get("content-type", "")
+            return r.json() if "json" in ct else r.text
+        finally:
+            if own:
+                await self.__aexit__()
+
+    async def health(self) -> dict:
+        return await self._arequest("GET", "/health")
+
+    async def metrics(self) -> str:
+        return await self._arequest("GET", "/metrics")
+
+    async def ingest(self, text: str, *, purpose: str = "recall") -> dict:
+        return await self._arequest("POST", "/v1/ingest",
+                                    {"text": text, "purpose": purpose})
+
+    async def recall(self, prompt: str, *, purpose: str = "recall",
+                     mode: str | None = None) -> dict:
+        body = {"prompt": prompt, "purpose": purpose}
+        if mode:
+            body["mode"] = mode
+        return await self._arequest("POST", "/v1/recall", body)
+
+    # ---- 规划中（明确报错，不伪装；与同步版口径一致）----
+    async def ask(self, *a, **kw):
+        raise NotImplementedError(_NOT_READY["ask"])
+
+    async def update(self, *a, **kw):
+        raise NotImplementedError(_NOT_READY["update"])
+
+    async def forget(self, *a, **kw):
+        raise NotImplementedError(_NOT_READY["forget"])
+
+    async def list(self, *a, **kw):
+        raise NotImplementedError(_NOT_READY["list"])

n1mem-0.1.3/n1mem.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: n1mem
+Version: 0.1.3
+Summary: N1Mem memory API client (BYOK, zero hard dependencies)
+Author: N1Mem (powered by T1Mem engine)
+License: Proprietary
+Project-URL: Homepage, https://www.n1mem.com
+Keywords: memory,llm,rag,agent,n1mem,t1mem
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: async
+Requires-Dist: httpx>=0.24; extra == "async"
+
+# n1mem · N1Mem 记忆 API Python SDK
+
+> powered by T1Mem engine · BYOK（自带 Key）· 同步零依赖
+
+## 安装
+
+```bash
+pip install n1mem            # 同步版，零硬依赖
+pip install n1mem[async]     # 需要异步客户端时（依赖 httpx）
+```
+
+## 10 行代码跑通
+
+```python
+from n1mem import N1Mem
+
+m = N1Mem(api_key="tk_xxx")        # 或设环境变量 N1MEM_API_KEY 后不传参
+
+print(m.health())                  # 服务健康 + provider 可用性
+m.ingest("我今天换了新工位，在 3 楼靠窗")
+print(m.recall("我坐哪儿"))
+```
+
+## API
+
+| 方法 | 对应端点 | 说明 |
+|---|---|---|
+| 方法 | 对应端点 | 说明 |
+|---|---|---|
+| `health()` | `GET /health` | 健康与 provider 状态，无需鉴权 |
+| `metrics()` | `GET /metrics` | Prometheus 文本指标 |
+| `ingest(text, purpose="recall")` | `POST /v1/ingest` | 写入一段记忆（持久化 + 建向量，写入即可召回） |
+| `recall(prompt, purpose="recall")` | `POST /v1/recall` | 按提示召回；返回 `answer`（已基于命中记忆接地）与 `retrieved`（命中明文） |
+| `ask / update / forget / list` | — | **尚未提供**，调用会明确抛 `NotImplementedError` |
+
+异步版 `AsyncN1Mem` 接口完全一致：
+
+```python
+async with AsyncN1Mem(api_key="tk_xxx") as m:
+    await m.ingest("…")
+```
+
+## 错误处理
+
+上游 4xx/5xx 统一抛 `N1MemError`，带 `status` / `message` / `endpoint`：
+
+```python
+from n1mem import N1MemError
+try:
+    m.ingest("x")
+except N1MemError as e:
+    print(e.status, e.endpoint, e.message)   # 401 /v1/ingest {"detail":"invalid api key"}
+```
+
+## 当前能力边界
+
+- `ingest()` 会把内容持久化到 N1Mem 存储层并生成向量，返回 `{stored, embedded, memory_id}`；写入后即可被召回。
+- `recall()` 走关键词 + 向量混合检索（hybrid），返回 `{answer, retrieved, recall_mode, ...}`。其中 `answer` 已基于命中的记忆做接地生成；若未命中任何记忆，会诚实返回未命中。
+- `ask / update / forget / list` 尚未提供，SDK 会明确抛 `NotImplementedError`，而不是静默返回空。
+
+> 历史勘误：v0.1.2 及更早 README 写「Phase 0 不持久化、recall 取不回」，该描述已随 C-2 存储层和召回接地修复而过时，请勿再引用。
+
+## 与 `t1mem_sdk` 的区别
+
+本目录有两个包，**不要混用**：
+
+| 包 | 对接对象 | 用途 |
+|---|---|---|
+| `n1mem` | 线上 C-2 API（`https://api.n1mem.com`） | **对外发布**，本 README 描述的对象 |
+| `t1mem_sdk` | 本地 t1mem-core API（`http://127.0.0.1:8080`） | 内部使用，接口为 `/memories`、`/sessions`、`/stats` |
+
+## 相关：MCP Server
+
+想让 Claude / Cursor 直连，见 `src/t1mem-core/mcp_server/`（C-3）。

n1mem-0.1.3/n1mem.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+README.n1mem.md
+pyproject.toml
+n1mem/__init__.py
+n1mem/client.py
+n1mem.egg-info/PKG-INFO
+n1mem.egg-info/SOURCES.txt
+n1mem.egg-info/dependency_links.txt
+n1mem.egg-info/requires.txt
+n1mem.egg-info/top_level.txt
+tests/test_n1mem_cloud.py
+tests/test_sdk.py
+tests/test_w10_e2e.py
+tests/test_w92_sdk.py

n1mem-0.1.3/n1mem.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

n1mem-0.1.3/n1mem.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[async]
+httpx>=0.24

n1mem-0.1.3/n1mem.egg-info/top_level.txt

@@ -0,0 +1 @@
+n1mem

n1mem-0.1.3/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "n1mem"
+version = "0.1.3"
+description = "N1Mem memory API client (BYOK, zero hard dependencies)"
+readme = "README.n1mem.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+authors = [{ name = "N1Mem (powered by T1Mem engine)" }]
+keywords = ["memory", "llm", "rag", "agent", "n1mem", "t1mem"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.optional-dependencies]
+async = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://www.n1mem.com"
+
+[tool.setuptools.packages.find]
+include = ["n1mem*"]
+
+# 说明：本文件只打包对外的 `n1mem` 包。
+# 同目录下的 `t1mem_sdk/` 是**内部** SDK（对接本地 t1mem-core API），
+# 接口与线上 C-2 不同套，不对外发布，故在此排除。

n1mem-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

n1mem-0.1.3/tests/test_n1mem_cloud.py

@@ -0,0 +1,115 @@
+"""n1mem 对外 SDK 单测（全部 mock，零网络、零 API 花费）。
+
+覆盖：
+  1. 默认端点与鉴权头正确
+  2. ingest / recall 请求体字段与线上 C-2 契约一致
+  3. 上游 401 / 429 正确转成 N1MemError
+  4. 未就绪能力（ask/update/forget/list）明确 NotImplementedError —— 不伪装支持
+  5. 无 api_key 时不带 Authorization 头
+"""
+import io
+import json
+import urllib.error
+
+import pytest
+
+from n1mem import DEFAULT_BASE_URL, N1Mem, N1MemError
+
+
+class _Resp(io.BytesIO):
+    def __init__(self, payload, status=200):
+        raw = payload if isinstance(payload, str) else json.dumps(payload)
+        super().__init__(raw.encode("utf-8"))
+        self.status = status
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+
+def _capture(monkeypatch):
+    """拦截 urlopen，返回 (记录的请求, 预设响应设置器)。"""
+    box = {}
+
+    def fake_urlopen(req, timeout=None, **kw):
+        box["req"] = req
+        box["timeout"] = timeout
+        return box.get("resp", _Resp({"ok": True}))
+
+    monkeypatch.setattr("urllib.request.urlopen", fake_urlopen)
+    return box
+
+
+def test_default_base_url_is_production():
+    m = N1Mem(api_key="tk_x")
+    assert m.base_url == DEFAULT_BASE_URL == "https://api.n1mem.com"
+
+
+def test_auth_header_present(monkeypatch):
+    box = _capture(monkeypatch)
+    N1Mem(api_key="tk_abc").health()
+    assert box["req"].get_header("Authorization") == "Bearer tk_abc"
+
+
+def test_no_key_no_auth_header(monkeypatch):
+    box = _capture(monkeypatch)
+    N1Mem(api_key=None).health()
+    assert box["req"].get_header("Authorization") is None
+
+
+def test_ingest_body_matches_api_contract(monkeypatch):
+    box = _capture(monkeypatch)
+    N1Mem(api_key="tk").ingest("我今天换了新工位")
+    req = box["req"]
+    assert req.get_method() == "POST"
+    assert req.full_url == DEFAULT_BASE_URL + "/v1/ingest"
+    body = json.loads(req.data.decode("utf-8"))
+    assert body["text"] == "我今天换了新工位"
+    assert body["purpose"] == "recall"
+
+
+def test_recall_body_matches_api_contract(monkeypatch):
+    box = _capture(monkeypatch)
+    N1Mem(api_key="tk").recall("我坐哪儿")
+    req = box["req"]
+    assert req.full_url == DEFAULT_BASE_URL + "/v1/recall"
+    body = json.loads(req.data.decode("utf-8"))
+    assert body["prompt"] == "我坐哪儿"
+
+
+def test_health_returns_parsed_json(monkeypatch):
+    box = _capture(monkeypatch)
+    box["resp"] = _Resp({"status": "ok", "region": "cn-hongkong"})
+    out = N1Mem(api_key="tk").health()
+    assert out["status"] == "ok"
+    assert out["region"] == "cn-hongkong"
+
+
+@pytest.mark.parametrize("code", [401, 429])
+def test_http_error_becomes_n1mem_error(code, monkeypatch):
+    def boom(req, timeout=None, **kw):
+        raise urllib.error.HTTPError(
+            DEFAULT_BASE_URL + "/v1/ingest", code, "err", {},
+            io.BytesIO(b'{"detail":"nope"}'))
+
+    monkeypatch.setattr("urllib.request.urlopen", boom)
+    with pytest.raises(N1MemError) as ei:
+        N1Mem(api_key="tk").ingest("x")
+    assert ei.value.status == code
+    assert "nope" in ei.value.message
+
+
+@pytest.mark.parametrize("name", ["ask", "update", "forget", "list"])
+def test_not_ready_capabilities_raise_clearly(name):
+    """关键：未就绪的能力必须明确报错，绝不能静默伪装成可用。"""
+    with pytest.raises(NotImplementedError) as ei:
+        getattr(N1Mem(api_key="tk"), name)("x")
+    assert "C-2" in str(ei.value) or "规划中" in str(ei.value)
+
+
+def test_repr_hides_key():
+    r = repr(N1Mem(api_key="tk_secret_value_123"))
+    assert "secret_value_123" not in r
+    assert "tk_sec" in r

n1mem-0.1.3/tests/test_sdk.py

@@ -0,0 +1,75 @@
+"""T1Mem SDK tests (integration with running server)."""
+import os
+import sys
+import uuid
+
+import pytest
+
+# Ensure SDK is on path
+ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, ROOT)
+
+from t1mem_sdk import T1MemClient, T1MemError  # noqa: E402
+
+
+BASE_URL = os.environ.get("T1MEM_URL", "http://127.0.0.1:8080")
+
+
+@pytest.fixture
+def client():
+    return T1MemClient(BASE_URL)
+
+
+@pytest.fixture
+def session_id():
+    return f"test-{uuid.uuid4().hex[:8]}"
+
+
+def test_health(client):
+    h = client.health()
+    assert h["status"] == "ok"
+
+
+def test_ingest_and_get(client, session_id):
+    m = client.ingest(session_id, "user", "SDK test message", tags=["pytest"])
+    assert m.session_id == session_id
+    assert m.content == "SDK test message"
+    assert "pytest" in m.metadata.get("tags", [])
+
+    fetched = client.get(m.id)
+    assert fetched.id == m.id
+
+
+def test_list_and_search(client, session_id):
+    client.ingest(session_id, "user", "alpha")
+    client.ingest(session_id, "assistant", "beta")
+    client.ingest(session_id, "user", "T1Mem rocks")
+
+    items = client.list_session(session_id)
+    assert len(items) == 3
+
+    hits = client.search(session_id, "T1Mem")
+    assert len(hits) == 1
+    assert "T1Mem" in hits[0].content
+
+
+def test_stats(client):
+    s = client.stats()
+    assert s.total >= 0
+    assert s.last_24h >= 0
+
+
+def test_404_raises(client):
+    with pytest.raises(T1MemError) as exc:
+        client.get("nonexistent-" + uuid.uuid4().hex)
+    assert exc.value.status == 404
+
+
+def test_batch_ingest(client, session_id):
+    items = [
+        {"session_id": session_id, "role": "user", "content": f"msg-{i}"}
+        for i in range(5)
+    ]
+    results = client.ingest_batch(items)
+    assert len(results) == 5
+    assert all(r.session_id == session_id for r in results)

n1mem-0.1.3/tests/test_w10_e2e.py

@@ -0,0 +1,205 @@
+"""W10: SDK e2e 测试 — Python SDK ↔ TypeScript SDK 数据互通
+
+场景：
+1. Python SDK 写入 → TypeScript SDK 读取（验证序列化一致）
+2. TypeScript SDK 写入 → Python SDK 读取
+3. 两端 search 行为一致
+4. 跨 SDK 鉴权一致性
+"""
+import os
+import sys
+import time
+import uuid
+import json
+import subprocess
+from pathlib import Path
+
+import pytest
+
+ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, ROOT)
+
+from t1mem_sdk import T1MemClient, T1MemError  # noqa: E402
+
+BASE_URL = os.environ.get("T1MEM_URL", "http://127.0.0.1:8080")
+TS_SDK_DIR = Path(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))).parent / "t1mem-sdk-ts"
+
+
+@pytest.fixture
+def py_client():
+    return T1MemClient(BASE_URL)
+
+
+@pytest.fixture
+def shared_session():
+    """e2e 共用 session_id"""
+    return f"e2e-{uuid.uuid4().hex[:8]}"
+
+
+def _run_ts(args: list[str], env_extra: dict | None = None) -> tuple[int, str, str]:
+    """跑一段 TS SDK 测试脚本，返回 (rc, stdout, stderr)"""
+    env = os.environ.copy()
+    env["T1MEM_URL"] = BASE_URL
+    if env_extra:
+        env.update(env_extra)
+    # 用绝对路径避开 Windows subprocess 找不到 npx
+    npx_bin = r"C:\Users\Administrator\.workbuddy\binaries\node\versions\22.22.2\npx.cmd"
+    r = subprocess.run(
+        [npx_bin, "tsx"] + args,
+        cwd=str(TS_SDK_DIR),
+        capture_output=True,
+        text=True,
+        timeout=60,
+        env=env,
+        shell=True,
+    )
+    return r.returncode, r.stdout, r.stderr
+
+
+def test_w10_01_py_ingest_ts_read(py_client, shared_session):
+    """W10.1: Python 写入 → TS 读取（通过临时 TS 脚本调 list）"""
+    py_client.ingest(shared_session, "user", "Python wrote this: T1Mem rocks")
+    py_client.ingest(shared_session, "assistant", "TS SDK should see this")
+    time.sleep(0.3)
+
+    # 让 TS 跑一个临时脚本去 list 这个 session
+    script = f"""
+import {{ T1MemClient }} from "../src/index.ts";
+const c = new T1MemClient({{ baseUrl: process.env.T1MEM_URL }});
+const list = await c.listSession("{shared_session}", {{ limit: 10 }});
+console.log(JSON.stringify({{ count: list.length, items: list.map(m => ({{ content: m.content, role: m.role, orgId: m.orgId }})) }}));
+"""
+    script_path = TS_SDK_DIR / "tests" / "_tmp_e2e_list.ts"
+    script_path.write_text(script)
+    try:
+        rc, out, err = _run_ts(["tests/_tmp_e2e_list.ts"])
+        assert rc == 0, f"TS script failed: {err}"
+        data = json.loads(out.strip().splitlines()[-1])
+        assert data["count"] == 2
+        assert data["items"][0]["orgId"] == "default"
+        # 至少 1 条含 T1Mem（顺序可能因 timestamp 翻转）
+        assert any("T1Mem" in it["content"] for it in data["items"])
+    finally:
+        if script_path.exists():
+            script_path.unlink()
+
+
+def test_w10_02_ts_ingest_py_read(py_client, shared_session):
+    """W10.2: TS 写入 → Python 读取"""
+    script = f"""
+import {{ T1MemClient }} from "../src/index.ts";
+const c = new T1MemClient({{ baseUrl: process.env.T1MEM_URL }});
+const m1 = await c.ingest({{ sessionId: "{shared_session}", role: "user", content: "TS wrote: T1Mem Python SDK", tags: ["from-ts"] }});
+const m2 = await c.ingest({{ sessionId: "{shared_session}", role: "assistant", content: "Py SDK should see this" }});
+console.log(JSON.stringify({{ ids: [m1.id, m2.id], tags: m1.metadata?.tags }}));
+"""
+    script_path = TS_SDK_DIR / "tests" / "_tmp_e2e_ingest.ts"
+    script_path.write_text(script)
+    try:
+        rc, out, err = _run_ts(["tests/_tmp_e2e_ingest.ts"])
+        assert rc == 0, f"TS script failed: {err}"
+        data = json.loads(out.strip().splitlines()[-1])
+        ts_ids = set(data["ids"])
+        assert "from-ts" in (data.get("tags") or [])
+    finally:
+        if script_path.exists():
+            script_path.unlink()
+
+    time.sleep(0.3)
+    # Python 读
+    items = py_client.list_session(shared_session)
+    assert len(items) == 2
+    py_ids = {m.id for m in items}
+    # IDs 必须完全一致
+    assert py_ids == ts_ids, f"ID mismatch: py={py_ids}, ts={ts_ids}"
+
+
+def test_w10_03_search_consistency(py_client, shared_session):
+    """W10.3: Python 和 TS 搜同一关键词，结果 ID 集合一致"""
+    # Py 写 3 条
+    py_client.ingest(shared_session, "user", "T1Mem 提供 Python 和 TypeScript SDK")
+    py_client.ingest(shared_session, "assistant", "T1Mem 是 Top-1 AI 记忆中间件")
+    py_client.ingest(shared_session, "user", "普通的文档")
+    time.sleep(0.5)
+
+    # Py 搜
+    py_hits = py_client.search(shared_session, "T1Mem", limit=10)
+    py_ids = sorted(m.id for m in py_hits)
+
+    # TS 搜
+    script = f"""
+import {{ T1MemClient }} from "../src/index.ts";
+const c = new T1MemClient({{ baseUrl: process.env.T1MEM_URL }});
+const hits = await c.search("{shared_session}", "T1Mem", {{ limit: 10 }});
+console.log(JSON.stringify(hits.map(h => h.id).sort()));
+"""
+    script_path = TS_SDK_DIR / "tests" / "_tmp_e2e_search.ts"
+    script_path.write_text(script)
+    try:
+        rc, out, err = _run_ts(["tests/_tmp_e2e_search.ts"])
+        assert rc == 0, f"TS script failed: {err}"
+        ts_ids = sorted(json.loads(out.strip().splitlines()[-1]))
+        # 两个 SDK 搜到的 ID 集合必须一致
+        assert py_ids == ts_ids, f"Py={py_ids}, TS={ts_ids}"
+    finally:
+        if script_path.exists():
+            script_path.unlink()
+
+
+def test_w10_04_chinese_round_trip(py_client, shared_session):
+    """W10.4: 中文 + emoji 跨 SDK 互通"""
+    content = "T1Mem 测试中文 + emoji 🎉 + 特殊字符 !@#$%"
+    py_client.ingest(shared_session, "user", content)
+    time.sleep(0.3)
+
+    # Py 读
+    items = py_client.list_session(shared_session)
+    assert len(items) == 1
+    assert items[0].content == content
+
+    # TS 读
+    script = f"""
+import {{ T1MemClient }} from "../src/index.ts";
+const c = new T1MemClient({{ baseUrl: process.env.T1MEM_URL }});
+const items = await c.listSession("{shared_session}", {{ limit: 5 }});
+console.log(JSON.stringify({{ count: items.length, content: items[0]?.content }}));
+"""
+    script_path = TS_SDK_DIR / "tests" / "_tmp_e2e_cn.ts"
+    script_path.write_text(script)
+    try:
+        rc, out, err = _run_ts(["tests/_tmp_e2e_cn.ts"])
+        assert rc == 0, f"TS script failed: {err}"
+        data = json.loads(out.strip().splitlines()[-1])
+        assert data["count"] == 1
+        assert data["content"] == content
+    finally:
+        if script_path.exists():
+            script_path.unlink()
+
+
+def test_w10_05_batch_50_items(py_client, shared_session):
+    """W10.5: 批量 50 条性能（< 5s）"""
+    items = [
+        {"session_id": shared_session, "role": "user", "content": f"batch-e2e-{i:03d}"}
+        for i in range(50)
+    ]
+    t0 = time.time()
+    results = py_client.ingest_batch(items)
+    elapsed = time.time() - t0
+    assert len(results) == 50
+    assert elapsed < 5.0, f"batch took {elapsed:.2f}s, expected <5s"
+
+
+def test_w10_06_ts_test_files_collect(shared_session):
+    """W10.6: 验证 TS SDK 自带 3 个测试文件全过（ingest/recall/search）"""
+    rc, out, err = _run_ts([
+        "--test", "tests/ingest.test.mjs",
+        "--test", "tests/recall.test.mjs",
+        "--test", "tests/search.test.mjs",
+    ])
+    # summary 末尾
+    lines = out.strip().splitlines()
+    last_summary = [l for l in lines if l.startswith("# ")]
+    summary_text = "\n".join(last_summary)
+    assert "# pass" in summary_text
+    assert "# fail 0" in summary_text, f"TS tests failed:\n{out[-2000:]}"

n1mem-0.1.3/tests/test_w92_sdk.py

@@ -0,0 +1,164 @@
+"""W9.2: Python SDK 增强测试（祝融主）
+
+覆盖：tags / metadata / 4 种 role / 错误处理 / 中文 / batch
+"""
+import os
+import sys
+import time
+import uuid
+
+import pytest
+
+ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, ROOT)
+
+from t1mem_sdk import T1MemClient, T1MemError  # noqa: E402
+
+BASE_URL = os.environ.get("T1MEM_URL", "http://127.0.0.1:8080")
+
+
+@pytest.fixture
+def client():
+    return T1MemClient(BASE_URL)
+
+
+@pytest.fixture
+def session_id():
+    return f"py-sdk-w92-{uuid.uuid4().hex[:8]}"
+
+
+def test_w92_01_ingest_basic(client, session_id):
+    """W9.2.1: 基本写入 + tags 合并"""
+    m = client.ingest(
+        session_id, "user", "T1Mem 是 Top-1 AI 记忆中间件",
+        tags=["w9.2", "test"],
+    )
+    assert m.session_id == session_id
+    assert m.content == "T1Mem 是 Top-1 AI 记忆中间件"
+    assert m.role == "user"
+    assert m.id  # 必有 id
+    assert m.org_id == "default"
+    assert "w9.2" in m.metadata.get("tags", [])
+    assert m.created_at > 0
+
+
+def test_w92_02_metadata_and_tags_merge(client, session_id):
+    """W9.2.2: 用户传 metadata + tags，SDK 应合并"""
+    m = client.ingest(
+        session_id, "assistant", "测试 metadata 合并",
+        metadata={"source": "w9.2-test", "priority": "high"},
+        tags=["meta-merge"],
+    )
+    assert m.metadata["source"] == "w9.2-test"
+    assert m.metadata["priority"] == "high"
+    assert "meta-merge" in m.metadata.get("tags", [])
+
+
+def test_w92_03_four_roles(client, session_id):
+    """W9.2.3: user/assistant/system/tool 4 种 role 都接受"""
+    for role in ["user", "assistant", "system", "tool"]:
+        m = client.ingest(session_id, role, f"{role} role test")
+        assert m.role == role
+    items = client.list_session(session_id)
+    assert len(items) == 4
+
+
+def test_w92_04_invalid_role_raises(client, session_id):
+    """W9.2.4: 非法 role 抛 T1MemError(422)"""
+    with pytest.raises(T1MemError) as exc:
+        client.ingest(session_id, "hacker", "should fail")
+    assert exc.value.status == 422
+
+
+def test_w92_05_empty_content_raises(client, session_id):
+    """W9.2.5: 空 content 抛 T1MemError(422)"""
+    with pytest.raises(T1MemError) as exc:
+        client.ingest(session_id, "user", "")
+    assert exc.value.status == 422
+
+
+def test_w92_06_batch_ingest(client, session_id):
+    """W9.2.6: 批量 10 条"""
+    items = [
+        {"session_id": session_id, "role": "user", "content": f"batch-{i}"}
+        for i in range(10)
+    ]
+    results = client.ingest_batch(items)
+    assert len(results) == 10
+    for i, r in enumerate(results):
+        assert r.content == f"batch-{i}"
+        assert r.session_id == session_id
+
+
+def test_w92_07_chinese_search(client, session_id):
+    """W9.2.7: 中文写入 + 中文检索"""
+    client.ingest(session_id, "user", "T1Mem 提供 Python 和 TypeScript SDK")
+    client.ingest(session_id, "assistant", "项目预算是 50 万人民币")
+    time.sleep(0.3)
+    # 搜中文
+    hits = client.search(session_id, "项目", limit=5)
+    assert len(hits) >= 1
+    assert any("项目" in h.content for h in hits)
+
+
+def test_w92_08_search_modes(client, session_id):
+    """W9.2.8: search 模式切换 text/vec/hybrid"""
+    client.ingest(session_id, "user", "T1Mem 提供 Python SDK")
+    time.sleep(0.3)
+    # text 模式
+    hits_text = client.search(session_id, "T1Mem", limit=5, mode="text")
+    assert len(hits_text) >= 1
+    # hybrid 模式
+    hits_h = client.search(session_id, "T1Mem", limit=5, mode="hybrid")
+    assert len(hits_h) >= 1
+    # 不存在的 mode 应抛 422
+    with pytest.raises(T1MemError) as exc:
+        client.search(session_id, "T1Mem", limit=5, mode="nonsense")
+    assert exc.value.status == 422
+
+
+def test_w92_09_pagination(client, session_id):
+    """W9.2.9: listSession 分页"""
+    for i in range(8):
+        client.ingest(session_id, "user", f"page-{i}")
+    p1 = client.list_session(session_id, limit=3, offset=0)
+    p2 = client.list_session(session_id, limit=3, offset=3)
+    p3 = client.list_session(session_id, limit=3, offset=6)
+    assert len(p1) == 3
+    assert len(p2) == 3
+    assert len(p3) == 2  # 8 - 6 = 2
+    # 倒序：p1[0] 最新, p1[-1] 早于 p2[0]
+    assert p1[0].created_at >= p1[-1].created_at
+    assert p1[-1].created_at >= p2[0].created_at
+
+
+def test_w92_10_404_raises(client):
+    """W9.2.10: 不存在的 memory_id 抛 404"""
+    with pytest.raises(T1MemError) as exc:
+        client.get(f"nonexistent-{uuid.uuid4()}")
+    assert exc.value.status == 404
+
+
+def test_w92_11_session_isolation(client):
+    """W9.2.11: 不同 session 完全隔离"""
+    sid_a = f"py-sdk-w92-A-{uuid.uuid4().hex[:6]}"
+    sid_b = f"py-sdk-w92-B-{uuid.uuid4().hex[:6]}"
+    client.ingest(sid_a, "user", "A 的项目是 T1Mem")
+    client.ingest(sid_b, "user", "B 的项目是 Mnemosyne")
+    list_a = client.list_session(sid_a)
+    list_b = client.list_session(sid_b)
+    assert len(list_a) == 1
+    assert len(list_b) == 1
+    assert "T1Mem" in list_a[0].content
+    assert "Mnemosyne" in list_b[0].content
+    # 跨 session 搜不到
+    hits = client.search(sid_a, "Mnemosyne", limit=5)
+    assert all("Mnemosyne" not in h.content for h in hits)
+
+
+def test_w92_12_connection_error():
+    """W9.2.12: 连接错误抛 T1MemError(0)"""
+    bad = T1MemClient("http://127.0.0.1:1", timeout=1.0)
+    with pytest.raises(T1MemError) as exc:
+        bad.health()
+    assert exc.value.status == 0