Metadata-Version: 2.5
Name: memcore-sdk
Version: 0.3.1
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")          # 服务端 key:绑定任意记忆主体,后续调用不必再传
# 控制台里给自己签的 key(mk_user_…)绑着你本人,不用知道 subject id:
# user = Memcore(api_key="mk_user_...").me()

# 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 不存在
```
