memcore-sdk 0.3.0__tar.gz

memcore_sdk-0.3.0/.gitignore

@@ -0,0 +1,86 @@
+# 密钥:绝不入库。真实 key 曾被误粘进 .env.example(模板),教训见 backend/README
+.env
+.env.*
+!.env.example
+
+# 依赖与缓存
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+
+# 他人仓库:5.4GB,各自带 .git 与不同许可证(含 AGPL / CC-NC),不纳入本仓库
+reference/
+
+# 评测数据:体积大且多为 CC-NC 许可,不可随代码分发(见 evals/benchmarks/DATASET_LICENSES.md)
+backend/evals/benchmarks/data/*.json
+backend/evals/benchmarks/results/
+backend/evals/results/
+# b47cacc 之后 backend/ → backend/v1/,上面几条只留作历史;实际生效的是这几条
+backend/v1/evals/results/
+backend/v1/evals/benchmarks/results/
+backend/v1/var/
+
+# Next 构建产物。website/.gitignore 已经挡了 website/.next/，
+# 但在仓库根跑错目录的 next build 会在这里落一个 .next/trace，那个挡不住。
+.next/
+
+# 运行产物
+*.log
+
+# 上面的 `.env` / `.env.*` 漏掉了 `<名字>.env` 这种写法 —— 实测
+# `backend/evals/benchmarks/samemodel.env` 带真实 API key 却处于未跟踪状态,
+# 一次 `git add -A` 就会入库。改用后缀匹配兜住全部(`.env.example` 不以 .env 结尾,不受影响)
+*.env
+
+# memos 运行数据:sqlite 库、日志、锁文件。是机器本地状态,不是代码。
+# 注意 `*.log` 匹配不到 `memos.log.2026-08-27` 这种带日期后缀的
+.memos/
+.venv-memos/
+
+# 画像/日记等每主体记忆产物:运行时生成,归宿是对象存储而非代码仓库(见 TECH_DESIGN §3.3)。
+# 初始提交曾误纳入 115 个文件,且是多租户重构**之前**的扁平布局(var/memory/<subject>/),
+# 重构后的布局是 var/memory/<tenant>/<project>/<subject>/,旧数据已不会再被读到
+backend/var/
+
+# TS SDK 构建产物与依赖
+sdk/typescript/dist/
+sdk/typescript/node_modules/
+
+# 小程序 demo 里的内核拷贝:由 `cd sdk/typescript && npm run build:mp` 生成
+clients/miniprogram/lib/memcore/
+
+# LongMemEval 各臂的逐题产物(体积大;数据集 MIT,但产物是本地生成物)
+backend/evals/results/lme_arms/
+
+#
+node_modules
+out
+
+# 竞品调研的本地抓取产物：含**别家用户的真实凭据 / 会话 token**（明文 API key、
+# Bearer token 等）。绝不入库 —— 一个 git add -A 就会把它们连同活凭据一起提交。
+# 需要复现时在本地重新抓，不要留在版本库里。
+.chrome-debug-profile/
+
+# 竞品 APK 本地留档：Rokid 612MB + Looki 109MB，且是别人的闭源商业应用，
+# 提交进会推送的仓库等于再分发。解读文档与证据摘录(cmd 输出)才是可入库的部分,
+# 二进制只用于本地复核 —— 需要时按各文档「复现步骤」一章重新 adb pull。
+# 按后缀匹配而非 `apk/`，否则会把目录里说明用途的 README 一起挡掉。
+*.apk
+*.xapk
+
+# 竞品截图：含真实账号信息（用户名、头像、设备列表），绝不入库。
+# 需要复现时在本地重新用 adb 抓，不要留在版本库里。
+docs/competitors/*/截图/
+
+# macOS Finder 目录元数据：无内容价值，且每次打开目录就会变动制造噪声提交。
+# 按文件名匹配（任意层级），不要写成 `docs/.DS_Store` 这种单点写法。
+.DS_Store
+
+# 搬来的 kbflow 服务的 Rust 构建产物(与 backend/auth/target 同理)
+backend/kbflow/target/
+
+# kbflow 的上传落盘目录(KB_UPLOAD_ROOT)—— 里面是用户上传的文档,绝不入库
+backend/kbflow/var/
+# 小程序里的内核是 sdk/typescript 的构建产物(npm run build:mp 拷进去),clients/ 已改名 app/
+app/miniprogram/lib/

