Metadata-Version: 2.4
Name: xingmind
Version: 8.10.4
Summary: 给 AI Agent 用的长期记忆层：改口可追溯、旧值不删只封口、多 Agent 共库不串味。纯 Python 零依赖。
Author: 黄迪尧 / 煋旺智能
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://gitee.com/xingwangzhineng/xingmind
Project-URL: Source, https://gitee.com/xingwangzhineng/xingmind
Project-URL: Changelog, https://gitee.com/xingwangzhineng/xingmind/blob/main/CHANGELOG.md
Project-URL: Documentation, https://gitee.com/xingwangzhineng/xingmind/blob/main/MCP%E6%8E%A5%E5%85%A5%E6%8C%87%E5%8D%97.md
Keywords: mcp,memory,agent,llm,long-term-memory,sqlite,ai
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 煋思维 XingMind

**给你的 AI Agent 装一个不会忘事、也不会记错事的脑子。**

AI 每次对话都从零开始：昨天说的事今天不记得，三个月前定的方案又被推翻一遍。
最难受的不是它忘了，是它记得半吊子——**旧方案和新方案一起端给你，还都说是你定的**。

这是给 Agent 用的**长期记忆层**——它不负责说话，只负责四件事：

- **记住**：一条事实只存一份，不堆一堆相似的话互相挤位置
- **找得回**：换个说法问也能捞出来，不是关键词硬匹配
- **改口记得住**：改了它认新的，旧的封口但还查得到（别处最容易翻车的地方）
- **共用不打架**：多个 Agent 读同一个脑袋，互不串味，谁也不能乱改谁的

纯 Python，零第三方依赖，全部记忆装在一个 SQLite 文件里。备份就是拷一个文件。

```
pip 不用装 | 数据库不用起 | 一个 .db 就完事
```

