Memoripy

Memoripy 是一个 Python 库，旨在使用短期和长期存储来管理和检索上下文感知的记忆交互。它支持需要记忆管理的 AI 驱动应用，并兼容 OpenAI、Azure OpenAI、OpenRouter 和 Ollama API。其功能包括上下文记忆检索、记忆衰减与强化、层次聚类以及基于图的关联。

特性

• 短期与长期记忆：根据使用情况和相关性将记忆分为短期或长期。

• 上下文检索：基于嵌入、概念和过往交互检索记忆。

• 概念提取与嵌入：使用 OpenAI 或 Ollama 模型进行概念提取和嵌入生成。

• 基于图的关联：构建概念图，并利用扩散激活机制进行相关性检索。

• 层次聚类：将相似的记忆聚类为语义组，以帮助进行上下文相关的检索。

• 衰减与强化：较旧的记忆会随时间衰减，而频繁访问的记忆则会被强化。

安装

您可以通过 pip 安装 Memoripy：

pip install memoripy

使用方法

以下示例展示了如何在 Python 脚本中设置和使用 Memoripy。

示例：example.py

此示例脚本展示了 Memoripy 的主要功能，包括初始化、存储交互、检索相关记忆以及生成响应。

from memoripy import MemoryManager, JSONStorage
from memoripy.implemented_models import OpenAIChatModel, OllamaEmbeddingModel

def main():
    # 将 'your-api-key' 替换为您的实际 OpenAI API 密钥
    api_key = "your-key"
    if not api_key:
        raise ValueError("请设置您的 OpenAI API 密钥。")

    # 定义聊天和嵌入模型
    chat_model_name = "gpt-4o-mini"  # 具体聊天模型名称
    embedding_model_name = "mxbai-embed-large"  # 具体嵌入模型名称

    # 选择存储方式
    storage_option = JSONStorage("interaction_history.json")
    # 或者使用内存存储：
    # from memoripy import InMemoryStorage
    # storage_option = InMemoryStorage()

    # 使用选定的模型和存储初始化 MemoryManager
    memory_manager = MemoryManager(
        OpenAIChatModel(api_key, chat_model_name),
        OllamaEmbeddingModel(embedding_model_name),
        storage=storage_option
    )

    # 新的用户提示
    new_prompt = "我的名字是哈扎尔"

    # 加载历史中的最后 5 条交互（用于上下文）
    short_term, _ = memory_manager.load_history()
    last_interactions = short_term[-5:] if len(short_term) >= 5 else short_term

    # 检索相关的过往交互，排除最后 5 条
    relevant_interactions = memory_manager.retrieve_relevant_interactions(new_prompt, exclude_last_n=5)

    # 使用最后的交互和检索到的交互生成响应
    response = memory_manager.generate_response(new_prompt, last_interactions, relevant_interactions)

    # 显示响应
    print(f"生成的响应：\n{response}")

    # 提取新交互的概念
    combined_text = f"{new_prompt} {response}"
    concepts = memory_manager.extract_concepts(combined_text)

    # 存储此次新交互及其嵌入和概念
    new_embedding = memory_manager.get_embedding(combined_text)
    memory_manager.add_interaction(new_prompt, response, new_embedding, concepts)

if __name__ == "__main__":
    main()

类与模块

• MemoryManager：管理记忆交互，检索相关信息，并根据过往交互生成响应。

• MemoryStore：存储并组织短期和长期记忆中的交互，支持基于相关性的聚类和检索。

• InMemoryStorage 和 JSONStorage：分别将记忆存储在内存数据结构或 JSON 文件中。

• BaseStorage：定义存储方法的抽象基类。

核心功能

1. 初始化记忆：从所选存储加载之前的交互并初始化记忆。

2. 添加交互：存储新的交互及其嵌入、概念、提示和输出。

3. 检索相关交互：使用余弦相似度、衰减因子和扩散激活机制，根据查询搜索过往交互。

4. 生成响应：结合当前提示和检索到的交互，生成上下文相关的响应。

5. 衰减与强化：对未使用的记忆增加衰减，对频繁访问的记忆进行强化。

依赖项

Memoripy 依赖于多个库，包括：

• openai

• faiss-cpu

• numpy

• networkx

• scikit-learn

• langchain

• ollama

这些依赖项将在您运行 pip install memoripy 时自动安装。

许可证

