Project Memory MCP

Project Memory MCP is a small, local-first backend for semantic search over a software project's Markdown and text documentation. It indexes document chunks in Qdrant and exposes retrieval through a CLI and MCP tools. The server does not call an LLM; the MCP host uses the retrieved context to formulate its answer.

Architecture

HTTP, MCP, and CLI modules are thin entry adapters. The application services orchestrate document loading, chunking, embeddings, and vector storage through typed domain ports. Sentence Transformers and Qdrant remain isolated in infrastructure adapters.

Documentation
     ↓
Chunking
     ↓
Embeddings
     ↓
Qdrant
     ↑
MCP Search Tool
     ↑
AI Host

Markdown files are first split by their heading hierarchy and then by character count. Text files use character-based recursive splitting directly. Each chunk receives a stable SHA-256 ID and keeps its relative source path and Markdown section.

Related MCP server: Markdown RAG MCP

Requirements

• Python 3.12

• Docker with Docker Compose

Installation

Create and activate a virtual environment:

python -m venv .venv

Linux and macOS:

source .venv/bin/activate

Windows PowerShell:

.venv\Scripts\Activate.ps1

Install the direct runtime and development dependencies:

pip install -r requirements.txt

Copy the example configuration:

Linux and macOS:

cp .env.example .env

Windows PowerShell:

Copy-Item .env.example .env

Run Qdrant

docker compose up -d qdrant

Qdrant exposes HTTP on port 6333 and gRPC on port 6334. Its data is stored in the named qdrant_storage volume.

Index sample documentation

The first run downloads the configured Sentence Transformers model.

python -m scripts.index_docs --path ./docs_sample

The command reports discovered files, created chunks, indexed files, and skipped files. Re-indexing replaces points for each processed path without deleting the whole collection.

Search from the CLI

python -m scripts.search_docs "Where are JWT tokens validated?" --top-k 5

Each result includes its cosine score, relative path, Markdown section, stable chunk ID, and text.

Run FastAPI

uvicorn app.api.main:app --reload

The current HTTP surface intentionally contains only:

GET /health

Run the MCP server

Open the server with MCP Inspector:

mcp dev mcp_server.py

The root module exports an MCP Python SDK v2 MCPServer named Project Memory MCP and uses stdio safely: application logging is sent to stderr.

Available tools:

• search_project_docs(query, top_k=5) searches the current project's indexed documentation and returns structured chunks. top_k must be between 1 and 20.

• get_document(path) reads one UTF-8 .md or .txt document under DOCS_ROOT. Absolute paths, traversal outside that root, and unsupported file types are rejected.

Quality checks

pytest
ruff check .
docker compose config

Tests use fake embedding and vector-store implementations, so they do not need Qdrant or an embedding model download.

MVP limitations

• Only local .md and .txt files are supported.

• Indexing is synchronous and manually triggered.

• Search is vector-only; there is no BM25, hybrid search, or reranking.

• There is no LLM call, generated answer, RAG prompt, authentication, multi-tenancy, background worker, GitHub integration, or web UI.

• The FastAPI application exposes health status only.

Possible next steps

• Reranking

• GitHub webhook and incremental indexing from webhook events

• Retrieval evaluation

• Hybrid search

• LangGraph query retry