Skip to main content
Glama

Qwen Memory MCP

Long-term memory for AI agents, powered by Qwen on Alibaba Cloud and exposed over the Model Context Protocol (MCP). Any MCP-capable agent gains durable, cross-session memory that accumulates experience, retrieves what matters within a limited context window, and forgets what is outdated.

Hackathon track: Track 1 - MemoryAgent. License: MIT. Copyright (c) 2026 JHELY GLOBAL SL.

Repository: https://github.com/John-CEO-HQ/qwen-memory-mcp

Demo video: https://youtu.be/ZxXKvVY6iMQ

This project is a learning experiment for the Qwen Cloud Hackathon: a standalone MCP server for agent memory on Alibaba Cloud.

Documentation

Guide

Purpose

docs/TESTING-GUIDE.md

Master index: testing phases and pass criteria

docs/CREDENTIALS-AND-SETUP.md

Accounts, API keys, regions, cost guardrails

docs/PHASE1-REMOTE-INTEGRATION.md

Live Qwen / DashScope tests from your machine

docs/PHASE2-DEPLOYMENT-TESTING.md

Alibaba deploy + verify deployed URL

docs/INSTALL.md

Full install, local run, Alibaba production deploy, troubleshooting

docs/JUDGE-TESTING.md

Instructions for hackathon judges

deploy/README.md

Alibaba ECS / Function Compute quick reference

AGENTS.md

Agent conventions and isolation contract

Related MCP server: mindcore-memory-mcp

Why

Agents feel sharp inside a single conversation and amnesiac across sessions. This server gives an agent a managed memory layer that does four things well:

  • Write - extract a durable memory (preference, fact, commitment, event), with a Qwen-derived summary, tags, importance (salience), and kind.

  • Search - semantic retrieval ranked by similarity + salience + recency + reinforcement.

  • Recall context - pack the most critical memories into a fixed token budget, ready to inject into a small context window.

  • Forget - a maintenance pass that consolidates related memories with Qwen and lets stale, low-value memories decay away.

Architecture

flowchart LR
  agent["Any MCP client / agent"] -->|"MCP: write / search / recall / forget"| server["Qwen Memory MCP server (stdio or HTTP)"]
  server --> service["MemoryService"]
  service -->|"embeddings + reasoning"| qwen["Qwen on Alibaba Cloud Model Studio (DashScope)"]
  service -->|"persist + retrieve"| store["MemoryStore"]
  store --> file["File / in-memory (local + demo)"]
  store --> mysql["Alibaba Cloud RDS / PolarDB for MySQL (production)"]

Memory lifecycle:

flowchart TD
  w["memory_write"] --> analyze["Qwen analyze: summary, tags, salience, kind"]
  analyze --> embed1["Qwen embed (text-embedding-v3)"]
  embed1 --> active["active memory"]
  active --> s["memory_search / memory_recall_context"]
  s --> rank["rank: similarity + salience + recency + reinforcement"]
  rank --> pack["pack into token budget"]
  s -.reinforce.-> active
  active --> f["memory_forget"]
  f --> cluster["cluster by embedding similarity"]
  cluster --> consolidate["Qwen consolidate cluster -> canonical memory"]
  consolidate --> outdated["flag contradicted items -> forgotten"]
  active --> decay["decay score below threshold -> forgotten"]

Quick start

npm install

# Offline demo (no API key needed - deterministic local intelligence):
npm run demo

# Run the test suite:
npm test

# Run as an MCP server over stdio (for MCP Inspector / desktop clients):
npm run build && npm start

To use the real Qwen models, copy .env.example to .env and set QWEN_API_KEY (and optionally QWEN_BASE_URL for your region). Without a key, the server automatically falls back to the offline deterministic intelligence so it always runs.

MCP tools

Tool

Purpose

Key inputs

memory_write

Persist a durable memory

userId, content, sourceSession?, salience?

memory_search

Top-k semantic recall

userId, query, k?

memory_recall_context

Critical memories packed to a token budget

userId, query, tokenBudget

memory_forget

Consolidate + decay maintenance

userId

All memories are namespaced by userId, so one server can serve many agents.

