Memwyre

Memwyre

为每个 AI 提供持久共享记忆。

网站 · 文档 · 控制台 / 应用 · Twitter / X

Memwyre 是一个开源的通用记忆基础设施，也是面向大模型（LLM）、AI Agent 和自定义应用的持久化知识检索层。

Memwyre 不会将 AI 视为无状态工具，也不会让你在 ChatGPT、Claude、Cursor 或不同的 Agent 环境之间切换时丢失上下文，而是作为统一的个人大脑，在外部运行。它会安全地摄取、分块并整理你的文档、网页、对话和工作流，让你可以在整个 AI 工具链中即时检索这些内容。

快速入门

npx -y install-memwyre

目录

1. 快速入门
2. 核心功能
3. 生态层级
4. 系统架构与核心工作流
5. LoCoMo 基准评估
6. 数据库架构与多租户
7. 安装与设置
8. 环境配置
9. 许可证

核心功能

• 解耦的持久记忆：作为外部且与大模型无关的记忆层。无论你使用 OpenAI、Google Gemini、Anthropic Claude，还是本地模型配置，知识库都会伴随你。
• 异步增强：自动优化记忆，去除填充文本、生成摘要、提取关键实体，并生成原子化事实关联。
• 动态上下文精简与时效衰减：采用受艾宾浩斯遗忘曲线启发的对数衰减机制，按时间顺序淘汰过时或相互矛盾的用户偏好，从而优化上下文大小。
• 基于审批的收件箱流程：引入记忆仪表板收件箱，让你在将自动捕获的记忆存入长期向量索引前进行查看、编辑、批准或拒绝。
• 项目范围容器化：将向量搜索和事实关联限制在特定工作区或项目范围内，从而实现可靠的多租户容器化。

生态系统层级

Memwyre 提供多种信息摄取与检索方式：

• 1. Web 应用与仪表板（部署于 memwyre.tech）：主要 Web 应用，使用 Vue 3（Vite + Tailwind CSS）编写，集成了引导式教程、用于文档管理的 Monaco Editor、计费集成，以及用于调试和验证向量排名的可视化检索模拟器。
• 2. Chrome 扩展（Manifest V3）（可从 Chrome 网上应用店获取）：自动向 Web 聊天客户端注入上下文、映射身份验证令牌，并允许用户一键将文章、代码片段或对话日志直接保存到个人存储库。
• 3. Model Context Protocol（MCP）服务：Python 服务，可将记忆工具（search_memory、save_memory、get_document）直接接入 Cursor 和 VS Code 等 IDE，或 Claude Desktop 等桌面助手。
• 4. CLI 工具：基于 Node 的命令行界面（cli/），提供终端级交互、查询测试和批量文档上传功能。
• 5. OpenClaw 插件：专用集成模块（openclaw-plugin/），让多 Agent 平台能够直接与 Memwyre 记忆库交互。

系统架构与核心工作流

高层组件

Memwyre 将用户客户端连接到本地或云端向量搜索服务和 AI 提供商：

flowchart TB
    subgraph Client_Side ["Client Side"]
        Browser["WebApp (Vue 3 / Vite)"]
        Extension["Chrome Extension (MV3)"]
        CLI["CLI Client (Node.js)"]
    end

    subgraph Load_Balancer ["Ingress"]
        Nginx["Nginx Reverse Proxy"]
    end

    subgraph Backend_Core ["Backend API (FastAPI)"]
        Auth_Mod["Auth & Users Module"]
        Mem_Mod["Memory Management"]
        Ret_Mod["Retrieval Engine"]
        LLM_Mod["LLM Service (V1/V2)"]
    end

    subgraph Background_Workers ["Celery Workers"]
        Ingest_Worker["Ingestion & Chunking Worker"]
        Dedupe_Worker["Deduplication Worker"]
    end

    subgraph Data_Persistence ["Data Layer"]
        Postgres[("PostgreSQL / SQLite")]
        Pinecone[("Pinecone / ChromaDB")]
        Redis[("Redis Message Broker")]
    end
    
    subgraph External_Services ["AI Inference"]
        NVIDIA["NVIDIA NIM (Kimi K2.6)"]
        Azure["Azure OpenAI (GPT-4o-mini)"]
        Gemini["Google Gemini API"]
    end

    Browser -->|HTTPS| Nginx
    Extension -->|HTTPS| Nginx
    CLI -->|HTTPS| Nginx
    Nginx --> Backend_Core
    
    Auth_Mod --> Postgres
    Mem_Mod --> Postgres
    Mem_Mod --> Ingest_Worker
    
    Ret_Mod --> Pinecone
    Ret_Mod --> Postgres
    Ret_Mod --> External_Services
    
    Ingest_Worker --> External_Services
    Ingest_Worker --> Pinecone
    Ingest_Worker --> Postgres

