内容
# 🧠 超记忆场
[](https://github.com/armandojaleo/hipercampo/actions/workflows/ci.yml)
🌍 **西班牙语版本： [README.es.md](README.es.md)** · 您正在阅读中文版本。
**为 Claude 构建的记忆系统，基于超向量 —— 而非嵌入式。**
大多数大型语言模型的记忆系统都是相同的：分割文本，转换为密集向量，并检索最接近的向量（ANN / top-k）。这种方法衡量的是**相似性**，而非**相关性**、**重要性**，并且它永远不会**遗忘**。这就像一个带有搜索框的垃圾场。
`hipercampo` 尝试了一种不同的方法。它是一个 **MCP** 服务器，为 Claude 提供了一种模拟海马体的记忆模式，整合了四个相互关联的理念：
| 理念 | 功能 | 灵感来源 |
|------|--------------|-------------|
| **VSA / 超向量** | 将记忆表示为 10,000 位的二进制向量，并使用实数代数（`bind` / `bundle`）。它能区分 *"狗咬人"* 和其逆序 —— 而密集嵌入式会模糊这种区别。运行于 CPU，使用 popcount，无需 GPU。 | Kanerva (SDM)，Plate (HRR) |
| **惊喜门控写入** | 双重否决：不会存储**冗余**（存在类似内容）或**可预测**（内部增量语言模型已预测，衡量单位为比特 —— 压缩 / MDL）的内容。这就是 token 节省的作用（尚未进行端到端测量）。 | 海马体预测误差；压缩即智能（Hutter） |
| **巩固（睡眠）** | 离线过程将相似的事件**分组**为语义记忆（结构分组：减少节点，连接文本；可选 `summarizer` 真正凝聚）并存档原始内容。 | 海马体 → 大脑皮层重放 |
| **主动遗忘** | 强度随使用而衰减；弱记忆变为**休眠**（不会删除，如人类大脑）并可通过 `hc_muse` **重新唤起**。高重要性保护。 | 自适应遗忘 |
> **工程诚实度。** 惊喜度结合了两个信号：**词汇新颖度**（`1 − 与存储内容的最高相似度`）和实际**预测误差**，通过自家增量语言模型以比特 / token 估计（压缩 / MDL，无神经网络，无 GPU）。基础编码器为**词汇**；对于同义词，有可选的语义钩（如下）。所有组件均可更换，无需修改其他部分。
---
## 安装（完整指南：[INSTALL.md](INSTALL.md)）
**快速路径 — 本地 Python + Claude 代码：**
```bash
git clone https://github.com/armandojaleo/hipercampo.git
cd hipercampo
pip install -e . # 安装 hipercampo + 依赖
python scripts/demo.py # （可选）观察循环运行
claude mcp add hipercampo -- python -m hipercampo.server # 连接到 Claude 代码
```
重启 Claude 代码后，您将获得 10 种记忆工具（`hc_remember`、`hc_recall`、`hc_muse`、`hc_dream`、`hc_update`、`hc_remember_fact`、`hc_ask_role`、`hc_consolidate`、`hc_forget`、`hc_stats`）。有关 Docker、Claude Desktop、`.mcp.json`、验证和故障排除，请参阅 **[INSTALL.md](INSTALL.md)**。
---
## 30 秒体验（无需 Claude）
```bash
pip install numpy
python scripts/demo.py
```
您将看到代数运算区分词序和完整循环（惊喜 → 回忆 → 睡眠 → 遗忘）的工作过程。
**实际用例** 见 [`examples/`](examples/)：具有跨会话记忆的个人助理、具有角色查询的项目知识库和创造性头脑风暴， forgotten 记忆可以重新浮现。
---
## 测试集 — 它能实现预期功能
```bash
python tests/test_vsa.py # VSA 代数（绑定 / 捆绑 / 顺序）
python tests/test_memory.py # 循环：惊喜、回忆、睡眠、遗忘、持久性
python tests/test_namespaces.py # 上下文隔离、并发性、事务
python tests/test_calibration.py # 自适应惊喜度、回滚、空查询、凝聚力
python tests/test_properties.py # 在构造数据上保持不变（8 轮）
python scripts/scenarios.py # 叙述性故事：Claude 记忆用户
```
共 16 套测试，均在 CI 中通过（Python 3.11–3.13）。示例不变式检查：*不会为重复内容创建第二个记忆*，*在 25 个干扰项中检索针状物*，*遗忘不会删除重要性 ≥ 0.8 的内容*，*一个上下文无法看到或修改另一个上下文的数据*，*失败的事务不会留下痕迹*。
## 基线比较（第 2 阶段）
`python scripts/baselines.py [--semantic]` 将 hipercampo 与相同语料库上的标准方法进行比较（10 个事实 + 10 个混淆干扰项）。每类别的 MRR + **错误召回率**（无关查询仍返回内容）：
| 方法 | 关键词 | 拼写错误 | 同义词 | 全局 | 错误召回 |
|--------|:---:|:---:|:---:|:---:|:---:|
| BM25（精确词汇） | 1.00 | 0.77 | 0.33 | 0.70 | 1.00 |
| 嵌入式 + 余弦 | 0.95 | 0.88 | 0.79 | 0.87 | 0.20 |
| hipercampo（词汇） | 1.00 | 0.91 | 0.51 | 0.81 | **0.20** |
| **hipercampo + 语义** | 1.00 | 0.95 | **0.90** | **0.95** | ~0.20 |
诚实解读：
- **在排名（MRR）上，hipercampo + 语义胜出**（0.95）：它融合了词汇精度（关键词 / 拼写错误）与语义范围（同义词）。在纯词汇模式下，它已经击败 BM25，尤其是在**拼写错误**方面，得益于字符三元组。
- **弃权现在起作用**：噪声相对（z-score）阈值将错误召回率降至 **0.20**，与嵌入式的余弦截止（曾为 1.00）相当。
- 语料库 **小且合成**：一个信号，而不是大规模证明。参见 [ROADMAP.md](ROADMAP.md)。
## 规模和延迟（已测量）
| 记忆数量 | 完整 `recall()`（CPU） | 找到针状物？ |
|----------|:---:|:---:|
| 2,000 | ~40 ms | 是，排名 #1 |
| 10,000 | ~164 ms | 是，排名 #1 |
**向量化** 扫描（整个矩阵的 XOR + 原生 NumPy 2.0 popcount）：比逐行扫描快 ~5 倍。呈线性增长（无 ANN 索引）：足以应对个人记忆（数百到数千）；在 ~100k 时，您需要索引。已知限制，非隐藏。
## 克劳德获得的工具
| 工具 | 用于 |
|------|-----|
| `hc_remember(text, importance, confidence)` | 存储某些内容（如果新颖 / 令人惊讶）。`importance` = 重要性（≥0.8 保护免受遗忘）；`confidence` = 可靠性（权重排名）。 |
| `hc_recall(query, k, include_history)` | 通过相似性和扩散激活检索。可以**放弃**（返回 `[]`）。 |
| `hc_muse(query, k)` | **创造性回忆**：唤起**间接**联系和**休眠**记忆，可以重新浮现并连接想法。用于洞察 / 头脑风暴。 |
| `hc_dream(max_bridges)` | **创造性睡眠**：提出*桥梁*，连接共享共同关联但未链接的记忆 — 假设在审查“第二天早上”。 |
| `hc_update(target, new_text, memory_id)` | **更新已更改的事实**（安全替换；旧内容保留为历史）。 |
| `hc_consolidate()` | 睡眠阶段：将事件分组为语义知识。 |
| `hc_forget(dry_run)` | 主动遗忘。`dry_run=True` 在删除前排练。 |
| `hc_remember_fact(subject, predicate, object, …)` | 存储**结构化事实**（组合 VSA）。 |
| `hc_ask_role(role, …known fields…)` | 在已知其他字段的情况下询问某个字段： *"谁咬了人？"* → 解绑定。 |
| `hc_stats()` | 记忆状态（包括数据库路径）。 |
防护措施（环境变量）：`HIPERCAMPO_MAX_MEMORIES` 限制每个上下文的记忆数量（淘汰保留率最低的；不会删除受保护的）；`HIPERCAMPO_REDACT_SECRETS=1` 在存储前屏蔽检测到的秘密，而不是仅警告。
## 记忆的四个轴（新颖度 ≠ 重要性 ≠ 可靠性 ≠ 效用）
| 轴 | 衡量内容 | 谁设置 | 用于 |
|------|------------------|-------------|----------|
| **新颖度 / 惊喜度** | 新颖还是可预测？（MDL） | 派生 | 决定是否**写入** |
| **重要性** | 重要程度 | 调用者（`importance`） | **保护**免受遗忘 |
| **可靠性** | 真实 / 可信程度 | 调用者（`confidence`） | **排名**在检索时 |
| **效用** | 实际使用程度 | 派生（`access_count`） | **保护**免受遗忘通过使用 |
遗忘结合了后三个因素，形成透明的*保留度*（`0.4·importance + 0.3·reliability + 0.3·utility`）：时间仅标记候选者，但**价值**决定。
## 具有角色的组合记忆（区别所在）
嵌入式**无法**实现的功能：询问 *谁对谁做了什么* 并通过角色获得正确答案。事实通过将每个值绑定到其角色并捆绑来编码 — 然后通过*解绑定*恢复任何字段（`hipercampo/roles.py`）：
```python
from hipercampo.roles import ItemMemory, encode_fact, query_role
im = ItemMemory()
fact = encode_fact({"subject": "dog", "predicate": "bites", "object": "man"}, im)
query_role(fact, "subject", im) # -> [("dog", 0.74)]
query_role(fact, "object", im) # -> [("man", 0.76)]
```
`python scripts/roles_demo.py` 展示了结论： *"狗咬人"* 和 *"人咬狗"* 具有**相同的值**，但恢复的主题 / 对象是**交换的** — 密集嵌入式将它们放在几乎相同的位置；VSA 保持它们不同。测量：每个角色恢复正确填充器的比例明显更高（0.74 vs 0.54），容量高达 5 个角色。将这些角色记录连接到实时 MCP 循环是下一步（参见 [ROADMAP.md](ROADMAP.md))。
## 上下文、Docker、安全
- **上下文**：命名空间（`HIPERCAMPO_NAMESPACE`）用于隔离项目 / 配置文件存储在单个数据库中，或存储在单独的文件中（`HIPERCAMPO_DB`）。**本地**隔离，非多用户安全 — hipercampo 是本地优先的。参见 [SECURITY.md](SECURITY.md)。
- **Docker**：`docker compose build && docker compose run --rm hipercampo`。
- **安全**：检索的文本是**数据，而非指令**。内置防护措施（`hipercampo/safety.py`）：`hc_remember` 在可能的情况下警告**秘密**（纯文本数据库），`hc_recall` 将类似**注入指令**的记忆标记为 `untrusted`。它们会警告，但不会阻止。详细信息见 [SECURITY.md](SECURITY.md)。
## 架构
```
文本 ──▶ encoder.py ──▶ 超向量（10,000 位）
│
vsa.py （绑定 / 捆绑 / 排列 / 向量化 popcount）
│
memory.py ── 惊喜 · 回忆 + 扩散 · 睡眠 · 遗忘 · 4 轴
│
store.py ── SQLite WAL（记忆 + 图，命名空间隔离，事务）
│
server.py ── MCP（stdio） ──▶ 克劳德
```
## 相关工作与诚实定位
hipercampo **并未发明**超维计算（HDC / VSA 可追溯到 20 世纪 90 年代：Kanerva, Plate），也不是尝试构建智能体记忆的第一个尝试（Mem0, Letta, Graphiti, MemGPT; MnemoCore 使用 HDC）。原创之处在于**特定组合**：VSA + 惊喜度（MDL）+ 巩固 + 遗忘 + 四个轴，作为 **MCP** 服务器公开，处理记忆作为一个**循环**。我们并不声称击败基于嵌入式的混合记忆；我们探索了一个不同的范式，并测量了其局限性。
## 许可证与归属
MIT（参见 [LICENSE](LICENSE)）。原始代码；依赖和想法在 [ATTRIBUTION.md](ATTRIBUTION.md) 中得到认可。房屋规则：**如果我们使用他人的作品，尤其是受版权保护的作品，我们会说明。**
## 致谢
由 **Armando Jaleo** 与 **Claude** （Anthropic）共同构建，通过衡量后再相信并说明限制。感谢 Pentti Kanerva 和 Tony Plate，他们数十年前的想法至今仍然存在。以及对严格审计的感谢：诚实的批评使该项目在每次迭代中变得更好。
*而且 — 祝贺西班牙！ 🇪🇸⚽ 某些记忆值得 `confidence=1.0`.*
> 记忆不仅仅是存储：它是一个循环，保存、关联、巩固和遗忘。如果有一天这能帮助机器**有判断地**记住 — 并让使用它们的人审计 — 那将是值得的。 — 精心制作。 🧠
