recallweaver 1.2.0__tar.gz

recallweaver-1.2.0/.gitignore

@@ -0,0 +1,3 @@
+.venv/ 
+__pycache__/ 
+*.db 

recallweaver-1.2.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.5
+Name: recallweaver
+Version: 1.2.0
+Summary: A lightweight local memory engine for AI agents
+Requires-Python: ==3.11.9
+Requires-Dist: click>=8.1
+Requires-Dist: fastapi>=0.110
+Requires-Dist: openai>=1.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.7
+Requires-Dist: uvicorn>=0.27
+Provides-Extra: test
+Requires-Dist: httpx>=0.27; extra == 'test'
+Requires-Dist: pytest-mock>=3.14; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# 🧠 织忆 (RecallWeaver)
+
+**赋予 LLM Agent 穿越时间的记忆能力。零 Docker、零向量库、纯单文件 SQLite 构筑的工业级 AI 海马体。**
+
+<p align="center">
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.11+"></a>
+  <a href="#"><img src="https://img.shields.io/badge/Tests-Passing-brightgreen?style=for-the-badge&logo=pytest&logoColor=white" alt="Tests Passing"></a>
+  <a href="#"><img src="https://img.shields.io/badge/Latency-10ms-blueviolet?style=for-the-badge&logo=speedtest&logoColor=white" alt="Latency 10ms"></a>
+  <a href="#"><img src="https://img.shields.io/badge/Precision-1.0-success?style=for-the-badge" alt="Precision 1.0"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="MIT License"></a>
+</p>
+
+![Demo](./assets/demo.gif)
+
+> 看！大肥鱼在真实 DeepSeek 环境下，如何利用纯本地记忆识破主人的花生过敏陷阱，并完成北京到杭州的时空转移。
+
+**无需 Docker，无需向量数据库，也不必把整段对话塞进上下文。** RecallWeaver 为 Agent 提供可演变、可检索、会遗忘的长期记忆。
+
+[核心特性](#-核心高光特性) · [性能与质量](#-性能与质量验证) · [快速开始](#-快速开始) · [架构](#-项目架构)
+
+---
+
+## 💥 为什么选择 RecallWeaver？
+
+传统 RAG 记忆方案经常把“检索到文本”误当成“理解了事实”。当对话变长、事实更新、闲聊增多时，常见问题会逐渐显现：
+
+| 传统方案的痛点 | 可能造成的结果 |
+|---|---|
+| 🕰️ **时间逻辑混乱** | “以前住在北京”与“现在住在杭州”同时进入上下文，Agent 前后矛盾，像是“精神分裂”。 |
+| 🔊 **高频噪音挤占上下文** | 股票涨跌、天气闲聊等高频内容挤掉过敏、住址等真正重要的事实。 |
+| 🧱 **部署成本高** | 重型向量库、图数据库和配套服务带来额外的部署、运维与资源成本。 |
+
+### RecallWeaver 的破局方式
+
+以**单文件 SQLite** 为持久化核心，结合**双时间戳事实版本**与**动态遗忘评分**：事实更新时保留历史并关闭旧版本；检索时综合相关性、时效与权重，并通过分数阈值过滤低价值噪音。轻量部署，也能明确回答“现在是什么”以及“以前是什么”。
+
+---
+
+## 📊 性能与质量验证
+
+以下为项目压测与评测记录中的结果：
+
+### 🔥 并发与长稳压测
+
+| 持续时间 | 并发线程 | 总请求数 | 成功率 | 死锁 | P99 延迟 |
+|---:|---:|---:|---:|---:|---:|
+| 1,800 秒 | 50 | 180,000 | **100%** | **0** | **10.5 ms** |
+
+### 🎯 检索质量评估
+
+基于 100 组高仿真测试数据，评估检索结果与核心事实标准答案的一致性：
+
+| Precision | Recall | F1-Score | 评测样本 |
+|---:|---:|---:|---:|
+| **1.0000** | **1.0000** | **1.0000** | 100 组 |
+
+### 🧪 混沌工程边界验证
+
+| 场景 | 验证结果 |
+|---|---|
+| SQL 注入文本 | 参数化查询防护通过 |
+| 高频恶意检索刷分 | 权重加成上限与噪音阈值拦截通过 |
+| 空数据库调用 | 空结果兜底通过 |
+
+> 这些数字是项目当前记录的基准结果。实际表现会随硬件、SQLite 版本、数据集和运行配置变化。
+
+---
+
+## ✨ 核心高光特性
+
+### 🕰️ 双时间戳时空图谱 (Temporal Graph)
+
+事实带有 `valid_from` 与 `valid_to`。同一主谓关系发生冲突时，系统在事务中关闭旧事实并写入新事实，历史不被覆盖。基于 SQLite 递归 CTE 的图谱遍历支持多跳关系查询，让 Agent 能区分事实的当前状态与历史状态。
+
+### 📉 动态遗忘打分池 (Decay Pool)
+
+以指数衰减为基础，综合记忆权重与检索反馈计算候选得分。检索次数的加成受有用性权重和上限约束；最终结果还会经过分数阈值截断，避免无关闲聊仅凭频繁出现就长期霸屏。
+
+### ⚡ 混合检索 (Hybrid Search)
+
+结合 SQLite FTS5 全文检索与图谱召回，再由衰减引擎统一重排。FTS5 的 `trigram` 分词支持中文连续子串匹配；结构化事实则可通过图谱关系查找，互补关键词召回与事实关联。
+
+### 🔎 可观测、可解释
+
+通过结构化日志、Trace ID 与线程安全指标记录核心链路状态。召回结果包含来源、分数及有效时间信息，便于排查与理解 Agent 为什么记住或忽略某条信息。
+
+---
+
+## 🚀 快速开始
+# 启动 API 服务
+uvicorn src.recallweaver.server:app --reload
+
+### 1. 克隆并安装
+
+```bash
+git clone https://github.com/gaoweimax/recallweaver.git
+cd recallweaver
+python -m pip install -e .
+```
+
+### 2. 配置 DeepSeek 密钥
+
+示例使用环境变量读取密钥。请替换为你自己的密钥，**不要把真实密钥写入代码或提交到仓库**。
+
+```bash
+export DEEPSEEK_API_KEY="sk-..."
+```
+
+Windows PowerShell 可使用：
+
+```powershell
+$env:DEEPSEEK_API_KEY = "sk-..."
+```
+
+### 3. 写入事实并检索
+
+```python
+from recallweaver.api import RecallWeaverAPI
+
+api = RecallWeaverAPI(db_path="recallweaver.db")
+
+# 记录结构化事实
+api.remember_triple(
+    subject="张三",
+    predicate="住在",
+    object_="杭州",
+)
+
+# 检索与问题相关的记忆
+results = api.recall("张三住在哪里？", limit=3)
+for memory in results:
+    print(f"[{memory.score:.3f}] {memory.content or memory.object}")
+```
+
+运行带真实 DeepSeek API 的 Rich 终端示例：
+
+```bash
+python examples/deepseek_agent.py
+```
+
+---
+
+## 🏗️ 项目架构
+
+```text
+src/recallweaver/
+├── api.py                 # 统一 API 门面与输入校验
+├── config.py              # L1：环境与配置管理
+├── errors.py              # 领域异常定义
+├── db.py                  # SQLite 连接、事务与重试
+├── models.py              # Pydantic 输入/输出模型
+├── memory_manager.py      # 记忆持久化与双时间戳冲突处理
+├── graph.py               # 图谱关系查询与递归 CTE
+├── retrieval.py           # FTS5 与图谱混合检索、结果重排
+├── decay_engine.py        # L3：衰减评分、有用性权重与阈值过滤
+├── extraction/            # 实体与事实抽取组件
+└── observability/
+    ├── logging.py         # 结构化日志与敏感信息处理
+    └── metrics.py         # 线程安全的内存指标
+```
+
+模块按职责拆分：**L1 配置与校验**提供稳定边界，**L3 检索与衰减算法**专注记忆质量，**L6 可观测性**提供日志和运行指标。架构取舍与演进记录见 [`docs/adr/`](docs/adr/)。
+
+---
+
+## 🧑‍💻 开发与测试
+
+安装开发依赖后，可运行单元与集成测试：
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -v
+```
+
+检索基准脚本：
+
+```bash
+python benchmarks/bench_retrieval.py
+```
+
+## 🤝 参与贡献
+
+欢迎通过 Issue 讨论问题、提交改进建议或贡献代码。涉及行为变更时，请一并补充相应测试与文档。
+
+## 📄 开源协议
+
+RecallWeaver 采用 [MIT License](LICENSE)。

recallweaver-1.2.0/README.md

@@ -0,0 +1,187 @@
+# 🧠 织忆 (RecallWeaver)
+
+**赋予 LLM Agent 穿越时间的记忆能力。零 Docker、零向量库、纯单文件 SQLite 构筑的工业级 AI 海马体。**
+
+<p align="center">
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.11+"></a>
+  <a href="#"><img src="https://img.shields.io/badge/Tests-Passing-brightgreen?style=for-the-badge&logo=pytest&logoColor=white" alt="Tests Passing"></a>
+  <a href="#"><img src="https://img.shields.io/badge/Latency-10ms-blueviolet?style=for-the-badge&logo=speedtest&logoColor=white" alt="Latency 10ms"></a>
+  <a href="#"><img src="https://img.shields.io/badge/Precision-1.0-success?style=for-the-badge" alt="Precision 1.0"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="MIT License"></a>
+</p>
+
+![Demo](./assets/demo.gif)
+
+> 看！大肥鱼在真实 DeepSeek 环境下，如何利用纯本地记忆识破主人的花生过敏陷阱，并完成北京到杭州的时空转移。
+
+**无需 Docker，无需向量数据库，也不必把整段对话塞进上下文。** RecallWeaver 为 Agent 提供可演变、可检索、会遗忘的长期记忆。
+
+[核心特性](#-核心高光特性) · [性能与质量](#-性能与质量验证) · [快速开始](#-快速开始) · [架构](#-项目架构)
+
+---
+
+## 💥 为什么选择 RecallWeaver？
+
+传统 RAG 记忆方案经常把“检索到文本”误当成“理解了事实”。当对话变长、事实更新、闲聊增多时，常见问题会逐渐显现：
+
+| 传统方案的痛点 | 可能造成的结果 |
+|---|---|
+| 🕰️ **时间逻辑混乱** | “以前住在北京”与“现在住在杭州”同时进入上下文，Agent 前后矛盾，像是“精神分裂”。 |
+| 🔊 **高频噪音挤占上下文** | 股票涨跌、天气闲聊等高频内容挤掉过敏、住址等真正重要的事实。 |
+| 🧱 **部署成本高** | 重型向量库、图数据库和配套服务带来额外的部署、运维与资源成本。 |
+
+### RecallWeaver 的破局方式
+
+以**单文件 SQLite** 为持久化核心，结合**双时间戳事实版本**与**动态遗忘评分**：事实更新时保留历史并关闭旧版本；检索时综合相关性、时效与权重，并通过分数阈值过滤低价值噪音。轻量部署，也能明确回答“现在是什么”以及“以前是什么”。
+
+---
+
+## 📊 性能与质量验证
+
+以下为项目压测与评测记录中的结果：
+
+### 🔥 并发与长稳压测
+
+| 持续时间 | 并发线程 | 总请求数 | 成功率 | 死锁 | P99 延迟 |
+|---:|---:|---:|---:|---:|---:|
+| 1,800 秒 | 50 | 180,000 | **100%** | **0** | **10.5 ms** |
+
+### 🎯 检索质量评估
+
+基于 100 组高仿真测试数据，评估检索结果与核心事实标准答案的一致性：
+
+| Precision | Recall | F1-Score | 评测样本 |
+|---:|---:|---:|---:|
+| **1.0000** | **1.0000** | **1.0000** | 100 组 |
+
+### 🧪 混沌工程边界验证
+
+| 场景 | 验证结果 |
+|---|---|
+| SQL 注入文本 | 参数化查询防护通过 |
+| 高频恶意检索刷分 | 权重加成上限与噪音阈值拦截通过 |
+| 空数据库调用 | 空结果兜底通过 |
+
+> 这些数字是项目当前记录的基准结果。实际表现会随硬件、SQLite 版本、数据集和运行配置变化。
+
+---
+
+## ✨ 核心高光特性
+
+### 🕰️ 双时间戳时空图谱 (Temporal Graph)
+
+事实带有 `valid_from` 与 `valid_to`。同一主谓关系发生冲突时，系统在事务中关闭旧事实并写入新事实，历史不被覆盖。基于 SQLite 递归 CTE 的图谱遍历支持多跳关系查询，让 Agent 能区分事实的当前状态与历史状态。
+
+### 📉 动态遗忘打分池 (Decay Pool)
+
+以指数衰减为基础，综合记忆权重与检索反馈计算候选得分。检索次数的加成受有用性权重和上限约束；最终结果还会经过分数阈值截断，避免无关闲聊仅凭频繁出现就长期霸屏。
+
+### ⚡ 混合检索 (Hybrid Search)
+
+结合 SQLite FTS5 全文检索与图谱召回，再由衰减引擎统一重排。FTS5 的 `trigram` 分词支持中文连续子串匹配；结构化事实则可通过图谱关系查找，互补关键词召回与事实关联。
+
+### 🔎 可观测、可解释
+
+通过结构化日志、Trace ID 与线程安全指标记录核心链路状态。召回结果包含来源、分数及有效时间信息，便于排查与理解 Agent 为什么记住或忽略某条信息。
+
+---
+
+## 🚀 快速开始
+# 启动 API 服务
+uvicorn src.recallweaver.server:app --reload
+
+### 1. 克隆并安装
+
+```bash
+git clone https://github.com/gaoweimax/recallweaver.git
+cd recallweaver
+python -m pip install -e .
+```
+
+### 2. 配置 DeepSeek 密钥
+
+示例使用环境变量读取密钥。请替换为你自己的密钥，**不要把真实密钥写入代码或提交到仓库**。
+
+```bash
+export DEEPSEEK_API_KEY="sk-..."
+```
+
+Windows PowerShell 可使用：
+
+```powershell
+$env:DEEPSEEK_API_KEY = "sk-..."
+```
+
+### 3. 写入事实并检索
+
+```python
+from recallweaver.api import RecallWeaverAPI
+
+api = RecallWeaverAPI(db_path="recallweaver.db")
+
+# 记录结构化事实
+api.remember_triple(
+    subject="张三",
+    predicate="住在",
+    object_="杭州",
+)
+
+# 检索与问题相关的记忆
+results = api.recall("张三住在哪里？", limit=3)
+for memory in results:
+    print(f"[{memory.score:.3f}] {memory.content or memory.object}")
+```
+
+运行带真实 DeepSeek API 的 Rich 终端示例：
+
+```bash
+python examples/deepseek_agent.py
+```
+
+---
+
+## 🏗️ 项目架构
+
+```text
+src/recallweaver/
+├── api.py                 # 统一 API 门面与输入校验
+├── config.py              # L1：环境与配置管理
+├── errors.py              # 领域异常定义
+├── db.py                  # SQLite 连接、事务与重试
+├── models.py              # Pydantic 输入/输出模型
+├── memory_manager.py      # 记忆持久化与双时间戳冲突处理
+├── graph.py               # 图谱关系查询与递归 CTE
+├── retrieval.py           # FTS5 与图谱混合检索、结果重排
+├── decay_engine.py        # L3：衰减评分、有用性权重与阈值过滤
+├── extraction/            # 实体与事实抽取组件
+└── observability/
+    ├── logging.py         # 结构化日志与敏感信息处理
+    └── metrics.py         # 线程安全的内存指标
+```
+
+模块按职责拆分：**L1 配置与校验**提供稳定边界，**L3 检索与衰减算法**专注记忆质量，**L6 可观测性**提供日志和运行指标。架构取舍与演进记录见 [`docs/adr/`](docs/adr/)。
+
+---
+
+## 🧑‍💻 开发与测试
+
+安装开发依赖后，可运行单元与集成测试：
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -v
+```
+
+检索基准脚本：
+
+```bash
+python benchmarks/bench_retrieval.py
+```
+
+## 🤝 参与贡献
+
+欢迎通过 Issue 讨论问题、提交改进建议或贡献代码。涉及行为变更时，请一并补充相应测试与文档。
+
+## 📄 开源协议
+
+RecallWeaver 采用 [MIT License](LICENSE)。

recallweaver-1.2.0/benchmarks/ablation.py

@@ -0,0 +1,147 @@
+"""Run a compact ablation of recency ranking and temporal fact resolution.
+
+The script compares normal API recall with a recency-only baseline, then
+contrasts unversioned text history with the graph's current fact timeline.
+All experiments use temporary SQLite databases and leave no project data.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from recallweaver.api import RecallWeaverAPI
+
+QUERY = "张三吃啥"
+CORE_FACT = "朋友问张三吃啥？张三对花生过敏，不能吃花生。"
+NOISE_COUNT_BEFORE = 100
+NOISE_COUNT_AFTER = 50
+
+
+def _write_noise(api: RecallWeaverAPI, count: int, offset: int) -> None:
+    """Write unrelated chatter records with stable, unique contents.
+
+    Args:
+        api: API instance backed by an experiment-only database.
+        count: Number of chatter memories to add.
+        offset: Starting sequence number for unique chatter text.
+    """
+    for index in range(offset, offset + count):
+        api.add_memory(
+            f"群聊闲聊{index:03d}：今天天气不错，晚饭吃了米饭和青菜。"
+        )
+
+
+def _run_recall_ablation(api: RecallWeaverAPI) -> None:
+    """Compare decay-aware recall with a recency-only ranking baseline.
+
+    Args:
+        api: API instance containing the 151-record recall corpus.
+    """
+    _write_noise(api, NOISE_COUNT_BEFORE, 0)
+    core_memory_id = api.add_memory(CORE_FACT)
+    _write_noise(api, NOISE_COUNT_AFTER, NOISE_COUNT_BEFORE)
+
+    recall_results = api.recall(QUERY, limit=NOISE_COUNT_BEFORE + 1)
+    assert recall_results, "完整流程没有召回任何结果"
+    assert recall_results[0].memory_id == core_memory_id, (
+        "完整流程中核心事实没有排在第 1 位"
+    )
+    assert "花生过敏" in recall_results[0].content
+
+    with api.database_manager.get_connection() as conn:
+        recency_rows = conn.execute(
+            """
+            SELECT id, content
+            FROM memories
+            WHERE tenant_id = ?
+            ORDER BY rowid DESC
+            """,
+            ("default",),
+        ).fetchall()
+    recency_results: list[dict[str, Any]] = [
+        dict(row) for row in recency_rows
+    ]
+    core_positions = [
+        index
+        for index, row in enumerate(recency_results, start=1)
+        if row["id"] == core_memory_id
+    ]
+    assert len(recency_results) == (
+        NOISE_COUNT_BEFORE + 1 + NOISE_COUNT_AFTER
+    ), "消融基线数据条数不符合预期"
+    assert core_positions == [NOISE_COUNT_AFTER + 1], (
+        "仅按写入顺序排序时，核心事实未落在第 51 位"
+    )
+    assert all(
+        "群聊闲聊" in row["content"]
+        for row in recency_results[:NOISE_COUNT_AFTER]
+    ), "核心事实之前的最近 50 条记录应全部为无关噪音"
+
+    print("实验组 A（完整检索流程）")
+    print(f"  查询：{QUERY}")
+    print(f"  Top-1：{recall_results[0].content}")
+    print("  结果：核心事实排在第 1 位")
+    print("实验组 B（消融：忽略相关性与衰减，仅按最近写入排序）")
+    print(f"  最近写入的噪音：{NOISE_COUNT_AFTER} 条")
+    print(f"  核心事实排名：第 {core_positions[0]} 位")
+    print("  结果：核心事实被最近写入的闲聊挤到第 51 位")
+
+
+def _run_graph_ablation(db_path: Path) -> None:
+    """Contrast unversioned text retrieval with graph fact history.
+
+    Args:
+        db_path: Temporary database path reserved for this experiment.
+    """
+    api = RecallWeaverAPI(str(db_path))
+    api.add_memory("张三住在北京。")
+    api.remember_triple("张三", "住在", "北京")
+    api.add_memory("张三住在上海。")
+    api.remember_triple("张三", "住在", "上海")
+
+    with api.database_manager.get_connection() as conn:
+        text_rows = conn.execute(
+            """
+            SELECT content
+            FROM memories
+            WHERE tenant_id = ? AND content LIKE ?
+            ORDER BY rowid
+            """,
+            ("default", "%张三住在%"),
+        ).fetchall()
+    text_results = [str(row["content"]) for row in text_rows]
+    assert len(text_results) == 2, "文本基线应同时返回两条居住地记忆"
+    assert any("北京" in content for content in text_results)
+    assert any("上海" in content for content in text_results)
+
+    history = api.get_history("张三", "住在")
+    assert len(history) == 2, "图谱历史应保留两个事实版本"
+    current_facts = [fact for fact in history if fact["valid_to"] is None]
+    assert len(current_facts) == 1, "图谱必须只保留一个当前有效事实"
+    assert current_facts[0]["object"] == "上海"
+
+    print("实验组 C（消融：仅查文本，不读取图谱有效状态）")
+    print(f"  文本结果：{'；'.join(text_results)}")
+    print("  结果：北京和上海同时出现，无法判断当前事实")
+    print("  图谱时间线：")
+    for fact in history:
+        state = "当前有效" if fact["valid_to"] is None else "已失效"
+        print(
+            f"    {fact['object']}：{state} "
+            f"(valid_from={fact['valid_from']}, valid_to={fact['valid_to']})"
+        )
+
+
+def main() -> None:
+    """Execute all ablation cases using isolated temporary databases."""
+    with tempfile.TemporaryDirectory(prefix="recallweaver-ablation-") as directory:
+        root = Path(directory)
+        recall_api = RecallWeaverAPI(str(root / "recall-ablation.sqlite3"))
+        _run_recall_ablation(recall_api)
+        _run_graph_ablation(root / "graph-ablation.sqlite3")
+
+
+if __name__ == "__main__":
+    main()