n1mem · N1Mem 记忆 API Python SDK

powered by T1Mem engine · BYOK（自带 Key）· 同步零依赖

安装

pip install n1mem            # 同步版，零硬依赖
pip install n1mem[async]     # 需要异步客户端时（依赖 httpx）

10 行代码跑通

from n1mem import N1Mem

m = N1Mem(api_key="tk_xxx")        # 或设环境变量 N1MEM_API_KEY 后不传参

print(m.health())                  # 服务健康 + provider 可用性
m.ingest("我今天换了新工位，在 3 楼靠窗")
print(m.recall("我坐哪儿"))

API

异步版 AsyncN1Mem 接口完全一致：

async with AsyncN1Mem(api_key="tk_xxx") as m:
    await m.ingest("…")

错误处理

上游 4xx/5xx 统一抛 N1MemError，带 status / message / endpoint：

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 的区别

本目录有两个包，不要混用：

相关：MCP Server

想让 Claude / Cursor 直连，见 src/t1mem-core/mcp_server/（C-3）。