[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_120":121},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":41,"_42":43,"_44":45,"_46":47,"_48":47,"_49":50,"_51":52,"_53":54,"_55":-5,"_56":47,"_57":58,"_59":60,"_61":-5,"_62":-5,"_63":11,"_64":47,"_65":66,"_67":68,"_69":70,"_71":72,"_73":74,"_75":-5,"_76":-5,"_77":-5,"_78":47,"_79":-5,"_80":81,"_82":83,"_84":85,"_86":87,"_88":89,"_90":91,"_92":93},"apiUrl","https://odel.app/api","creator","memwyreai","moduleId","memwyre","@memwyreai/memwyre","displayName","Memwyre","tagline","Universal persistent memory and knowledge retrieval layer for AI agents and LLMs.","iconKey","https://avatars.githubusercontent.com/u/304789346?v=4","category","remote","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://server.memwyre.tech/mcp/\",\"transport\":\"streamable-http\",\"authType\":\"bearer\"}","pricingModel","free","creatorUserId","system:external-import","createdAt",1788496931000,"updatedAt","sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.memwyreai%2Fmemwyre","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",1,"upstreamUpdatedAt",1788416506000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/memwyreai/Memwyre","githubRepoFullName","memwyreai/Memwyre","releaseId","ext-memwyreai-memwyre","version","1.0.0","descriptionMarkdown","# Memwyre\n\n### Persistent Shared Memory for Every AI.\n\n

\n \n \n \n $\"Memwyre$ \n \n

\n\n

\n Website ·\n Documentation ·\n Console / App ·\n Twitter / X\n

