Skip to main content
Glama
cmdparkour

memory-mcp-server

by cmdparkour

Memory MCP Server

Universal personal memory system for AI assistants — a Model Context Protocol (MCP) server that gives any AI tool persistent, searchable memory across sessions.

Works with Claude Desktop, Cursor, Windsurf, Cline, Roo Code, OpenCode, Continue and any MCP-compatible client.

100% local. No API keys. No cloud. Your memories stay on your machine.


Features

  • Hybrid Search — semantic vector search + full-text keyword search, combined for best results

  • 100% Local — uses FastEmbed for embeddings, runs entirely on your machine

  • Zero Configuvx memory-mcp-server just works

  • Universal — one server, all your AI tools share the same memory

  • Structured — five memory types: preference, project, workflow, knowledge, summary

  • Auto-setup — one command to configure all your AI tools

  • Fast — SQLite + LanceDB, sub-second queries even with thousands of memories

Related MCP server: aivectormemory

Quick Start

Prerequisites

  • Python 3.11+

  • uv (recommended) or pip

Install

# Using uv (recommended)
uv tool install memory-mcp-server

# Or with pip
pip install memory-mcp-server

Auto-Configure All Your AI Tools

memory-mcp-setup setup

This detects your installed AI tools and adds memory-mcp to each one automatically.

Or Configure Manually

See Manual Configuration below.


Supported AI Tools

Tool

Auto-Setup

Manual Config

Claude Desktop

Cursor

Windsurf

Cline (VS Code)

Roo Code (VS Code)

OpenCode

Continue

Any MCP Client


Manual Configuration

Claude Desktop

