Metadata-Version: 2.4
Name: nexsandglass
Version: 2.10.3
Summary: 沙漏记忆系统 — 纯本地零依赖L3思考层
Home-page: https://github.com/lovevin1314-tech/NexSandglass-Agent-DedicatedMemory
Author: NeuroBase
Project-URL: Homepage, https://github.com/lovevin1314-tech/NexSandglass-Agent-DedicatedMemory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# NexSandglass ⏳ — 沙漏记忆系统

> **`pip install nexsandglass`** · 纯本地 · 零依赖 · 零 API Key

[![PyPI](https://img.shields.io/badge/PyPI-2.10.3-blue)](https://pypi.org/project/nexsandglass/)
[![Python](https://img.shields.io/badge/Python-3.11+-blue)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

---

**不是记住你说过什么——是理解你怎么变成今天的你。**

投石问路 + 影子沙双引擎搜索 · 偏移率感知 · 管道聚合画像 · 四层问答式极简注入。纯本地，零依赖，越用越懂你。

| 特性 | 说明 |
|------|------|
| 🔍 四路并发搜索 | 影子沙 + FTS5 + IDX + TF-IDF，毫秒级响应 |
| 🧬 偏移率追踪 | 省钱/愿投/放弃 三维量化 + 决策疲劳检测 |
| 🎭 管道聚合画像 | fact_tags + decision_particles → 越用越懂你 |
| 💉 极简注入 | ~60 tokens，LLM 一眼看懂 |
| 🔒 全本地 | 数据不出设备，OS 层全盘加密 |
| 🚀 一键安装 | `pip install nexsandglass` |

---

## 快速开始

```bash
pip install nexsandglass
```

```python
from sandglass_vault import search, count
from sandglass_log import log_message

log_message("今天讨论了搜索排序优化", "user")
print(search("搜索排序"))  # 毫秒级返回
print(f"沙漏总量: {count()}条")
```

**Hermes 用户：**
```bash
hermes plugins install lovevin1314-tech/NexSandglass
# 重启 Desktop → 设置 → 记忆体 → 选择 NexSandglass
```

---

## 与现有方案对比

| 维度 | Mem0 / Letta | NexSandglass |
|------|:---:|:---:|
| 依赖 | 向量数据库+N个包 | **零依赖，纯 stdlib** |
| 注入量 | ~200-22000t | **~60t** |
| 决策追踪 | ❌ | **决策粒子+偏移率+心理预判** |
| 情绪感知 | ❌ | **情绪熵（会话级摘要）** |
| 画像溯源 | ❌ | **可追溯到行号** |
| 搜索 | 向量检索 | **四路并发（影子沙+FTS5+IDX+TF-IDF）** |
| 安装 | 服务栈 | **pip install** |

---

## 版本历程

### V2.10 — PyPI 发布
`pip install nexsandglass` — 全球 AI Agent 一键安装。两段式轮次注入(60t)，DB 自省增量启动，沙子自愈。

### V2.9 — 极简注入 + 纯本地化
四路并发搜索 + 管道聚合画像 + 去 LLM 全链路闭环。偏移率·纠结度·铁律因子·Porter Stemmer。

### V1.x — 奠基
偏移率·情绪感知·决策粒子·影子沙·织布机·场景系统

---

## 设计原则

1. **层追加不替换** — 新层叠加，永不修改下层
2. **纯本地** — Python stdlib + SQLite，零外部依赖
3. **极简注入** — 每轮 ~60t，LLM 按需搜索
4. **越用越懂你** — 管道数据随沙子自然积累

---

## 性能基准

| 层 | 操作 | median |
|----|------|--------|
| L1 写 | 单次落沙 | **4.3ms** |
| L2 搜 | FTS5搜索 | **1.6ms** |
| | 影子沙 | **0.7ms** |
| L3 思 | 偏移率 | **<0.1ms** |
| | 铁律因子 | **<0.1ms** |

> 测试：5900条 · Windows 10 · i5-8265U · Python 3.11
