大模型外存记忆系统（LLM External storage Memory System）

A flexible, scalable memory system designed for large language models (LLMs) to store, retrieve, and manage long-term memory. This system integrates vector search for semantic retrieval and graph storage for relationship management, enabling LLMs to build contextual, connected memory networks.

Derectory Structure

llm-memory-system/
├── memory_chunk.py    # 记忆块数据结构定义
├── vector_db.py       # 向量数据库（语义检索核心）
├── graph_db.py        # 图数据库（记忆关系管理）
├── memory_db.py       # 记忆管理器（协调VectorDB与GraphDB）
├── read_tool.py       # 读取工具（大模型查询记忆接口）
├── write_tool.py      # 写入工具（大模型更新记忆接口）
└── README.md          # 项目说明文档

核心功能

1. 语义化记忆检索：基于向量相似性快速定位相关记忆，支持标签、时间范围过滤
2. 记忆关系管理：构建记忆间的关联网络（如"依赖""扩展""相关"），支持多深度关系查询
3. 完整记忆生命周期：从添加、更新、查询到删除的全流程管理
4. 持久化存储：支持记忆系统整体保存与加载，避免数据丢失
5. 大模型友好接口：提供标准化的 ReadTool/WriteTool，可直接集成到LLM工具调用流程

组件说明

1. memory_chunk.py

核心作用：定义单个记忆单元的数据结构，封装记忆的完整信息。

关键字段

• chunk_id：唯一标识（UUID4自动生成）
• content：记忆核心内容（文本形式，如技术文档、代码片段、决策记录）
• chunk_type：记忆类型（如"技术知识""代码片段""用户偏好"）
• embedding：文本的向量表示（numpy数组，与嵌入模型维度一致）
• metadata：元数据（标签、重要性、来源、时间戳等）
• timestamp/last_accessed：创建时间与最后访问时间（用于热度排序）

核心方法

• to_dict()：转换为字典（支持序列化存储）
• from_dict()：从字典重建实例（支持反序列化加载）
• update_access_time()：更新最后访问时间（用于记忆清理策略）

2. vector_db.py

核心作用：基于向量的记忆存储与语义检索，支持高效相似性查询。

依赖

• memory_chunk.py（依赖 MemoryChunk类管理记忆块）
• numpy（向量计算）
• scikit-learn（余弦相似度计算）

核心功能

• 向量存储：校验向量维度一致性，单独管理向量以加速查询
• 标签索引：构建标签-记忆块映射，支持快速标签过滤
• 语义检索：结合余弦相似度与多条件过滤（标签、时间范围）
• 持久化：支持 save_to_disk()/load_from_disk()（基于pickle）

关键方法

• add_chunk()：添加记忆块（自动更新标签索引）
• search_similar()：基于查询向量返回Top-K相似记忆
• get_statistics()：获取数据库状态（记忆块数量、标签分布等）

3. graph_db.py

核心作用：管理记忆块之间的关系网络，支持多深度关联查询。

依赖

• networkx（有向图数据结构）
• 无直接依赖 MemoryChunk（仅通过 chunk_id关联，降低耦合）

核心功能

• 节点管理：存储记忆块对应的节点（与 VectorDB的 chunk_id一一对应）
• 关系管理：支持有向关系（如A→B表示"A依赖B"），支持多类型关系
• 深度查询：获取节点的直接/间接关联记忆，支持关系类型过滤
• 持久化：支持 save_to_disk()/load_from_disk()

关键方法

• add_relationship()：添加记忆块间的关系
• get_related_nodes()：查询多深度关联节点
• get_relationships()：获取节点的直接关系（支持方向过滤）

4. memory_db.py

核心作用：记忆系统的上层协调器，封装 VectorDB与 GraphDB的底层操作，提供统一接口。

依赖

• memory_chunk.py、vector_db.py、graph_db.py

核心功能

• 统一记忆管理：添加记忆时同步更新向量库与图库，保证数据一致性
• 整合检索：结合语义相似性与关系网络，返回完整记忆信息
• 生命周期管理：支持记忆的添加、查询、更新、删除全流程
• 系统监控：提供全局统计信息（向量库/图库状态、总记忆量）

关键方法

• add_memory()：添加完整记忆（同步创建向量节点与关系）
• search_memory()：整合语义检索与关系信息
• get_related_memories()：查询指定记忆的关联记忆
• save_to_disk()/load_from_disk()：整体持久化/加载

5. read_tool.py

核心作用：大模型调用的记忆读取接口，封装复杂查询逻辑为简单API。

依赖

• memory_db.py（依赖 MemoryManager访问底层存储）
• 嵌入模型（需实现 embed()方法，如Sentence-BERT）

核心功能

• 语义搜索：大模型通过自然语言查询相似记忆
• 关系查询：获取指定记忆的关联记忆
• 详情查询：获取单个记忆块的完整信息（含关系）
• 状态监控：获取记忆系统的统计信息

大模型调用示例

from read_tool import ReadTool
from memory_db import MemoryManager
from dummy_embedding import DummyEmbeddingModel

