MindCore Memory MCP

mcp-name: io.github.woshilaohei/mindcore-memory

AI Long-Term Memory Server — Production-grade persistent memory for AI agents.

"The best AI agent isn't the smartest — it's the one that remembers."

Table of Contents

• Why MindCore Memory
• Quick Start
• Installation
• MCP Client Setup
• Core Tools
• Eval Results
• Architecture
• Development
• License

Why MindCore Memory

AI agents today face a fundamental limitation: they forget everything between sessions.

MindCore Memory is the missing persistence layer for AI agents. Built as an MCP server, it plugs into any MCP-compatible client (Claude Desktop, Cursor, Cline, etc.) with zero configuration changes.

Quick Start

# 1. Install
pip install mindcore-memory

# 2. Launch MCP Server
mindcore-memory

# 3. Store a memory
# Your AI agent can now call:
memory_store(
    content="User's name is Zhang San, prefers Python, free on Wednesdays",
    importance=3,
    tags=["user-profile", "schedule"],
    confidence=0.95
)

# 4. Recall later (even across sessions!)
results = memory_recall(
    query="Zhang San's schedule and preferences",
    limit=5
)

Installation

Via pip (Recommended)

pip install mindcore-memory

Via pipx (Isolated)

pipx install mindcore-memory

From Source

git clone https://github.com/woshilaohei/mindcore-memory-mcp.git
cd mindcore-memory-mcp
pip install -e .

Requirements

• Python 3.10 or higher
• No external database required (uses embedded TinyDB)

MCP Client Setup

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mindcore-memory": {
      "command": "python",
      "args": ["-m", "mindcore_memory.server"]
    }
  }
}

Cursor / Cline / Roo Code

{
  "mcpServers": {
    "mindcore-memory": {
      "command": "python",
      "args": ["-m", "mindcore_memory.server"],
      "env": {
        "MINDCODE_MEMORY_FILE": "~/.mindcore/memory.json"
      }
    }
  }
}

Any MCP Client (Generic)

{
  "mcpServers": {
    "mindcore-memory": {
      "command": "python",
      "args": ["-m", "mindcore_memory.server"]
    }
  }
}

Core Tools

memory_store — Store a Memory

memory_store(
    content="Python was created by Guido van Rossum",
    importance=3,          # 1 (low) to 4 (critical)
    tags=["python", "history"],
    confidence=0.95,       # 0.0 to 1.0
    source="agent"         # "agent", "user", or "tool"
)

Returns a memory_id for later reference.

memory_recall — Search Memories

memory_recall(
    query="Who created Python?",
    tags=["python"],       # Optional: filter by tags
    limit=10,              # Max results
    min_confidence=0.7     # Confidence threshold
)

Returns ranked results by relevance × importance × confidence.

memory_context — Build Context Window

memory_context(
    query="Current project architecture decisions",
    max_tokens=2000,       # Auto-truncates to fit context
    tags=["architecture"]  # Optional tag filter
)

Smart deduplication + priority sorting. Never overloads the context window.

memory_update — Update a Memory

memory_update(
    memory_id="abc123",
    content="Updated: Python 3.13 is now the latest stable release",
    importance=4,
    confidence=0.99
)

memory_delete — Remove a Memory

memory_delete(memory_id="abc123")

memory_stats — Memory Statistics

stats = memory_stats()
# Returns: total memories, per-tag counts, average confidence, storage size

Eval Results

Our evaluation framework tests every dimension of memory quality:

Storage Integrity:        100% — Data persists correctly across restarts
Recall Relevance:         100% — Relevant memories recalled first
Confidence Calibration:   100% — Confidence scores match actual relevance
Importance Weighting:     100% — High-priority memories always ranked higher
Context Efficiency:       100% — Context window never overloaded
Deduplication Accuracy:   100% — No duplicate memories in context

Overall Score: 100%

Architecture

+------------------+     MCP Protocol     +---------------------+
|                  | <--- JSON-RPC -----> |                     |
|  AI Client       |       (stdio)        |  MindCore Memory    |
|  (Claude/Cursor) |                      |  MCP Server         |
|                  |                      |                     |
+------------------+                      +----------+----------+
                                                     |
                                            +--------v--------+
                                            |                 |
                                            |  Memory Engine  |
                                            |  - Store        |
                                            |  - Recall       |
                                            |  - Context      |
                                            |  - Update       |
                                            |  - Delete       |
                                            |                 |
                                            +--------+--------+
                                                     |
                                            +--------v--------+
                                            |                 |
                                            |  TinyDB         |
                                            |  (Embedded)     |
                                            |                 |
                                            +-----------------+

• Zero Dependencies: No PostgreSQL, Redis, or vector DB needed
• Embedded Database: TinyDB stores memories as local JSON files
• MCP Native: Implements Model Context Protocol over stdio transport
• Scoring Engine: Combines importance, confidence, recency, and relevance

Find Us

MindCore Memory is listed on all major MCP directories:

Development

# Clone and install dev dependencies
git clone https://github.com/woshilaohei/mindcore-memory-mcp.git
cd mindcore-memory-mcp
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Run type checker
mypy mindcore_memory/

License

MIT License — Copyright (c) 2025 Lao Hei

Links

• GitHub: https://github.com/woshilaohei/mindcore-memory-mcp
• PyPI: https://pypi.org/project/mindcore-memory/
• MCP Registry: https://registry.modelcontextprotocol.io/servers/io.github.woshilaohei/mindcore-memory
• Issues: https://github.com/woshilaohei/mindcore-memory-mcp/issues