Metadata-Version: 2.1
Name: n1mem
Version: 0.1.1
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` | 按提示召回 |
| `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"}
```

## ⚠ 当前限制（重要）

C-2 服务目前处于 **Phase 0**（公网可达 + 鉴权 + 限流 + 探针已就绪）：

- `ingest()` 会把内容真实发往上游模型，并返回 `stored: true`，
  但**尚未落真实存储层** —— 因此随后 `recall()` **取不回**本次写入的内容。
- `recall()` 返回的是上游模型的回答，**不是**从记忆库检索的结果。
- `ask / update / forget / list` 尚未提供，SDK 会明确报错而不是静默返回空。

存储层（Phase 1）接入后，本文件与 `client.py` 的对应注释会同步更新。

## 与 `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）。
