MCP 服务器

HKC Memory Server

An MCP server for managing persistent AI memory using hybrid search (keyword + semantic vector) with SQLite storage and offline-first local embeddings.

README

HKC Memory Server

A high-performance Model Context Protocol (MCP) server for managing persistent AI memory using hybrid search (keyword + semantic vector search). This server provides a sophisticated memory management system for AI assistants, enabling them to store, retrieve, and organize contextual information efficiently.

Features

Hybrid Search: Combines SQLite FTS5 (full-text search) with semantic vector embeddings for optimal retrieval
UCMF Format: Ultra-Compact Memory Format for efficient memory serialization
Persistent Storage: SQLite database with optimized WAL mode
Offline-First: Uses local embedding models (sentence-transformers) with no network dependency
Memory Management: Tools for saving, retrieving, optimizing, and pruning memories
Confidence Scoring: Weighted importance system for memory prioritization

Requirements

System Requirements

Python 3.8 or higher
SQLite 3.x (with FTS5 support)
2GB+ RAM recommended for embedding model

Python Dependencies

All dependencies are listed in requirements.txt:

mcp
fastmcp
aiofiles
langchain-huggingface
sentence-transformers
numpy

Embedding Model

The server uses sentence-transformers/all-MiniLM-L6-v2 (384-dimensional embeddings). The model will be automatically downloaded on first run to:

Windows: %USERPROFILE%\.cache\huggingface\hub\
Linux/Mac: ~/.cache/huggingface/hub/

Alternatively, you can:

Set HKC_EMBED_MODEL_PATH environment variable to point to a local model directory
Place the model in a ./models/all-MiniLM-L6-v2/ folder relative to the server script

Installation

1. Clone or Download

git clone <your-repo-url>
cd hkc-memory-server

2. Create Virtual Environment (Recommended)

# Windows
python -m venv .venv
.venv\Scripts\activate

# Linux/Mac
python3 -m venv .venv
source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Download Embedding Model (Optional - Pre-download)

python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')"

LM Studio MCP Configuration

To use this server with LM Studio, add the following configuration to your LM Studio MCP settings JSON file:

Windows Configuration

{
  "mcpServers": {
    "hkc-memory": {
      "command": "C:\\path\\to\\your\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\your\\hkc-memory-server\\hkc_memory_server.py"
      ],
      "env": {
        "VIRTUAL_ENV": "C:\\path\\to\\your\\.venv"
      }
    }
  }
}

Linux/Mac Configuration

{
  "mcpServers": {
    "hkc-memory": {
      "command": "/path/to/your/.venv/bin/python",
      "args": [
        "/path/to/your/hkc-memory-server/hkc_memory_server.py"
      ],
      "env": {
        "VIRTUAL_ENV": "/path/to/your/.venv"
      }
    }
  }
}

Important: Replace the paths with your actual installation paths.

Usage

Starting the Server Manually

python hkc_memory_server.py

The server will:

Initialize the SQLite database (memory_index.db)
Create necessary directories (backups/, conversations/)
Generate the UCMF legend file if not present
Start the MCP server and wait for connections

Available MCP Tools

1. `save_memory`

Saves a new memory to the database.

Parameters:

memory_detail (string): The content of the memory
category (string): Category tag (e.g., "preferences", "goals", "relationships")
importance (float): Confidence score between 0.0 and 1.0
reasoning (string, optional): Why this memory is important
who (string, optional): Person associated with the memory (default: "User")

Example:

save_memory(
    memory_detail="Prefers dark mode for all applications",
    category="preferences",
    importance=0.8,
    reasoning="User explicitly mentioned multiple times"
)

2. `retrieve_memories`

Retrieves relevant memories using hybrid search.

Parameters:

context_keywords (list of strings): Keywords for semantic search
categories (list of strings, optional): Filter by categories
limit (int, optional): Maximum results to return (default: 10)

Example:

retrieve_memories(
    context_keywords=["dark mode", "UI preferences"],
    categories=["preferences"],
    limit=5
)

3. `pack_context`

Retrieves memories and formats them in UCMF (Ultra-Compact Memory Format) for system prompts.

Parameters:

context_keywords (list of strings): Keywords for semantic search
categories (list of strings, optional): Filter by categories
max_lines (int, optional): Maximum memory lines to include (default: 40)

Example:

pack_context(
    context_keywords=["user preferences"],
    max_lines=20
)

4. `get_memory_stats`

Returns statistics about the memory store.

Returns: JSON with total fact count, counts by type, and database path.

5. `optimize_memories`

Prunes low-confidence memories to keep the database clean.

Parameters:

aggressive (bool, optional): If True, removes memories with confidence < 0.3; otherwise < 0.1

Example:

optimize_memories(aggressive=False)

UCMF Format

Memories are stored in an Ultra-Compact Memory Format (UCMF) with the following fields:

id|t|who|what|why|whn|whr|tags|c

id: Unique identifier (hash)
t: Type (P=person, Proj=project, pref=preference, int=interest, rel=relationship, goal=goal, note=note, Σ=summary)
who: Person/entity associated with the memory
what: Description of the memory
why: Reasoning/importance
whn: When (timestamp in YYYYMMDD or YYYYMMDDTHHMM format, '-' if unknown)
whr: Where (location, '-' if unknown)
tags: Comma-separated tags
c: Confidence score (0.0 to 1.0)