Generated banner for mnemory
Generated logo for mnemory

mnemory

Memory server

Created by Filip Pytloun

Published in fpytloun/mnemory. Publisher page

283 GitHub stars

What it is

A self-hosted, secure, feature-rich memory system for AI agents and assistants. Provides intelligent fact extraction and deduplication, with an artifact store for detailed content.
— the description by Filip Pytloun

AutoGineer overview, from the brain’s own files

mnemory is a self-hosted memory system designed to provide AI agents and assistants with persistent, long-term memory. It functions as an MCP server, allowing it to integrate seamlessly with various AI clients like Claude Code, Cursor, and Open WebUI. The system uses a two-tier architecture: a vector store for fast, semantically searchable summaries and an artifact store for detailed content. It features an intelligent pipeline that performs fact extraction, deduplication, and contradiction resolution in a single LLM call. mnemory also includes a built-in management UI for monitoring and memory maintenance, along with health checks to ensure data quality. It is built for production environments with support for Qdrant, S3/MinIO, and Prometheus monitoring.

How it works

Memory model: Vector store

AutoGineer overview, from the brain’s own files

mnemory operates by intercepting information shared during agent conversations. It uses an LLM pipeline to extract facts, classify them by importance and category, and resolve contradictions against existing data. These facts are stored in a vector database for semantic search, while detailed artifacts are kept in a separate store. During interaction, the system retrieves relevant memories based on the current context and user queries. It also manages memory lifecycles using configurable time-to-live (TTL) settings and provides a health-checking mechanism to detect and fix data inconsistencies.

Folders
FolderRoleFiles
.githubagent-config4
docsdocs31
teststests42
benchmarksfolder16
filesfolder8
integrationsfolder40
mnemoryfolder59

The agent reads

The agent writes

Requirements

Runtimes: Python >=3.11

Databases: Qdrant, Redis

API keys (by name): OPENAI_API_KEY

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Google Antigravity, Kiro, OpenCode, Amp, Roo Code, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. Not scanned by AutoGineerIts dependencies are installed by pip or uv when you run it and were not scanned by AutoGineer (9 declared). https://pypi.org/project/mnemory/
  2. Created by Filip Pytloun. Published in fpytloun/mnemory. Licence: Apache License 2.0.

Usage

AutoGineer overview, from the brain’s own files

  • Connects to AI agents via the Model Context Protocol (MCP).
  • Provides a REST API for custom integrations and plugin development.
  • Includes a web-based dashboard for memory management and visualization.
  • Supports automatic recall and memory persistence across sessions.
  • Offers built-in health checks and maintenance tools for memory quality.
  • Integrates with monitoring tools like Prometheus and Grafana.
“What did I decide last week about the database?”
The agent performs a temporal-aware semantic search across stored memories to retrieve the specific decision made.
“I drive a Skoda.”
The system extracts this fact and stores it; if a later statement says 'I bought a Tesla', it updates the record instead of creating a duplicate.

Documentation by Filip Pytloun

<p align="center"> <img src="files/banner.png" alt="mnemory banner" /> </p>

mnemory

Looking for a complete Agent OS? Meet Cognis — a cloud-native, self-hosted workspace where AI agents do real work. Bring together conversations, tools, workflows, and remote executors, with long-term memory powered by mnemory and guardrails provided by Intaris.

Deletion is intentionally best effort, not a verified-erasure or compliance guarantee. Normal deletion retracts and preserves history; explicit privacy erasure attempts physical cleanup. See deletion limits.

Give your AI agents persistent memory. mnemory is a self-hosted MCP server that adds personalization and long-term memory to any AI assistant — Claude Code, ChatGPT, Open WebUI, Cursor, or any MCP-compatible client.

Plug and play. Connect mnemory and your agent immediately starts remembering user preferences, facts, decisions, and context across conversations. No system prompt changes needed.

Self-hosted and secure. Your data stays on your infrastructure. No cloud dependencies, no third-party access to your memories.

Intelligent. Uses a unified LLM pipeline for fact extraction, deduplication, and contradiction resolution in a single call. Memories are semantically searchable, automatically categorized, and expire naturally when no longer relevant.