摄取流水线

摄取记忆会触发后台工作任务，以异步方式处理、嵌入并整理原始数据：

sequenceDiagram
    participant User
    participant API as FastAPI API
    participant Worker as Celery Worker
    participant LLM as LLM/Embedding Provider
    participant Vector as Pinecone/ChromaDB
    participant DB as PostgreSQL/SQLite

    User->>API: POST /memory (Raw Text Content)
    API->>DB: Save Memory (Status: Pending)
    API->>Worker: Dispatch Ingest Task
    API-->>User: 202 Accepted (In progress)
    
    Note over Worker: Asynchronous Processing
    Worker->>LLM: Metadata Extraction (Titles, Tags)
    Worker->>Worker: Semantic Chunking (Overlapping Splits)
    
    loop Parallel Enrichment
        Worker->>LLM: Enrich Chunk (Q&A Pairs, Summaries)
        Worker->>LLM: Extract SPO Facts (Subject-Predicate-Object)
    end
    
    Worker->>Vector: Batch Upsert Embeddings (Chunks + Facts)
    Worker->>DB: Write Chunks & Facts (Linked to Memory)
    Worker->>DB: Update Memory Status (Approved/Active)

并行检索（RAG）

检索查询会并行执行精确的关系型事实查询和模糊语义搜索，以超低延迟为大模型上下文提供内容：

sequenceDiagram
    participant User
    participant API as FastAPI API
    participant RetSvc as RetrievalService
    participant Vector as Vector Store
    participant DB as Relational DB
    participant LLM as GenAI Model

    User->>API: Chat Query / RAG Trigger
    API->>RetSvc: search_memories(Query, project_id)
    
    par State Fact Lookups
        RetSvc->>Vector: Vector Search (Factual matches)
        RetSvc->>DB: SQL Filter (Valid & Non-superseded Facts)
    and Semantic Search
        RetSvc->>Vector: Vector Search (Chunk embeddings)
        RetSvc->>RetSvc: MMR Re-ranking (Filter redundant chunks)
    end
    
    RetSvc->>RetSvc: Merge Results (State Facts + Chunk text)
    RetSvc-->>API: Ranked Top-K Context Items
    
    API->>LLM: Generate Answer (Prompt + Merged Context)
    LLM-->>User: Streaming Response

LoCoMo 基准评估

LoCoMo-10（长对话记忆）基准由 Snap Research 在 “Evaluating Very Long-Term Conversational Memory of LLM Agents”（2024） 一文中提出，用于评估 AI Agent 系统在长期记忆、事实一致性、时间对齐以及长篇多轮对话流程（每段对话最多包含 32 个会话和 26,000 个词元）上的多跳推理能力。

性能指标（Memwyre 与扁平向量系统对比）

提示

上下文压缩：Memwyre 将上下文长度减少了 88.5%（检索 3,000 个 Token，而非 26,000 个 Token 的原始对话），同时准确率显著优于扁平向量索引。

LoCoMo 性能的架构优势

1. 动态上下文剪枝：在分块丰富化过程中去除对话噪声（填充词、问候语和干扰信息）。
2. 两阶段重排序：先通过广泛、高召回率的向量检索阶段获取结果，再使用 Cross-Encoder 重排序器，仅选出上下文相关性最高的记忆项。
3. 艾宾浩斯对数近期性衰减：当较新的条目覆盖较早的用户偏好或冲突事实时，自动降低其时效性。
4. 对抗免疫能力：采用严格的语义包含机制；当查询不存在的信息时，检索器会妥善失败并拒绝产生幻觉。

数据库架构与多租户