Add to claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "memory": {
      "command": "uvx",
      "args": ["memory-mcp-server"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "uvx",
      "args": ["memory-mcp-server"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "memory": {
      "command": "uvx",
      "args": ["memory-mcp-server"]
    }
  }
}

Cline (VS Code)

Cline auto-detects MCP servers, or add manually in Cline MCP settings:

{
  "mcpServers": {
    "memory": {
      "command": "uvx",
      "args": ["memory-mcp-server"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Roo Code (VS Code)

Same format as Cline, in Roo MCP settings:

{
  "mcpServers": {
    "memory": {
      "command": "uvx",
      "args": ["memory-mcp-server"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

OpenCode

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "memory": {
      "type": "local",
      "command": ["uvx", "memory-mcp-server"],
      "enabled": true
    }
  }
}

Any MCP Client (stdio transport)

uvx memory-mcp-server

The server communicates over stdio using the MCP protocol.


MCP Tools

The server exposes 6 tools:

Tool

Description

memory_store

Store a new memory with kind, tags, priority

memory_search

Hybrid semantic + keyword search

memory_list

List memories with optional filters

memory_update

Update content, tags, or priority

memory_delete

Delete a memory by ID

memory_stats

Get total count and breakdown

Memory Kinds

Kind

Use For

preference

Personal preferences: coding style, tools, conventions

project

Project-specific: architecture, tech stack, decisions

workflow

Processes: PR flow, deployment steps, review checklists

knowledge

Technical insights: gotchas, solutions, tips

summary

Session summaries: key decisions, outcomes


Teaching Your AI to Use Memory

Copy the contents of SKILL.md into your AI tool's system prompt, custom instructions, or rules file. This teaches the AI when and how to use the memory tools.

Where to Put It

Tool

Location

Claude Desktop

Project Instructions or CLAUDE.md

Cursor

.cursor/rules/*.mdc or Settings → Rules

Windsurf

.windsurfrules

Cline

.clinerules

Roo Code

.roorules

OpenCode

.opencode/skills/memory-system/SKILL.md

Continue

.continue/rules/*.md


CLI Commands

# Auto-configure all detected AI tools
memory-mcp-setup setup

# Auto-configure a specific tool
memory-mcp-setup setup --tool cursor

# Preview config without writing (dry run)
memory-mcp-setup setup --dry-run

# Show config snippet for manual setup
memory-mcp-setup show-config --tool claude-desktop

# Health check
memory-mcp-setup doctor

Environment Variables

Variable

Default

Description

MEMORY_DATA_DIR

Platform-specific (see below)

Directory for memory database files

MEMORY_CACHE_DIR

System default

Cache directory for embedding model

Default Data Directory

Platform

Path

macOS

~/Library/Application Support/memory-mcp/data

Linux

~/.local/share/memory-mcp/data

Windows

%APPDATA%\memory-mcp\data


Architecture

┌─────────────────────────────────────────────┐
│              AI Tool (Client)                │
│  Claude / Cursor / Windsurf / Cline / ...    │
└────────────────┬────────────────────────────┘
                 │ MCP (stdio)
┌────────────────▼────────────────────────────┐
│          memory-mcp-server                   │
│                                              │
│  ┌─────────────┐  ┌──────────────────────┐  │
│  │   FastMCP    │  │   EmbeddingManager   │  │
│  │  (6 tools)   │  │  (FastEmbed/BGE)     │  │
│  └──────┬──────┘  └──────────┬───────────┘  │
│         │                    │               │
│  ┌──────▼────────────────────▼───────────┐  │
│  │           MemoryStore                  │  │
│  │                                        │  │
│  │  ┌──────────┐    ┌─────────────────┐  │  │
│  │  │  SQLite   │    │    LanceDB      │  │  │
│  │  │ metadata  │    │  vector index   │  │  │
│  │  │   + FTS   │    │  (384-dim BGE)  │  │  │
│  │  └──────────┘    └─────────────────┘  │  │
│  └────────────────────────────────────────┘  │
└──────────────────────────────────────────────┘
  • SQLite: stores memory metadata, supports full-text search via FTS5

  • LanceDB: stores embedding vectors, supports fast approximate nearest neighbor search

  • FastEmbed: runs BAAI/bge-small-en-v1.5 locally for 384-dimensional embeddings


Development

# Clone
git clone https://github.com/cmdparkour/memory-mcp-server.git
cd memory-mcp-server

# Install with dev dependencies
uv sync

# Run directly
uv run memory-mcp

# Run setup CLI
uv run memory-mcp-setup doctor

FAQ

Does it need an API key?

No. Everything runs locally — embedding model included.

Does it support Chinese / non-English languages?

Yes. The BGE embedding model supports multilingual text. SQLite FTS5 also handles CJK characters.

Can multiple AI tools share the same memory?

Yes — that's the whole point. All tools point to the same local database.

Where is my data stored?

See Default Data Directory. You can override with MEMORY_DATA_DIR.

How do I back up my memories?

Copy the data directory. It contains a SQLite database and a LanceDB folder.

How do I reset all memories?

Delete the data directory.


License

MIT — see LICENSE.

Available Tools

6 tools
memory_deleteC

Delete a memory by ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
memory_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It does not mention if deletion is irreversible, requires confirmation, or has any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (5 words) and front-loaded. While it could benefit from more detail, it contains no unnecessary content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema and only one parameter, the description lacks essential context for a destructive operation, such as consequences or prerequisites.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description adds no meaning beyond the parameter name. It does not explain how to obtain the memory_id or any constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (delete) and resource (memory) with the method (by ID). It is distinct from siblings like memory_list or memory_store.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives such as memory_update or memory_store. No when-not-to-use conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_listB

List memories with optional filters. Ordered by creation date descending.

ParametersJSON Schema
NameRequiredDescriptionDefault
kindNo
projectNo
limitNo
offsetNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It mentions ordering but does not disclose pagination behavior (limit/offset), filter matching semantics, or any rate limits. For a query tool, this is adequate but could be improved.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, efficient and front-loaded with purpose. However, it could integrate parameter descriptions without adding bulk.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters and an output schema, the description fails to explain filter fields, pagination, or return structure. It lacks context needed for a complete understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must explain parameters. It only mentions 'optional filters' without naming or describing kind, project, limit, offset, leaving the agent to infer from parameter names alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'list' and resource 'memories', with additional details about optional filters and ordering by creation date descending. This distinguishes it from sibling tools like memory_store, memory_delete, etc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for listing with filters but does not explicitly state when to use this tool over siblings like memory_search. It provides no exclusion criteria or alternative recommendations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_statsA

Get memory system statistics: total count, breakdown by kind and project.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, but the description clearly indicates a read-only, non-destructive operation. Behavioral traits like authentication or response format are not detailed, but the presence of an output schema partially compensates.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single, concise sentence that front-loads the core purpose with no extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a parameterless stats tool with an output schema; clearly communicates what statistics are returned and the breakdown dimensions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist (0 params), so schema coverage is effectively 100%. Baseline is 4 for zero parameters; description adds no further parameter info, which is acceptable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it retrieves memory system statistics including total count and breakdown by kind and project, distinguishing it from sibling CRUD tools like memory_delete and memory_store.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use, but the context of zero parameters and being a stats tool implies it's for global aggregation. Sibling names imply alternatives for specific operations, but no direct guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_storeC

Store a memory. kind must be one of: preference, project, workflow, knowledge, summary.

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYes
kindYes
tagsNo
sourceNo
projectNo
priorityNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.4/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description fails to disclose any behavioral traits. It does not mention idempotency, side effects, persistence guarantees, or error behavior (e.g., handling invalid 'kind'). This leaves the agent unaware of critical operational characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise at two sentences, with no superfluous words. However, it leans toward under-specification rather than optimal conciseness, as key details are omitted. Despite this, it is well-structured and front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 6 parameters (2 required), zero schema coverage, and no annotations, the description is severely incomplete. It does not cover the behavior of optional parameters, nor does it hint at the output schema (though one exists). The agent would lack sufficient context to use the tool correctly in diverse scenarios.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description adds limited parameter meaning. It clarifies that 'kind' has a set of allowed values, which is helpful. However, it does not explain the purpose or expected format of 'content,' 'tags,' 'source,' 'project,' or 'priority,' leaving the agent to infer from parameter names alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Store a memory.' It specifies that 'kind' must be one of the listed values, which clarifies the resource type. However, it does not explicitly differentiate from sibling tools like 'memory_update,' which could cause confusion about additive vs. updative behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a list of valid 'kind' values but offers no guidance on when to use this tool versus alternatives (e.g., memory_update, memory_delete). It lacks context on prerequisites, common use cases, or scenarios where this tool is preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_updateB

Update an existing memory's content, tags, or priority.

ParametersJSON Schema
NameRequiredDescriptionDefault
memory_idYes
contentNo
tagsNo
priorityNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It indicates a mutation but does not disclose behavior for missing memory_id, partial vs full update, or side effects. The optional fields in schema suggest partial update, but description omits this.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence of 8 words, front-loaded with action and resource. No unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists but is not shown; still, description needn't explain return values. However, with 4 parameters, 0% schema coverage, and no annotations, the description is too brief. It fails to clarify partial update behavior, error handling, or required format of fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It lists the field names (content, tags, priority) but adds no extra meaning about format, constraints, or relationships. The schema provides basic type info, but description adds no semantic value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (update), resource (existing memory), and fields (content, tags, priority). It distinguishes from siblings like memory_store (create) and memory_delete (delete).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for modifying existing memories but does not explicitly state when to use this over alternatives. It lacks guidance on prerequisites (e.g., requires existing memory_id) or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updatesv0.2.0
    • First observedmemory_delete
    • First observedmemory_list
    • First observedmemory_search
    • First observedmemory_stats
    • First observedmemory_store
    • First observedmemory_update

TDQS

A3.5/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: delete by ID, list with filters, search by similarity/keywords, get stats, store new, update existing. No overlap.

Naming Consistency5/5

All tools follow a consistent 'memory_verb' pattern in snake_case, making the operation immediately clear.

Tool Count5/5

6 tools is well-scoped for a memory system, covering core operations without unnecessary bloat.

Completeness4/5

Covers CRUD (store, list, search, update, delete) plus stats. Minor gap: no explicit get-by-id, but list/search likely return full memory objects.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/cmdparkour/memory-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server