Transports

  • stdio (MCP_TRANSPORT=stdio, default) - launched as a child process by a local MCP client.

  • Streamable HTTP (MCP_TRANSPORT=http) - stateless JSON-RPC at POST /mcp with optional Authorization: Bearer <MCP_AUTH_TOKEN>, plus GET /health. This is the shape used for cloud deployment and remote per-user MCP URLs.

Storage

  • MEMORY_STORE=memory - in-process, ephemeral (tests/demo).

  • MEMORY_STORE=file - single JSON file at MEMORY_FILE_PATH (local default).

  • MEMORY_STORE=mysql - Alibaba Cloud RDS / PolarDB for MySQL (production); schema is created automatically. Vectors are stored as JSON and scored in the app; see src/memory/mysql-store.ts for the AnalyticDB-PG (pgvector) upgrade path.

Alibaba Cloud / Qwen

The only integration points with Alibaba Cloud are src/qwen.ts (DashScope embeddings + chat) and src/memory/mysql-store.ts (RDS/PolarDB). See docs/INSTALL.md for full production setup and deploy/README.md for a short Alibaba quick reference.

Configuration

See .env.example for all variables (Qwen models, store selection, transport, auth token, and forgetting/decay tuning).

Layout

qwen-memory-mcp/
  src/
    qwen.ts               # Alibaba Cloud / Qwen (DashScope) intelligence  [PROOF]
    fake-intelligence.ts  # offline deterministic intelligence (tests/demo)
    intelligence.ts       # picks Qwen vs fake
    config.ts             # env-driven config
    types.ts              # domain types
    memory/
      store.ts            # MemoryStore interface
      file-store.ts       # file / in-memory store
      mysql-store.ts      # Alibaba RDS / PolarDB store               [PROOF]
      create-store.ts     # store factory
      ranking.ts          # retrieval ranking + token-budget packing
      forgetting.ts       # clustering + consolidation + decay
      service.ts          # MemoryService (orchestration)
    server.ts             # MCP server + 4 tools
    transports/
      stdio.ts            # stdio transport
      http.ts             # streamable HTTP transport (stateless)
    index.ts              # entry point
  demo/cli.ts             # multi-session offline demo
  test/                   # vitest suite
  deploy/                 # Alibaba Cloud deployment docs
  Dockerfile

License

MIT License. Copyright (c) 2026 JHELY GLOBAL SL. See LICENSE.

Available Tools

4 tools
memory_forgetConsolidate and forgetA

Runs the maintenance pass: clusters of related memories are merged by Qwen into one canonical memory, contradicted/outdated items are forgotten, and stale low-importance memories decay away. Returns a report of what was consolidated, archived, forgotten, and retained.

Inputs: userId (required).

memory_recall_contextRecall context within a token budgetB

Returns the most critical memories for a query, greedily packed to fit a token budget, as a ready-to-inject context block. Use this to load long-term memory into a limited context window before answering.

Inputs: query (required), userId (required), tokenBudget (required).

memory_writeWrite memoryA

Persist something worth remembering about a user (a preference, fact, commitment, or event). Qwen derives a short summary, tags, importance (salience), and kind. Call this whenever the user reveals durable information you should recall in future sessions.

Inputs: userId (required), content (required), salience, sourceSession.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: writing new memories, searching them, recalling context for a query, and running maintenance. No overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent 'memory_<verb>' pattern, making the action clear and predictable.

    Tool Count5/5

    Four tools cover the core memory operations (write, search, recall, maintenance) without unnecessary bloat. The scope is appropriate for a memory management server.

    Completeness3/5

    Missing explicit update and list operations; however, the automatic maintenance and selective retrieval cover common use cases. Gaps exist for direct manipulation of individual memories.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      A production-grade long-term memory MCP server that enables AI agents to persist and recall memories across sessions with importance weighting, confidence calibration, and efficient context window management.
      9
      18 PyPI
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Persistent, searchable memory for AI agents over the Model Context Protocol, enabling memory storage, full-text search with BM25 ranking, and retrieval across sessions.
      8 npm
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      A persistent memory server for AI agents using MCP protocol, enabling semantic storage and retrieval of dialogues, documents, and agent states.
      -