memcore_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.5
+Name: memcore-sdk
+Version: 0.3.0
+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")          # 绑定记忆主体,后续调用不必再传
+
+# 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 不存在
+```

memcore_sdk-0.3.0/README.md

@@ -0,0 +1,144 @@
+# 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")          # 绑定记忆主体,后续调用不必再传
+
+# 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 不存在
+```

memcore_sdk-0.3.0/example.py

@@ -0,0 +1,60 @@
+"""SDK 快速上手 —— 也是端到端测试。
+
+前置:后端在 localhost:8000 运行。
+    python example.py
+"""
+
+import uuid
+
+from memcore import Memcore
+
+mc = Memcore(base_url="http://localhost:8000")  # 生产环境传 api_key=
+user = mc.subject(f"demo-{uuid.uuid4().hex[:6]}")  # 绑定主体,后续调用不必再传
+
+print("1) 写入记忆(sync:写完立刻可查)")
+out = user.remember("我叫 Richard,住在上海,在做数据库产品,周末喜欢爬山。", sync=True)
+print(f"   抽出 {out.get('facts', 0)} 条记忆\n")
+
+print("2) 检索 + explain")
+hits = user.recall("他住在哪里", explain=True)
+for m in hits:
+    paths = list(m.why.matched_paths) if m.why else []
+    print(f"   · {m}  ← 命中路径 {paths}")
+if hits.budget:
+    b = hits.budget
+    print(f"   预算:返回 {b['items_returned']}/{b['items_considered']} 条,"
+          f"用了 {b['tokens_used']}/{b['token_budget']} token\n")
+
+print("3) 直接拼进你的 prompt(最常见用法)")
+print("   " + (hits.as_prompt().replace("\n", "\n   ") or "(空)") + "\n")
+
+print("4) 画像")
+p = user.profile()
+for s in p.slots[:5]:
+    print(f"   [{s.topic}/{s.sub_topic}] {s.projection}")
+print()
+
+print("5) 溯源:这条记忆怎么来的")
+if hits.facts:
+    lin = user.explain(hits.facts[0].id)
+    src = lin.get("source_messages") or []
+    gen = lin.get("generations") or []
+    print(f"   来源消息 {len(src)} 条;生成记录 {len(gen)} 条"
+          + (f",模型 {gen[0]['model']},prompt 哈希 {gen[0]['prompt_sha256'][:12]}…" if gen else ""))
+print()
+
+print("6) 遗忘(抽错了 → 作废但留痕)")
+if hits.facts:
+    user.forget(hits.facts[0].id, reason="示例:这条抽错了")
+    after = user.recall("他住在哪里")
+    print(f"   否决后再查:{len(after)} 条(原 {len(hits)} 条)")
+print()
+
+print("7) 审计账本")
+for e in user.audit(limit=5):
+    print(f"   {e['at'][:19]}  {e['action']}  {e['layer']}")
+
+print("\n清理:")
+receipt = user.forget(everything=True, reason="示例结束")
+print(f"   删除回执:{receipt['receipt']['deleted']}")
+mc.close()

memcore_sdk-0.3.0/memcore/__init__.py

@@ -0,0 +1,15 @@
+"""memcore — 通用记忆内核的 Python SDK。
+
+    from memcore import Memcore
+    mc = Memcore(api_key="mk_live_...")
+    user = mc.subject("user-42")
+    user.remember("我住在上海")
+    print(user.recall("我住在哪").as_prompt())
+"""
+
+from memcore.client import AsyncMemcore, AsyncSubject, Memcore, Subject
+from memcore.models import MemcoreError, Memory, Profile, ProfileSlot, RecallResult, Why
+
+__version__ = "0.3.0"
+__all__ = ["Memcore", "AsyncMemcore", "Subject", "AsyncSubject", "Memory", "Profile",
+           "ProfileSlot", "RecallResult", "Why", "MemcoreError"]