Metadata-Version: 2.4
Name: n1mem
Version: 0.1.5
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`（命中明文） |
| `forget(memory_id)` | `POST /v1/forget` | 删除指定记忆（仅本租户可见，删除后无法召回） |
| `ask / update / 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` 已基于命中的记忆做接地生成；若未命中任何记忆，会诚实返回未命中。
- `forget(memory_id)` 删除本租户内指定记忆及关联向量，删除后不可再召回。
- `ask / update / 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）。
