内容
索引
一种为大型语言模型（LLMs）实现的仿人三轴记忆架构的认知记忆系统。
[](https://github.com/iyulab/memory-indexer/actions/workflows/ci.yml)
[](tests/)
[](https://www.nuget.org/packages/MemoryIndexer)
[](https://dotnet.microsoft.com/)
[](LICENSE)
## 问题
LLMs 面临一个基本限制：**有限的上下文窗口**。
```
┌─────────────────────────────────────────────────────┐
│ 会话 1 │ 会话 2 │ 会话 3 │ 当前 │
│ (丢失) │ (丢失) │ (丢失) │ (活动) │
└─────────────────────────────────────────────────────┘
```
**当前的解决方法存在不足：**
| 方法 | 限制 |
|----------|------------|
| 总结 | 信息丢失，额外的 LLM 调用 |
| 滑动窗口 | 重要的早期上下文丢失 |
| 完整历史 | 快速达到 token 限制 |
| RAG | 未针对对话上下文进行优化 |
## 解决方案
记忆索引提供 **零上下文工程** —— 您专注于提示，我们处理所有内存管理。
**之前** （手动上下文管理）：
```python
class ChatService:
def chat(self, message):
# 您管理：历史记录、总结、token 计数、
# 上下文组装、配置文件加载、事实提取...
if self.count_tokens(self.history) > MAX_TOKENS:
self.history = self.summarize(self.history) # 😓
```
**之后** （使用记忆索引）：
```python
class ChatService:
def chat(self, message):
await memory.store(session, message) # 自动分类，自动放置
context = await memory.recall(message) # 智能检索
return await llm.generate(context, message) # 完成。
```
> *"记忆的目标不是随着时间的推移传递最准确的信息，而是通过只保留有价值的信息来指导和优化智能决策。*
> — Richards & Frankland (2017)
## 角色与范围
| 是什么 | 不是什么 |
|------------|---------------|
| 通用记忆原语 | 聊天机器人框架 |
| 基于认知科学的架构 | 向量数据库 |
| 任意 LLM 客户端的 MCP 服务器 | 与特定用例绑定 |
| 领域无关的构建块 | 有偏见的应用程序 |
## 核心架构
**三轴记忆模型** ，其中每个记忆都有三个正交维度：
```
类型 × 范围 × 层级 = 什么 × 何时 × 何地
```
| 轴 | 值 | 认知基础 |
|------|--------|-----------------|
| **类型** | 事件、语义、过程、事实、反思 | Tulving 的记忆分类 |
| **范围** | 回合、主题、会话、用户 | 时间范围（秒 → 永久） |
| **层级** | 缓冲区、短期、长期、存档 | Atkinson-Shiffrin + Baddeley |
```
层级提升管道（Atkinson-Shiffrin + Tulving）：
┌─────────────────────────────────────────────────────┐
│ 缓冲区（T0）- 感官存储 │
│ 过期时间：60 秒空闲 │ 500 个 token │ 3 回合 │
├─────────────────────────────────────────────────────┤
│ 短期（T1）- 工作记忆（Baddeley 的 7±2） │
│ 容量：9 项，自动提升当超过 │
├─────────────────────────────────────────────────────┤
│ 长期（T2）- 事件记忆 │
│ 会话级事件和体验 │
├─────────────────────────────────────────────────────┤
│ 存档（T3）- 语义记忆 │
│ 提升：置信度 ≥ 0.8 且确认 ≥ 3 │
└─────────────────────────────────────────────────────┘
```
准测试摘要
| 延迟 | 吞 |
|-----------|---------|------------ 存储 | ~2.3 μs | 435K 次/秒 |
| 召回（限制 5） | ~5 μs | 次/秒 |
| 召回工作流 |.8 μs | 263K 次/秒 |
内存存储与模拟嵌入。有关完整结果，请参见 [基准测试详情](docs/BENCHMARKS.md)。
## 快速入门
### 作为 MCP 服务器
```bash
dotnet tool install -g MemoryIndexer.Mcp
```
配置 Claude Desktop (`%APPDATA%\Claude\claude_desktop_config.json`)：
```json
{
"mcpServers": {
"memory-indexer": {
"command": "memory-indexer-mcp"
}
}
}
```
### 作为 SDK
```bash
dotnet add package MemoryIndexer.Sdk
```
```csharp
// 在 AddMemoryIndexer() 之前注册您的嵌入服务
services.AddSingleton<IEmbeddingService>(myEmbeddingService);
// 内存存储（默认）
services.AddMemoryIndexer(options =>
{
options.Embedding.Dimensions = 1536; // 匹配您的嵌入模型
});
// 或使用 SQLite 持久存储
services.AddMemoryIndexer(options =>
{
options.Storage.ConnectionString = "memories.db";
options.Embedding.Dimensions1536;
}).WithVec();
// 存储
await memoryAsync("user123用户偏好暗黑模式", importance: 0.8f);
// 召回
var results = await memoryService.RecallAsync("user123", "UI 偏好", limit: 5);
```
## 示例
### [MemoryChatApp](samples/MemoryChatApp/)
基于 Web 的聊天，演示 **上下文预算 API 智能召回取代完整的对话历史。
```
传统：messages = [msg1, msg2, ... msgN] → Token 成本：O(n)
本演示：context = recall(query, budget=2000) → Token 成本：O(1)
```
**功能：**
- 基于 token 预算的上下文构建（RecentHeavy、Balanced、SemanticHeavy 策略）
- 4 级内存可视化（缓冲区 → 短期 → 长期 → 存档）
- 会话隔离与跨会话用户事实
- 灵活的嵌入（注入您自己的 IEmbeddingService）与 LLM 支持（GpuAI）
```bash
cd samples/MemoryChatApp
.\start-dev.ps1 # 打开前端 + 后端
```
### [二十个问题游戏](samples/TwentyQuestionsGame/)
AI 对战 AI 演示，两个 LLM 代理使用 **仅内存召回** 玩二十个问题 —— 无需注入聊天历史。
```
传统：messages: [Q1, A1, Q2, A2, ... Q19, A19] ← O(n) 上下文增长
本演示：user: "Alpha says: Yes" ← O(1) 常数上下文
```
**证明：**
- 代理通过 `memory_re 仅构建连贯的多回合策略
- 无论如何，上下文维护均为 O(1)
- 代理之间的内存隔离正确
```bash
cd samples/Twenty
dotnet run # LLM 提供程序
dotnet --local # 使用本地 ONNX 模型（无需 API 密钥）
```
## 自定义存储后端
记忆索引提供 `IMemoryStore` 接口用于自定义存储实现。使用此接口与 PostgreSQLdrant、Redis、Pinecone 或任何系统集成。
```csharp MemoryIndexer.Utilities;
publicPostgresStore : IMemoryStore
{
public async Task<MemoryUnit> StoreAsync(MemoryUnit memory, CancellationToken ct)
{
memory.PrepareForStore(); // 扩展：设置 Id、CreatedAt、UpdatedAt
memory.ValidateForStore(); // 扩展：验证必填字段
// 您的存储逻辑在此
await _db.Memories.AddAsync(Map(memory), ct await _dbAsync(ct);
return memory;
}
// ... IMemoryStore 方法
}
// 注册您的自定义存储
services.AddSingleton<IMemoryStore, MyPostgresStore>();
services.AddMemoryIndexer(options => options.Embedding.Dimensions = 1536有关包括混合 PostgreSQL+Qdrant 设置在内的完整模式，请参见 [自定义Store 实现指南](docs/GUIDES.md#custom-imemorystore-implementation)。
| 文档 | 描述----------|-------------|
| [架构](docs/ARCHITECTURE.md) | 系统设计、三轴模型、层级/类型详细信息 |
| [智能](docs/INTELLIGENCE.md) | 冲突解决、自适应检索、图遍历 |
| [评估](docs/EVALUATION.md) | KPI、NIAH 测试、多针场景 |
| [健康状况](docs/HEALTH.md) | 健康检查、Kubernetes 探针 |
| [基准测试](docs/BENCHMARKS.md) | 性能测量 |
| [指南](docs/GUIDES.md) | 配置、自定义存储、使用模式 |
| [路线图](docs/ROADMAP.md) | 功能时间表和状态 |
## 研究基础
建立在最新的记忆研究基础上：
- **MemGPT**：OS 启发的虚拟内存分页
- **Mem0/Mem0g**：基于图的记忆网络
- **H-MEM**：具有索引路由的层次记忆
- **认知心理学**：Atkinson-Shiffrin、Baddeley、Tulving 模型
## 许可证
MIT 许可证 - 有关详细信息，请参见 [LICENSE](LICENSE)。
---
**由 [iyulab](https://github.com/iyulab) 构建**