Features

  • Zero config — uvx mnemory, connect your MCP client, done. Works out of the box with any OpenAI-compatible API.

  • Intelligent extraction — A single LLM call extracts facts, classifies metadata, and deduplicates against existing memories.

  • Contradiction resolution — "I drive a Skoda" + later "I bought a Tesla" = automatic update, not a duplicate.

  • Two-tier memory — Fast searchable summaries in a vector store + detailed artifact storage (reports, code, research) retrieved on demand.

  • AI-powered search — Multi-query semantic search with temporal awareness. Ask "What did I decide last week about the database?" and it finds the right memories.

  • Memory health checks — Built-in three-phase consistency checker (fsck) detects duplicates, contradictions, quality issues, and prompt injection. Run manually or on a schedule with auto-fix.

  • 10+ client support — Claude Code, ChatGPT, Open WebUI, OpenClaw, Cursor, Windsurf, Cline, OpenCode, and more. Native plugins available for automatic recall/remember.

  • Built-in management UI — Dashboard, semantic search, memory browser with full CRUD, relationship graph visualization, and health check interface. No extra tools needed.

  • Production ready — Qdrant for vectors, S3/MinIO for artifacts, API key or Cognis JWT authentication, per-user isolation, Kubernetes-friendly stateless HTTP.

  • Secure by default — API key or Cognis JWT authentication with session-level identity binding, per-user memory isolation, anti-injection safeguards in extraction prompts.

  • REST API + MCP — Dual interface with the same backend. 16 MCP tools + full REST API with OpenAPI spec. Build plugins, integrations, or use directly.

  • Prometheus monitoring — Built-in /metrics endpoint with operation counters and memory gauges. Pre-built Grafana dashboard included.

Quick Start

mnemory needs an OpenAI-compatible API key for LLM and embeddings. It picks up OPENAI_API_KEY from your environment automatically.

uvx mnemory

If uvx reports No module named 'mcp.server.fastmcp', update uv. Older uv versions on Alpine can ignore mnemory's MCP v1 dependency constraint. Until you update uv, run:

uvx --with "mcp<2" mnemory

That's it. mnemory starts on http://localhost:8050/mcp, stores data in ~/.mnemory/.

Now connect your client — for Claude Code, add to your MCP config:

{
  "mcpServers": {
    "mnemory": {
      "type": "streamable-http",
      "url": "http://localhost:8050/mcp",
      "headers": {
        "X-Agent-Id": "claude-code"
      }
    }
  }
}

Start a new conversation. Memory works automatically.

Also available via Docker, pip, or production setup with Qdrant + S3. See the full quick start guide for more clients and options.

Screenshots

<p align="center"> <img src="files/screenshots/ui-dashboard.jpg" alt="Dashboard — memory totals, breakdowns, and operation counts" width="800" /> <br><em>Dashboard with memory breakdowns by type, category, and role</em> </p>

<p align="center"> <img src="files/screenshots/ui-search.jpg" alt="Search — semantic and AI-powered search with filters" width="800" /> <br><em>Semantic search and AI-powered find with filters</em> </p>

<p align="center"> <img src="files/screenshots/ui-graph.jpg" alt="Graph — D3.js force-directed memory relationship visualization" width="800" /> <br><em>Memory relationship graph visualization</em> </p>

See all screenshots and UI features including memory browser, health checks, and artifact management.

Supported Clients

mnemory works with any MCP-compatible client. Some clients also have dedicated plugins for automatic recall/remember.

ClientMCPPluginSetup Guide
Claude CodeYesYes (hooks)Guide
ChatGPTYes (MCP connector)--Guide
Claude DesktopYes--Guide
Hermes AgentYesYes (plugin)Guide
Open WebUIYesYes (filter)Guide
OpenCodeYesYes (plugin)Guide
OpenClawYesYes (plugin)Guide
CursorYes--Guide
WindsurfYes--Guide
ClineYes--Guide
Continue.devYes--Guide
Codex CLIYes--Guide

MCP = works via Model Context Protocol (LLM-driven tool calls). Plugin = dedicated integration with automatic recall/remember (no LLM tool-calling needed).

How It Works

Storing: You share information naturally. mnemory extracts individual facts, classifies them (type, category, importance), checks for duplicates and contradictions against existing memories, and stores them as searchable vectors — all in a single LLM call.

Searching: Ask a question and mnemory generates multiple search queries covering different angles and associations, runs them in parallel, and reranks results by relevance. Temporal-aware — "what did I decide last week?" just works.

Recalling: At conversation start, your agent loads pinned memories (core facts, preferences, identity) plus recent context. During conversation, relevant memories are found automatically based on what you're discussing.

Maintaining: Memories have configurable TTL — context expires in 7 days, episodic memories in 90. Frequently accessed memories stay alive (reinforcement). The built-in health checker detects and fixes duplicates, contradictions, and quality issues.

Learn more in the architecture docs.

Benchmark

Evaluated on the LoCoMo benchmark — 10 multi-session dialogues with 1540 QA questions across 4 categories:

Systemsingle_hopmulti_hoptemporalopen_domainOverall
mnemory63.153.174.878.273.2
mnemory (gpt-oss-120b)66.359.468.573.870.5
Memobase70.952.185.077.275.8
Mem0-Graph65.747.258.175.768.4
Mem067.151.255.572.966.9
Zep61.741.449.376.666.0
LangMem62.247.923.471.158.1

