Metadata-Version: 2.4
Name: nexsandglass
Version: 2.10.4
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.4-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)

---

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

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

---

## 快速开始

```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
```

**MCP 用户：**
```bash
git clone https://github.com/lovevin1314-tech/NexSandglass-Agent-DedicatedMemory
python sandglass_mcp.py
```

**Docker：**
```bash
docker-compose up -d
```

---

## 与现有方案对比

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

---

## 五大支柱

| 支柱 | 做什么 |
|------|--------|
| 🧬 管道聚合画像 | fact_tags + decision_particles → 越用越懂你 |
| 📊 偏移率 | 省钱/愿投/放弃 三维量化 + 跨阶段对比 |
| 🔍 搜索滤镜 | 六维感知扩展关键词 |
| 🧵 织布机 | 四支柱合成 + 矛盾检测 |
| 🪡 织线 | 正则三元组，纯本地因果链 |

---

## 设计原则

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

---

## 性能基准

| 层 | 操作 | median | p99 |
|----|------|--------|------|
| **L1 写** | 单次落沙 | **4.3ms** | 19.5ms |
| **L2 搜** | FTS5搜索 | **1.6ms** | 5.4ms |
| | 影子沙 | **0.7ms** | 1.2ms |
| | 四路并发 | 79.4ms | — |
| **L3 思** | 偏移率 | **<0.1ms** | — |
| | 情绪熵(会话级) | 6.5ms | — |
| | 心理预判 | 7.0ms | — |
| | 铁律因子 | **<0.1ms** | — |

> 测试：5900条 · Windows 10 · i5-8265U · Python 3.11 · 完全隔离

---

## 版本历程

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

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

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