Memwyre

Persistent Shared Memory for Every AI.

Website · Documentation · Console / App · Twitter / X

Memwyre is an open-source, universal memory infrastructure and persistent knowledge retrieval layer for Large Language Models (LLMs), AI agents, and custom applications.

Rather than treating AI as stateless and losing context every time you switch between ChatGPT, Claude, Cursor, or different agent environments, Memwyre sits externally as a unified personal brain. It securely ingests, chunks, and structures your documents, web pages, conversations, and workflows—making them instantly retrievable across your entire AI toolchain.

Quickstart

npx -y install-memwyre

Table of Contents

1. Quickstart
2. Core Features
3. Ecosystem Tiers
4. System Architecture & Core Workflows
5. The LoCoMo Benchmark Evaluation
6. Database Schema & Multi-Tenancy
7. Installation & Setup
8. Environment Configuration
9. License

Core Features

• Decoupled Persistent Memory: Acts as an external, LLM-agnostic memory layer. Your knowledge base follows you whether you are using OpenAI, Google Gemini, Anthropic Claude, or local model configurations.
• Asynchronous Enrichment: Automatically refines memories, stripping filler text, generating summaries, extracting key entities, and producing atomic factual associations.
• Dynamic Context Pruning & Recency Decay: Utilizes an Ebbinghaus-inspired logarithmic decay to deprecate outdated or contradictory user preferences chronologically, keeping context sizes optimized.
• Approval-Based Inbox Flow: Introduces a memory dashboard inbox, allowing you to review, edit, approve, or reject auto-captured memories before committing them to long-term vector indexes.
• Project-Scoped Containerization: Restricts vector searches and factual associations to specific workspaces or project scopes, providing robust multi-tenant containerization.

Ecosystem Tiers

Memwyre provides multiple ways to ingest and retrieve information:

• 1. Web Application & Dashboard (Deployed on memwyre.tech): The main web app written in Vue 3 (Vite + Tailwind CSS), incorporating an onboarding tour, Monaco Editor for document management, billing integration, and a visual retrieval simulator to debug and verify vector rankings.
• 2. Chrome Extension (Manifest V3) (Available on Chrome Web Store): Auto-injects context into web chat clients, maps authentication tokens, and allows users to save articles, code snippets, or conversational logs directly to their vault with a single click.
• 3. Model Context Protocol (MCP) Server: A Python server mapping memory tools (search_memory, save_memory, get_document) directly into IDEs like Cursor and VS Code, or desktop assistants like Claude Desktop.
• 4. CLI Tool: A Node-based Command Line Interface (cli/) providing terminal-level interaction, query testing, and batch document uploads.
• 5. OpenClaw Plugin: A dedicated integration module (openclaw-plugin/) allowing multi-agent platforms to interface directly with the Memwyre memory vault.

System Architecture & Core Workflows

High-Level Components

Memwyre connects user clients to local or cloud vector search services and AI providers:

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

Ingestion Pipeline

Ingesting a memory triggers background worker tasks to process, embed, and structure raw data asynchronously:

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)

Parallelized Retrieval (RAG)

Retrieval queries run exact relational Fact lookups and fuzzy Semantic Search in parallel to feed LLM contexts with ultra-low latency:

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

The LoCoMo Benchmark Evaluation

The LoCoMo-10 (Long Conversational Memory) benchmark, introduced by Snap Research in "Evaluating Very Long-Term Conversational Memory of LLM Agents" (2024), evaluates AI agent systems on long-term memory, factual consistency, temporal alignment, and multi-hop reasoning over lengthy, multi-session dialog flows (up to 32 sessions and 26,000 tokens per conversation).

Performance Metrics (Memwyre vs. Flat Vector Systems)