# 初始化
manager = MemoryManager(embedding_dim=768)
embed_model = DummyEmbeddingModel()
read_tool = ReadTool(manager, embed_model)

# 调用工具：搜索"Python多线程"相关记忆
result = read_tool.call(
    action="search_similar",
    query="Python多线程安全",
    top_k=3,
    tags=["Python", "并发"]
)

6. write_tool.py

核心作用：大模型调用的记忆写入接口，支持记忆的添加、更新与删除。

依赖

• memory_db.py（依赖 MemoryManager操作底层存储）
• 嵌入模型（需实现 embed()方法）

核心功能

• 添加记忆：支持设置标签、重要性、来源及初始关系
• 更新记忆：支持部分字段更新（内容、元数据、重要性等）
• 关系管理：添加/删除记忆块间的关系
• 持久化触发：手动触发记忆系统保存到磁盘

大模型调用示例

from write_tool import WriteTool
from memory_db import MemoryManager
from dummy_embedding import DummyEmbeddingModel

# 初始化
manager = MemoryManager(embedding_dim=768)
embed_model = DummyEmbeddingModel()
write_tool = WriteTool(manager, embed_model)

# 调用工具：添加新记忆
result = write_tool.call(
    action="add_memory",
    content="Python中用threading.Lock()避免数据竞争",
    memory_type="编程知识",
    tags=["Python", "多线程"],
    importance=0.85,
    source="Python官方文档"
)

Quick Start

1. Install Dependencies

pip install numpy scikit-learn networkx

2. Initialize

from memory_db import MemoryManager
from read_tool import ReadTool
from write_tool import WriteTool
from dummy_embedding import DummyEmbeddingModel  # replace with actual emdedding model

embedding_dim = 768  
manager = MemoryManager(embedding_dim=embedding_dim)
embed_model = DummyEmbeddingModel(embedding_dim=embedding_dim)

read_tool = ReadTool(manager, embed_model)
write_tool = WriteTool(manager, embed_model)

3. Process Example

Step1：Add Memory

# 添加记忆1
add_res1 = write_tool.add_memory(
    content="CUDA内存优化需按32字节对齐，提升带宽利用率",
    memory_type="技术知识",
    tags=["CUDA", "性能优化"],
    importance=0.9,
    source="NVIDIA开发者文档"
)
chunk1_id = add_res1["result"]["chunk_id"]

# 添加记忆2（关联记忆1）
add_res2 = write_tool.add_memory(
    content="CUDA线程块划分建议每个块处理128行非零元素，平衡负载",
    memory_type="技术知识",
    tags=["CUDA", "线程优化"],
    importance=0.85,
    relationships=[{"target_id": chunk1_id, "type": "related_to"}]
)
chunk2_id = add_res2["result"]["chunk_id"]

Step 2：Query Memory

# 语义搜索：查询"CUDA优化"相关记忆
search_res = read_tool.search_similar(
    query="CUDA性能优化方法",
    top_k=2,
    include_relationships=True
)
print("搜索结果：", search_res["results"])

# 关系查询：获取记忆1的关联记忆
related_res = read_tool.get_related(chunk_id=chunk1_id, max_depth=2)
print("关联记忆：", related_res["results"])

Step 3：Resistent Storage

# 保存记忆系统到磁盘
save_res = write_tool.save_memory(
    vector_path="vector_db.pkl",
    graph_path="graph_db.pkl"
)
print("保存结果：", save_res["message"])

# 从磁盘加载记忆系统
loaded_manager = MemoryManager.load_from_disk(
    vector_path="vector_db.pkl",
    graph_path="graph_db.pkl"
)

Embedding model Integration

系统通过 EmbeddingModelInterface接口适配任意嵌入模型，只需实现 embed(text: str) -> np.ndarray方法：

# 示例：集成Sentence-BERT
from sentence_transformers import SentenceTransformer
from memory_chunk import EmbeddingModelInterface

class SBERTEmbeddingModel(EmbeddingModelInterface):
    def __init__(self, model_name="all-MiniLM-L6-v2"):
        self.model = SentenceTransformer(model_name)
  
    def embed(self, text: str) -> np.ndarray:
        return self.model.encode(text, convert_to_numpy=True)

# 使用
embed_model = SBERTEmbeddingModel()

适用场景

1. 长对话系统：存储对话历史，支持上下文关联
2. 领域知识图谱：构建领域内的知识关联网络
3. 个性化推荐：基于用户记忆（偏好、历史）提供个性化服务
4. 决策支持系统：存储历史决策与依据，辅助后续决策

注意事项

1. 向量维度一致性：嵌入模型输出维度需与 MemoryManager初始化时的 embedding_dim一致
2. 持久化安全性：pickle格式不适合不可信数据，生产环境建议使用加密存储或更安全的序列化方式
3. 性能优化：大规模记忆场景建议使用分布式向量库（如FAISS、Milvus）替换内置 VectorDB
4. 记忆清理：需自行实现记忆清理策略（如基于访问时间、重要性的LRU/LFU策略）