> **同一模型、同一套 500 道题：装上它答对 461，不装答对 389，净多 72 题（+14.4pp）。**
> 这 +72 才是记忆层自己的功劳。别家公开分数换了答题模型，绝对值不能直接比，详见 [成绩](#成绩)。

**先看效果，3 分钟，不用装任何东西：**

```bash
python examples/quickstart.py
```

它会演四件事：记住 → 换个说法还能找回来 → **改主意了它记得新的、旧的还查得到** →
两个 Agent 共用一个库互不串味。全程本地，不调模型，不联网。

---

## 它治什么病

市面上的做法大多停在"把对话存成向量，检索最近似的几条拼进去"。这能治一部分，但治不了这四种：

- **改口了它还记着老版本** —— 你说"改用 Postgres"，它下次还推荐 SQLite
- **记住了一堆相似的废话** —— 同一件事存了八遍，检索时互相挤占位置
- **换个 Agent 就全忘了** —— 每个工具各存一份，谁也不认谁的
- **多个 Agent 互相改对方的记忆** —— 没有"谁能改谁的"这条规矩

## 怎么治的

**① 冲突不是覆盖，是封口。**
新事实推翻旧事实时，链条是这样的：**模型判断"这两句是不是同一件事的改口" → 代码执行封口**。
旧值不删，只标上失效时间；新值作为独立条目入库，指向它推翻了谁。
所以既能查到"现在的答案"，也能回查"以前是什么、什么时候改的"。

**② 去重不用阈值拍脑袋。**
词法（字符 bi-gram）+ 语义（词级 Jaccard）两路，同层同项目才比，跨层同名不误伤。

**③ 证据是编排出来的，不是堆出来的。**
先判断问题属于哪一类，再决定哪几块证据该出声、谁给谁让位。
这张表是拿错题换来的——不是设计出来的漂亮架构图。

**④ 一条记忆只有一个主人。**
四档可见范围（全局 / 同组 / 私有 / 绝密）。别人只能给你的记忆提建议，等你合并。
不是 `user_id` 分区那种"各存各的"，是"谁能改谁的"这条规矩。

## 30 秒上手

```python
from xingmind import Memory

mem = Memory("./my_memory")

# 记（type 和 mtype 两种写法都认，跟 CLI / MCP 保持一致）
mem.remember("数据库选型", "决定用 SQLite 做单文件总库，写入毫秒级，零依赖。",
             type="decision", importance=4)

# 答一道题（召回 → 精炼 → 补算 → 拼证据，一次做完）
ctx = mem.recall_context("我们用什么数据库存数据？")
print(ctx["context"])
```

## 别人做不到的那一手：改口

这是最容易被忽略、也最容易被用户骂的地方——**你明明说了换方案，它下次还在推荐旧的**。

```python
# 三个月后你改主意了
r = mem.remember("数据库选型", "改了：不用 SQLite 了，改用 Postgres，因为要多人同时写。",
                 type="decision", smart=True)      # smart=True 才会查重 + 判改口

print(r["action"])       # updated —— 不是新增一条，是"接上"
print(r["version"])      # 2

# 现在问它，答的是 Postgres
mem.recall_context("我们数据库用的是什么？")

# 但历史没丢：这条改过几次、每版是什么、哪版作数
print(mem.causal(r["mid"])["summary"])
# → "这条一共 2 个版本：v1 → v2（现在）。旧版本内容保留，可回查，只是不再参与检索。"
```

区别在哪：**覆盖式**方案把旧值删了（下次你想不起当初为什么改）；
**只留最新**方案连改过都看不出来。这里的旧版本**内容保留、只是封口**——
既能查到现在的答案，也能回查哪一天改的、改之前是什么。

或者接进任何支持 MCP 的客户端（Claude Desktop / Cursor / Cline / Claude Code）：

```bash
pip install xingmind
```

```json
{"mcpServers": {"xingmind": {"command": "xingmind-mcp"}}}
```

**就这四行，一个路径都不用填。** 记忆库默认在 `~/.xingmind`，
几个宿主自动共用同一份——在 Cursor 里记的事，Claude Desktop 里也查得到。

不想装包、要直接跑源码，或者挂上之后行为不对，见 **[MCP 接入指南](MCP接入指南.md)**
（含四个宿主的配置文件位置、三条必踩的坑、故障对照表）。

装完不放心，先跑这一行验证服务端自己是活的（不依赖任何客户端）：

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | xingmind-mcp
```

命令行也一样能干活（20 个子命令）：

```bash
python scripts/memory_manager.py --path ./my_memory add \
  --title "报价口径" --content "对外报价一律人民币结算" --type decision
python scripts/memory_manager.py --path ./my_memory search "报价用什么货币"
```

## 三个入口，同一份记忆

| 入口 | 用法 | 适合 |
|---|---|---|
| Python | `mem.recall_context(...)` | 自己写 Agent |
| MCP | stdio JSON-RPC，6 个工具 | Claude Desktop / Cursor / 任何 MCP 客户端 |
| CLI | `memory_manager.py <cmd>` | 脚本、运维、手工查 |

三者读写同一个 `.db`。实测（`eval/probe_interop.py`，3×3 九格 × 3 轮）：
**看得见 27/27、一字不差 27/27、零乱码**；MCP 与 CLI 各起 3 个进程同时写，**零丢失**。

## 成绩

在 LongMemEval-S 500 题上，自家实测 **461/500（92.2%）**。

需要强调两点，避免误读：

- **这是自家跑的，不是第三方复现**，答题模型是 DeepSeek V4.1 Flash
- 各家公开分数用的答题模型不同，**不能横向比绝对值**
- 唯一能横向比的数字：**同一个模型下，装上本记忆层答对 461 题，不装答对 389 题，净多 72 题**。这 +72 才是记忆层自己的功劳

## 它不做什么

诚实地说清边界，比承诺全能更有用：

- **不做向量语义检索**（默认）。本机没跑过真 embedding 模型，所以不吹"语义理解"。
  哈希字符向量那条路实测无效，已经不用了
- **不托管任何 API key**，不挑模型，不联网
- **不做后台常驻进程**（会抢资源、抢焦点）。要自动写入，请用会话钩子调 `absorb`
- **25 个实验性认知模块**（联想 / 反事实 / 好奇心…）目前**主干零调用**，
  在 `scripts/experimental/`。转正条件只有一个：配对重复测出"带它比不带它好"

## 许可：双许可

| 你是什么情况 | 用哪条 | 付钱吗 |
|---|---|---|
| 个人用 / 学习 / 研究 | AGPL-3.0 | 不要 |
| **公司内部使用**（数据不出门、不对外服务） | AGPL-3.0 | **不要** |
| 开源项目（衍生作品也用 AGPL） | AGPL-3.0 | 不要 |
| 嵌进你要卖的产品 / 做成 SaaS / 要闭源 | **商业授权** | 要 |

- 开源全文：[`LICENSE`](LICENSE)（AGPL-3.0）
- 商用范围与谈法：[`COMMERCIAL.md`](COMMERCIAL.md)
- 提交代码前请签：[`CLA.md`](CLA.md)

> 说人话：你可以随便看、随便改、自己公司内部随便用。
> 靠它赚钱（嵌进产品卖 / 做成服务卖 / 不愿开源）才需要买授权。

## 示例

| 文件 | 演什么 |
|---|---|
| [`examples/quickstart.py`](examples/quickstart.py) | 四件事走一遍：记住 / 找回 / 改口 / 隔离 |

## 文档

| 文件 | 给谁看 |
|---|---|
| [`MCP接入指南.md`](MCP接入指南.md) | 想挂到自己 AI 工具上的人，照抄就能用 |
| [`SKILL.md`](SKILL.md) | 给 AI 看的完整用法手册 |
| [`CHANGELOG.md`](CHANGELOG.md) | 每次改了什么、为什么改 |
| [`COMMERCIAL.md`](COMMERCIAL.md) | 想商用的人 |
| [`CLA.md`](CLA.md) | 想提 PR 的人 |

## 跑测试

```bash
python -m pytest scripts/tests -q
```

171 条测试。覆盖冲突消解、去重、作用域隔离、并发、MCP 协议、**MCP 官方客户端兼容**、
三入口互通、备份还原、「装到别人机器上路径会不会歪」，以及**模型给错参数类型时的行为**
（tags 传数组、dry_run 传 `"false"` 字符串、level 传 `"FULL"`、layer 传不存在的层）。