Configuration: gpt-5-mini for extraction, text-embedding-3-small for vectors. gpt-oss-120b via Groq is a budget alternative at ~5x lower cost with comparable quality. See configuration docs for model options and benchmarks/ for reproduction.

Documentation

DocumentDescription
Quick StartGet running in 5 minutes with any client
ConfigurationAll environment variables — LLM, storage, server, memory behavior
Memory ModelTypes, categories, importance, TTL, roles, scoping, sub-agents
MCP Tools16 MCP tools — memory CRUD, search, artifacts
REST APIFull REST API, fsck pipeline, recall/remember endpoints
ArchitectureSystem diagram, detailed flows for storing/searching/recalling
Management UIScreenshots, features, access, UI development
MonitoringPrometheus metrics, Grafana dashboard
DeploymentProduction setup, Docker, authentication, Kubernetes
DevelopmentBuilding, testing, linting, contributing
Client GuidesPer-client setup instructions (10 clients)
System PromptsTemplates for personality agents and custom setups

License

Apache 2.0

LICENSE

Shown as plain text.

                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship made available under
      the License, as indicated by a copyright notice that is included in
      or attached to the work (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean, as submitted to the Licensor for inclusion
      in the Work by the copyright owner or by an individual or Legal Entity
      authorized to submit on behalf of the copyright owner. For the purposes
      of this definition, "submitted" means any form of electronic, verbal,
      or written communication sent to the Licensor or its representatives,
      including but not limited to communication on electronic mailing lists,
      source code control systems, and issue tracking systems that are managed
      by, or on behalf of, the Licensor for the purpose of discussing and
      improving the Work, but excluding communication that is conspicuously
      marked or otherwise designated in writing by the copyright owner as
      "Not a Contribution."

      "Contributor" shall mean Licensor and any Legal Entity on behalf of
      whom a Contribution has been received by the Licensor and subsequently
      incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by the combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a cross-claim
      or counterclaim in a lawsuit) alleging that the Work or any Contribution
      incorporated within the Work constitutes direct or contributory patent
      infringement, then any patent licenses granted to You under this License
      for that Work shall terminate as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or Derivative Works
          a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, You must include a readable copy of the attribution
          notices contained within such NOTICE file, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own license statement for Your modifications and
      may provide additional grant of rights to use, copy, modify, merge,
      publish, distribute, sublicense, and/or sell copies of the Work,
      and to permit persons to whom the Work is furnished to do so,
      subject to the following conditions.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or exemplary damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or all other
      commercial damages or losses), even if such Contributor has been
      advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   Copyright 2026 Filip Pytloun

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
   implied. See the License for the specific language governing
   permissions and limitations under the License.
212 files · 196 not served here

Advantages

  • Intelligent extraction and contradiction resolution ensure memory accuracy and prevent duplicate entries. evidence: README.md
  • Self-hosted architecture ensures data privacy with no third-party access to stored memories. evidence: README.md
  • Supports a wide range of clients through the Model Context Protocol and dedicated plugins. evidence: README.md

Limitations

  • Deletion is best-effort and does not guarantee verified erasure or compliance. evidence: README.md
  • Most MCP clients require a specific system prompt instruction to initialize memory correctly. evidence: docs/README.md

Security

Risk level: Low risk

This brain runs

Agent instructions that run or fetch something (8)

  • AGENTS.md: docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/fpytloun/mnemory:latest .
  • AGENTS.md: docker buildx build --platform linux/amd64,linux/arm64 --push -t ghcr.io/fpytloun/mnemory:latest .
  • AGENTS.md: # Unit tests (fast, no API key needed, default pytest run)
  • AGENTS.md: They are **excluded from the default `pytest` run** via `addopts = "-m 'not e2e'"` in `pyproject.toml`.
  • AGENTS.md: **When to run e2e tests:**
  • AGENTS.md: Migrations run automatically on startup before the server accepts requests.
  • AGENTS.md: Each migration has a unique ID (e.g., `001_add_sparse_vectors`), a `description`, and a `run()` method
  • AGENTS.md: Migrations must be **idempotent** — safe to re-run if interrupted mid-way or if multiple instances start simultaneously

MCP servers (1)

  • README.md (mnemory): http://localhost:8050/mcp · uses the network
  • Low risk: network-instructions (AGENTS.md:88)

Attribution and licence

Created by
Filip Pytloun
Declared authors
  • Filip Pytloun (declared in pyproject.toml)
Publisher
Filip Pytloun (Community)
Source
fpytloun/mnemory · commit 2d83c47
Licence
Apache License 2.0 (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Filip Pytloun.

Install from source

196 of its files are not served here, so there is no ZIP. fpytloun/mnemory at 2d83c47