hkc-memory-server

ag1357/hkc-memory-server

3.2

If you are the rightful owner of hkc-memory-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

HKC Memory Server is a high-performance Model Context Protocol (MCP) server designed for managing persistent AI memory using hybrid search techniques.

Tools
5
Resources
0
Prompts
0

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:

  1. Set HKC_EMBED_MODEL_PATH environment variable to point to a local model directory
  2. 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:

  1. Initialize the SQLite database (memory_index.db)
  2. Create necessary directories (backups/, conversations/)
  3. Generate the UCMF legend file if not present
  4. 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)

Database Structure

The server creates and manages the following SQLite tables:

  • facts: Main memory storage (normalized structure)
  • ucmf: Compact UCMF format for each memory
  • facts_fts: Full-text search index (FTS5)
  • vectors: Semantic embedding vectors (384-dim)
  • meta: Server metadata and migration flags

Configuration

Environment Variables

  • HKC_EMBED_MODEL_PATH: Override the embedding model path
  • HF_HOME: Hugging Face cache directory
  • HF_HUB_OFFLINE: Set to "1" for offline mode (default in this server)
  • TRANSFORMERS_OFFLINE: Set to "1" for offline mode (default in this server)

Troubleshooting

"Model not found" Error

The embedding model hasn't been downloaded. Either:

  1. Run the pre-download command in the installation section
  2. Allow internet access on first run for automatic download
  3. Manually download and specify HKC_EMBED_MODEL_PATH

Database Lock Errors

The server uses WAL mode which should prevent most lock issues. If problems persist:

  1. Ensure no other processes are accessing memory_index.db
  2. Check file permissions
  3. Delete memory_index.db-wal and memory_index.db-shm files and restart

Memory/Performance Issues

  • The embedding model requires ~200MB RAM
  • Consider using optimize_memories() regularly to prune low-confidence entries
  • SQLite databases over 1GB may benefit from periodic VACUUM operations

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Submit a pull request with clear description of changes

License

[Add your chosen license here]

Acknowledgments