Memoripy 采用 Apache 2.0 许可证授权。

贡献

欢迎贡献！您可以随时提出问题或提交拉取请求以改进项目。

贡献者

Memoripy 快速上手指南

Memoripy 是一个专为 AI 应用设计的 Python 库，用于管理具备上下文感知能力的短期与长期记忆。它支持记忆衰减、强化、层级聚类及基于图的关联检索，兼容 OpenAI、Azure、OpenRouter 和 Ollama 等主流模型接口。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：建议 Python 3.8 及以上
• API Key：
  • 若使用 OpenAI 模型，需准备有效的 OPENAI_API_KEY。
  • 若使用 Ollama 进行本地嵌入或对话，需确保本地已安装并运行 Ollama 服务，且拉取了相应模型（如 mxbai-embed-large）。

国内加速建议：

1. PyPI 源：建议使用清华或阿里云镜像源加速依赖安装。
2. Ollama 模型：国内用户可通过配置环境变量或使用国内镜像站加速模型下载。
3. OpenAI 接口：如需访问 OpenAI API，请确保网络环境通畅或使用合法的代理/中转服务。

安装步骤

使用 pip 安装 Memoripy 及其所有依赖项。

使用官方源安装：

pip install memoripy

推荐使用国内镜像源加速安装（以清华源为例）：

pip install memoripy -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，系统将自动包含 openai, faiss-cpu, numpy, networkx, scikit-learn, langchain, ollama 等核心依赖。

基本使用

以下示例展示了如何初始化记忆管理器、加载历史上下文、检索相关记忆并生成响应。

示例代码 (example.py)

请根据您的实际环境替换 API Key 和模型名称。

from memoripy import MemoryManager, JSONStorage
from memoripy.implemented_models import OpenAIChatModel, OllamaEmbeddingModel

def main():
    # 替换为您的实际 OpenAI API Key
    api_key = "your-key"
    if not api_key:
        raise ValueError("Please set your OpenAI API key.")

    # 定义聊天模型和嵌入模型
    chat_model_name = "gpt-4o-mini"       # 具体的聊天模型名称
    embedding_model_name = "mxbai-embed-large"  # 具体的嵌入模型名称 (需确保本地 Ollama 已拉取此模型)

    # 选择存储方式：这里使用 JSON 文件持久化存储
    storage_option = JSONStorage("interaction_history.json")
    # 或者使用内存存储 (重启后数据丢失):
    # from memoripy import InMemoryStorage
    # storage_option = InMemoryStorage()

    # 初始化 MemoryManager，传入模型实例和存储选项
    memory_manager = MemoryManager(
        OpenAIChatModel(api_key, chat_model_name),
        OllamaEmbeddingModel(embedding_model_name),
        storage=storage_option
    )

    # 新的用户提示
    new_prompt = "My name is Khazar"

    # 加载最近的 5 条交互作为短期上下文
    short_term, _ = memory_manager.load_history()
    last_interactions = short_term[-5:] if len(short_term) >= 5 else short_term

    # 检索与当前提示相关的过往交互 (排除最近 5 条以避免重复)
    relevant_interactions = memory_manager.retrieve_relevant_interactions(new_prompt, exclude_last_n=5)

    # 结合近期上下文和检索到的相关记忆生成回复
    response = memory_manager.generate_response(new_prompt, last_interactions, relevant_interactions)

    # 输出生成的回复
    print(f"Generated response:\n{response}")

    # 提取新概念并计算嵌入向量
    combined_text = f"{new_prompt} {response}"
    concepts = memory_manager.extract_concepts(combined_text)
    new_embedding = memory_manager.get_embedding(combined_text)

    # 将本次交互存入记忆库
    memory_manager.add_interaction(new_prompt, response, new_embedding, concepts)

if __name__ == "__main__":
    main()

核心流程说明

1. 初始化：创建 MemoryManager 实例，配置聊天模型（如 GPT-4）、嵌入模型（如 Ollama）及存储后端。
2. 上下文加载：通过 load_history() 获取最近的短期记忆。
3. 智能检索：利用 retrieve_relevant_interactions() 基于语义相似度、记忆衰减机制和图扩散激活算法查找长期记忆。
4. 生成与存储：调用 generate_response() 生成回答，随后使用 add_interaction() 将新对话及其概念向量存入数据库，自动触发记忆强化或衰减逻辑。