\n\n[![FastAPI](https://img.shields.io/badge/Backend-FastAPI-blue.svg?style=flat-square&logo=fastapi)](https://fastapi.tiangolo.com/)\n[![Vue 3](https://img.shields.io/badge/Frontend-Vue%203-green.svg?style=flat-square&logo=vue.js)](https://vuejs.org/)\n[![Chrome Extension](https://img.shields.io/badge/Extension-Chrome%20Web%20Store-orange.svg?style=flat-square&logo=google-chrome)](https://chromewebstore.google.com/detail/memwyre/biplnkodgfdgejgblohhjeckiclfpekn)\n[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-lightgrey.svg?style=flat-square)](https://modelcontextprotocol.io/)\n[![LoCoMo Accuracy](https://img.shields.io/badge/LoCoMo%20Accuracy-73.5%25-brightgreen.svg?style=flat-square)](https://github.com/ramblinghermit0403/Memwyre#-the-locomo-benchmark-evaluation)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](https://opensource.org/licenses/Apache-2.0)\n\nMemwyre is an open-source, universal memory infrastructure and persistent knowledge retrieval layer for Large Language Models (LLMs), AI agents, and custom applications.\n\nRather 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.\n\n---\n\n## Quickstart\n\n\n\n\n\n\n

\n\n### 🧑‍💻 I want to connect my AI tools\n\nBuild your own external memory layer using our consumer-facing dashboard or browser extension, and plug it directly into **Cursor, VS Code, or Claude Desktop** via MCP:\n\n```bash\nnpx -y install-memwyre\n```\n\n**[→ Jump to User Setup](#installation--setup)**\n\n

\n\n### 🔧 I'm building AI agents & products\n\nInterface with the unified memory vault, custom vector searches, and profile-based retrieval APIs:\n\n- Integration guides for custom AI agents and apps\n- Plug-and-play **OpenClaw** & **Claude** plugins\n- Direct vector storage without configuration\n\n**[→ Jump to Developer Setup](#installation--setup)**\n\n

\n\n---\n\n## Table of Contents\n1. [Quickstart](#quickstart)\n2. [Core Features](#core-features)\n3. [Ecosystem Tiers](#ecosystem-tiers)\n4. [System Architecture & Core Workflows](#system-architecture--core-workflows)\n5. [The LoCoMo Benchmark Evaluation](#the-locomo-benchmark-evaluation)\n6. [Database Schema & Multi-Tenancy](#database-schema--multi-tenancy)\n7. [Installation & Setup](#installation--setup)\n8. [Environment Configuration](#environment-configuration)\n9. [License](#license)\n\n---\n\n## Core Features\n\n- **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.\n- **Asynchronous Enrichment**: Automatically refines memories, stripping filler text, generating summaries, extracting key entities, and producing atomic factual associations.\n- **Dynamic Context Pruning & Recency Decay**: Utilizes an Ebbinghaus-inspired logarithmic decay to deprecate outdated or contradictory user preferences chronologically, keeping context sizes optimized.\n- **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.\n- **Project-Scoped Containerization**: Restricts vector searches and factual associations to specific workspaces or project scopes, providing robust multi-tenant containerization.\n\n---\n\n## Ecosystem Tiers\n\nMemwyre provides multiple ways to ingest and retrieve information:\n\n* **1. Web Application & Dashboard** ([Deployed on memwyre.tech](https://memwyre.tech/login)): 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.\n* **2. Chrome Extension (Manifest V3)** ([Available on Chrome Web Store](https://chromewebstore.google.com/detail/memwyre/biplnkodgfdgejgblohhjeckiclfpekn)): 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.\n* **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.\n* **4. CLI Tool**: A Node-based Command Line Interface (`cli/`) providing terminal-level interaction, query testing, and batch document uploads.\n* **5. OpenClaw Plugin**: A dedicated integration module (`openclaw-plugin/`) allowing multi-agent platforms to interface directly with the Memwyre memory vault.\n\n---\n\n## System Architecture & Core Workflows\n\n### High-Level Components\nMemwyre connects user clients to local or cloud vector search services and AI providers:\n\n```mermaid\nflowchart TB\n subgraph Client_Side [\"Client Side\"]\n Browser[\"WebApp (Vue 3 / Vite)\"]\n Extension[\"Chrome Extension (MV3)\"]\n CLI[\"CLI Client (Node.js)\"]\n end\n\n subgraph Load_Balancer [\"Ingress\"]\n Nginx[\"Nginx Reverse Proxy\"]\n end\n\n subgraph Backend_Core [\"Backend API (FastAPI)\"]\n Auth_Mod[\"Auth & Users Module\"]\n Mem_Mod[\"Memory Management\"]\n Ret_Mod[\"Retrieval Engine\"]\n LLM_Mod[\"LLM Service (V1/V2)\"]\n end\n\n subgraph Background_Workers [\"Celery Workers\"]\n Ingest_Worker[\"Ingestion & Chunking Worker\"]\n Dedupe_Worker[\"Deduplication Worker\"]\n end\n\n subgraph Data_Persistence [\"Data Layer\"]\n Postgres[(\"PostgreSQL / SQLite\")]\n Pinecone[(\"Pinecone / ChromaDB\")]\n Redis[(\"Redis Message Broker\")]\n end\n \n subgraph External_Services [\"AI Inference\"]\n NVIDIA[\"NVIDIA NIM (Kimi K2.6)\"]\n Azure[\"Azure OpenAI (GPT-4o-mini)\"]\n Gemini[\"Google Gemini API\"]\n end\n\n Browser -->|HTTPS| Nginx\n Extension -->|HTTPS| Nginx\n CLI -->|HTTPS| Nginx\n Nginx --> Backend_Core\n \n Auth_Mod --> Postgres\n Mem_Mod --> Postgres\n Mem_Mod --> Ingest_Worker\n \n Ret_Mod --> Pinecone\n Ret_Mod --> Postgres\n Ret_Mod --> External_Services\n \n Ingest_Worker --> External_Services\n Ingest_Worker --> Pinecone\n Ingest_Worker --> Postgres\n```\n\n### Ingestion Pipeline\nIngesting a memory triggers background worker tasks to process, embed, and structure raw data asynchronously:\n\n```mermaid\nsequenceDiagram\n participant User\n participant API as FastAPI API\n participant Worker as Celery Worker\n participant LLM as LLM/Embedding Provider\n participant Vector as Pinecone/ChromaDB\n participant DB as PostgreSQL/SQLite\n\n User->>API: POST /memory (Raw Text Content)\n API->>DB: Save Memory (Status: Pending)\n API->>Worker: Dispatch Ingest Task\n API-->>User: 202 Accepted (In progress)\n \n Note over Worker: Asynchronous Processing\n Worker->>LLM: Metadata Extraction (Titles, Tags)\n Worker->>Worker: Semantic Chunking (Overlapping Splits)\n \n loop Parallel Enrichment\n Worker->>LLM: Enrich Chunk (Q&A Pairs, Summaries)\n Worker->>LLM: Extract SPO Facts (Subject-Predicate-Object)\n end\n \n Worker->>Vector: Batch Upsert Embeddings (Chunks + Facts)\n Worker->>DB: Write Chunks & Facts (Linked to Memory)\n Worker->>DB: Update Memory Status (Approved/Active)\n```\n\n### Parallelized Retrieval (RAG)\nRetrieval queries run exact relational Fact lookups and fuzzy Semantic Search in parallel to feed LLM contexts with ultra-low latency:\n\n```mermaid\nsequenceDiagram\n participant User\n participant API as FastAPI API\n participant RetSvc as RetrievalService\n participant Vector as Vector Store\n participant DB as Relational DB\n participant LLM as GenAI Model\n\n User->>API: Chat Query / RAG Trigger\n API->>RetSvc: search_memories(Query, project_id)\n \n par State Fact Lookups\n RetSvc->>Vector: Vector Search (Factual matches)\n RetSvc->>DB: SQL Filter (Valid & Non-superseded Facts)\n and Semantic Search\n RetSvc->>Vector: Vector Search (Chunk embeddings)\n RetSvc->>RetSvc: MMR Re-ranking (Filter redundant chunks)\n end\n \n RetSvc->>RetSvc: Merge Results (State Facts + Chunk text)\n RetSvc-->>API: Ranked Top-K Context Items\n \n API->>LLM: Generate Answer (Prompt + Merged Context)\n LLM-->>User: Streaming Response\n```\n\n---\n\n## The LoCoMo Benchmark Evaluation\n\nThe **[LoCoMo-10](https://github.com/snap-research/locomo)** (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).\n\n### Performance Metrics (Memwyre vs. Flat Vector Systems)\n\n| Evaluation Category | Test Description | Flat Vector RAG | Memwyre Engine |\n| :--- | :--- | :---: | :---: |\n| **Single-Hop Recall** | Direct retrieval of personal facts and values | 53.0% | **80.0%** |\n| **Multi-Hop Reasoning** | Linking facts across distant chat sessions | 24.0% | **45.0%** |\n| **Temporal Alignment** | Ordering events and identifying timeframe changes | 48.0% | **74.0%** |\n| **Open-Domain Reasoning** | Contextual inferences and complex reasoning | 50.0% | **76.0%** |\n| **Overall Accuracy** | Weighted average across all 1,540 test questions | 43.7% | **73.5%** |\n| **Mean Token Size** | Average size of retrieved context sent to LLM prompt | ~26,000 | **~3,000** |\n\n> [!TIP]\n> **Context Compression**: Memwyre achieves a **88.5% context length reduction** (retrieving 3,000 tokens instead of the 26,000-token raw conversational dialog) while significantly outperforming flat vector indexing in accuracy.\n\n### Architectural Enablers of LoCoMo Performance\n1. **Dynamic Context Pruning**: Strips out conversational noise (filler words, greetings, and distractors) during chunk enrichment.\n2. **Two-Stage Re-ranking**: Employs a broad, high-recall vector fetch stage followed by a Cross-Encoder re-ranker to pick only the most contextually relevant memory items.\n3. **Ebbinghaus Logarithmic Recency Decay**: Automatically deprecates older user preferences or conflicting facts chronologically when newer entries override them.\n4. **Adversarial Immunity**: Utilizes strict semantic containment, causing the retriever to fail cleanly and refuse hallucinations when queried on non-existent information.\n\n---\n\n## Database Schema & Multi-Tenancy\n\nMemwyre uses a hybrid storage model: metadata, relational facts, and user credentials reside in SQL tables (PostgreSQL/SQLite), while document chunks and enriched fact strings are mirrored in vector databases (Pinecone/ChromaDB).\n\n👉 **[View the Detailed Database Schema](https://github.com/memwyreai/Memwyre/blob/main/docs/database_schema.md)** for a complete breakdown of the Core Entities (`users`, `projects`, `memories`, `documents`, `chunks`, `facts`) and the Entity Relationship Diagram.\n\n### Fact Supersession & Project Containerization\n- **Supersession**: When a new fact matching the same `subject` and `predicate` is written (e.g. user moves from Berlin to Tokyo), the database marks the old record's `is_superseded` flag as `true` and updates `valid_until` to the current timestamp. This guarantees that temporal inquiries return state-accurate facts.\n- **Containerization**: Every memory, document, chunk, and fact contains a `project_id`. When querying, filters strictly enforce containment matching the current workspace's `project_id`, preventing leakage across different project environments.\n\n---\n\n## Installation & Setup\n\n### Prerequisites\n- Python 3.11 or 3.12 (UV package manager recommended)\n- Node.js 18+ & npm\n- Redis server (for background Celery tasks)\n- PostgreSQL database (Optional; SQLite is used by default)\n\n### 1. Backend API Setup\nNavigate to the backend directory, initialize the environment, install dependencies, and start the FastAPI server:\n\n```bash\ncd backend\n\n# Create virtual environment and install packages\nuv venv\nuv pip install -r requirements.txt\n\n# Start the FastAPI server\nuv run uvicorn app.main:app --reload\n```\n*API Swagger UI documentation will be available at `http://localhost:8000/docs`.*\n\n### 2. Background Ingestion Worker\nEnsure Redis is running, then start the Celery background worker to process ingestion queues:\n\n```bash\ncd backend\nuv run celery -A app.celery_app worker --loglevel=info -P solo\n```\n\n### 3. Frontend Dashboard Setup\nInstall frontend packages and spin up the Vite development server:\n\n```bash\ncd frontend\nnpm install\nnpm run dev\n```\n*The web dashboard runs at `http://localhost:5173`.*\n\n### 4. Chrome Extension Installation\n1. Open Chrome and navigate to `chrome://extensions/`\n2. Enable **Developer mode** (top-right toggle)\n3. Click **Load unpacked** (top-left)\n4. Select the `extension/` folder from the root of this project.\n5. In the Web App, go to **Settings** -> **Copy Extension Token** and paste it into the Extension popup to link your session.\n\n### 5. MCP Server Integration\n#### Claude Desktop\nAdd the following to your Claude Desktop config (located at `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n \"mcpServers\": {\n \"brain-vault\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/memwyre/backend/mcp_server.py\"]\n }\n }\n}\n```\n\n#### Cursor / VS Code\nConfigure your editor's MCP settings to run the server via command line:\n```bash\npython /path/to/memwyre/backend/mcp_server.py\n```\n\n### 6. Node CLI Setup\nInstall dependencies and run the command line tool globally:\n\n```bash\ncd cli\nnpm install\nnode index.js --help\n```\n\n---\n\n## Environment Configuration\n\nCopy the example environment file in the `backend/` directory and configure the variables:\n\n```bash\ncp backend/.env.example backend/.env\n```\n\nKey environment parameters:\n\n```env\n# --- Base Secrets & Database ---\nSECRET_KEY=\"your-strong-random-64-character-string\"\nDATABASE_URL=\"postgresql://postgres:password@localhost/brain-vault\"\n\n# --- Redis & Celery ---\nCELERY_BROKER_URL=\"redis://localhost:6379/0\"\nREDIS_URL=\"redis://localhost:6379/0\"\n\n# --- Vector Database (Pinecone) ---\nPINECONE_API_KEY=\"your-pinecone-api-key\"\nPINECONE_HOST=\"https://your-pinecone-index-host\"\nPINECONE_SPARSE_HOST=\"https://your-optional-sparse-index-host\"\n\n# --- LLM Providers & Embeddings ---\nMEMORY_ENGINE_VERSION=\"v2\" # \"v1\" for NVIDIA, \"v2\" for Azure/OpenAI\nAZURE_OPENAI_API_KEY=\"your-azure-key\"\nAZURE_OPENAI_ENDPOINT=\"https://your-resource-name.cognitiveservices.azure.com/\"\nAZURE_OPENAI_DEPLOYMENT=\"gpt-4o-mini\"\nAZURE_OPENAI_EMBEDDING_DEPLOYMENT=\"text-embedding-3-small\"\n\n# --- V1 Compatibility (NVIDIA NIM) ---\nEMBEDDING_API_KEY=\"your-nvidia-embedding-key\"\nLLM_API_KEY=\"your-nvidia-llm-key\"\n```\n\n---\n\n## License\n\nThis project is licensed under the Apache License, Version 2.0 (Apache-2.0). See the [LICENSE](https://github.com/memwyreai/Memwyre/blob/main/LICENSE) and [NOTICE](https://github.com/memwyreai/Memwyre/blob/main/NOTICE) files for details.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_105":106,"_107":108,"_109":110,"_111":112,"_113":114,"_115":116},"requiredSecrets",[],"tags",[96,97,98,99,100,101,102,103,104],"assets",[],"stats",{"_94":81,"_95":81},"ratingAvg","reviewCount","agent-memory","agentic-ai","ai-memory","claude-code-memory","llm","memory-management","openclaw-memory","openclaw-plugin","persistent-memory","topics",[96,97,98,99,100,117,118,101,119,102,103,104],"license","Apache-2.0","language","Vue","registryName","io.github.memwyreai/memwyre","homepage","https://memwyre.tech","packages",[],"mcp","mcp-server","model-context-protocol","ENV",{"_122":123,"_124":125,"_126":127},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]