xiaoheideplog/README.md

xiaoheideplog

Milvus + Azure OpenAI (text-embedding-3-small) project memory MCP server for Cursor. Transport: stdio or streamable-http (default in Docker on port 3101, path /mcp).

Design principles

1. Long-term memory without dumping the repo into the model — store summaries and decisions in Milvus; retrieve via MCP tools instead of pasting large files or logs into chat (token control).
2. Follow Milvus-style retrieval — new collections include a sparse BM25 field (via milvus-model MSMARCO stats) plus dense Azure embeddings; search uses hybrid_search + RRFRanker when that schema is present (multi-vector / hybrid search, reranking). Older collections without sparse_bm25 keep dense ANN only and add client-side RRF (dense order + lexical overlap) so accuracy does not rely on returning huge payloads.
3. Accuracy vs. payload size — tool defaults keep bodies small; ranking uses hybrid/RRF rather than “more text = better”. memory_semantic_search responses include retrieval_mode describing which path ran.

Environment: HYBRID_PREFETCH (default 96) controls the hybrid candidate pool before top_k.

Layout

• Data on disk: set DOCKER_VOLUME_DIRECTORY (default /mnt/redis-disk/xiaoheideplog/volumes) so etcd, MinIO, and Milvus use bind mounts under that path.
• Environment: see .env.example.

Run with Docker Compose

mkdir -p /mnt/redis-disk/xiaoheideplog/volumes/{etcd,minio,milvus}
cp .env.example .env
# edit .env — Azure endpoint and key
docker compose up -d --build

Point Cursor MCP at http://<host>:3101/mcp (HTTP transport).

Redis migration

Install with the migrate extra, with Milvus reachable and Azure env vars set (same as server):

pip install -e ".[migrate]"
export REDIS_URL=redis://127.0.0.1:6379/0
export MILVUS_HOST=127.0.0.1
export MILVUS_PORT=19530
# AZURE_OPENAI_* ...
xiaoheideplog-migrate-redis --dry-run
xiaoheideplog-migrate-redis

Cutover

After migration checks, stop the old cursor-project-memory container and keep using port 3101 for the new stack.

Post-migration cleanup (optional)

When Milvus is verified and the old Redis-backed MCP is no longer needed:

• Stop and remove old containers (cursor-memory-redis, cursor-project-memory, etc.).
• Remove the old Redis data directory on the host if it was only used for this feature.
• docker rmi unused images (for example cursor-project-memory:local, dedicated redis images). Use docker image prune carefully so unrelated images are not removed.