Memwyre 使用混合存储模型：元数据、关系事实和用户凭据存储在 SQL 表（PostgreSQL/SQLite）中，而文档分块和丰富化事实字符串则镜像存储在向量数据库（Pinecone/ChromaDB）中。

👉 查看详细数据库架构，了解核心实体（users、projects、memories、documents、chunks、facts）和实体关系图的完整说明。

事实覆盖与项目容器化

• 覆盖：当写入与相同 subject 和 predicate 匹配的新事实时（例如，用户从柏林搬到东京），数据库会将旧记录的 is_superseded 标记设为 true，并将 valid_until 更新为当前时间戳。这可确保时间相关查询返回符合实际状态的事实。
• 容器化：每条记忆、文档、分块和事实都包含 project_id。查询时，过滤器会严格确保结果属于当前工作区的 project_id，防止不同项目环境之间发生数据泄漏。

安装与设置

前置条件

• Python 3.11 或 3.12（推荐使用 UV 包管理器）
• Node.js 18+ 与 npm
• Redis 服务（用于后台 Celery 任务）
• PostgreSQL 数据库（可选；默认使用 SQLite）

1. 后端 API 设置

进入后端目录，初始化环境、安装依赖并启动 FastAPI 服务：

cd backend

# Create virtual environment and install packages
uv venv
uv pip install -r requirements.txt

# Start the FastAPI server
uv run uvicorn app.main:app --reload

API Swagger UI 文档可通过 http://localhost:8000/docs 访问。

2. 后台摄取工作器

确保 Redis 正在运行，然后启动 Celery 后台工作器来处理摄取队列：

cd backend
uv run celery -A app.celery_app worker --loglevel=info -P solo

3. 前端仪表板设置

安装前端软件包并启动 Vite 开发服务器：

cd frontend
npm install
npm run dev

Web 仪表板运行于 http://localhost:5173。

4. Chrome 扩展安装

1. 打开 Chrome 并前往 chrome://extensions/
2. 启用开发者模式（右上角的切换开关）
3. 点击加载已解压的扩展程序（左上角）
4. 选择此项目根目录中的 extension/ 文件夹。
5. 在 Web 应用中，前往设置 -> 复制扩展令牌，并将其粘贴到扩展弹出窗口中以关联会话。

5. MCP 服务集成

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中（Windows 上位于 %APPDATA%\Claude\claude_desktop_config.json，macOS 上位于 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "brain-vault": {
      "command": "python",
      "args": ["/path/to/memwyre/backend/mcp_server.py"]
    }
  }
}

Cursor / VS Code

配置编辑器的 MCP 设置，以通过命令行运行该服务：

python /path/to/memwyre/backend/mcp_server.py

6. Node CLI 设置

安装依赖项并全局运行命令行工具：

cd cli
npm install
node index.js --help

环境配置

复制 backend/ 目录中的示例环境文件，并配置变量：

cp backend/.env.example backend/.env

关键环境参数：

# --- Base Secrets & Database ---
SECRET_KEY="your-strong-random-64-character-string"
DATABASE_URL="postgresql://postgres:password@localhost/brain-vault"

# --- Redis & Celery ---
CELERY_BROKER_URL="redis://localhost:6379/0"
REDIS_URL="redis://localhost:6379/0"

# --- Vector Database (Pinecone) ---
PINECONE_API_KEY="your-pinecone-api-key"
PINECONE_HOST="https://your-pinecone-index-host"
PINECONE_SPARSE_HOST="https://your-optional-sparse-index-host"

# --- LLM Providers & Embeddings ---
MEMORY_ENGINE_VERSION="v2"  # "v1" for NVIDIA, "v2" for Azure/OpenAI
AZURE_OPENAI_API_KEY="your-azure-key"
AZURE_OPENAI_ENDPOINT="https://your-resource-name.cognitiveservices.azure.com/"
AZURE_OPENAI_DEPLOYMENT="gpt-4o-mini"
AZURE_OPENAI_EMBEDDING_DEPLOYMENT="text-embedding-3-small"

# --- V1 Compatibility (NVIDIA NIM) ---
EMBEDDING_API_KEY="your-nvidia-embedding-key"
LLM_API_KEY="your-nvidia-llm-key"

许可证

本项目采用 Apache License 2.0（Apache-2.0）许可。详情请参阅 LICENSE 和 NOTICE 文件。