codebase-memory

Serveur MCP de mémoire de codebase : index sémantique + analyse "clean code", 100 % local, pensé pour être scalable à des machines modestes.

Ce que ça fait

• Indexation : découpe un dépôt en chunks (AST pour Python, structurel sinon), les plonge en embeddings (fastembed ONNX par défaut — CPU, portable ; backend llama.cpp GPU en option), et les stocke dans un SQLite unique (FTS5 + BLOBs).
• Recherche hybride : fusion RRF entre BM25 (FTS5) et cosinus sémantique.
• Analyse clean code : règles statiques (complexité cyclomatique, longueur, TODO, exceptions avalées, duplicats…) + revue LLM (Hermes 4 14B via llama.cpp, ou Gemma 2B via OpenVINO GenAI en fallback CPU léger).
• Mémoire de conventions : notes projet retrievables sémantiquement.

Démarrage rapide

cd D:\codebase-memory
uv sync                 # installe les dépendances
uv sync --extra openvino   # + fallback Gemma 2B OpenVINO
uv run codebase-memory index D:\mon\repo          # CLI
uv run python -m codebase_memory                  # serveur MCP (stdio)

Plug dans Hermes

# ~/.hermes/config.yaml (clé mcp_servers)
mcp_servers:
  codebase-memory:
    command: "D:\\codebase-memory\\.venv\\Scripts\\python.exe"
    args: ["-m", "codebase_memory"]
    env:
      CODEBASE_MEMORY_EMBED_BACKEND: "fastembed"
      CODEBASE_MEMORY_LLM_BACKEND: "openvino"
      CODEBASE_MEMORY_OV_MODEL_DIR: "D:\\gemma-2b-int4-ov"
    timeout: 300

Outils exposés : mcp_codebase_memory_index_codebase, search_code, analyze_code, remember_note, recall_notes, memory_status.

GitHub Copilot (VS Code)

Copilot Chat / Agent mode sait consommer des serveurs MCP. Dans le workspace que tu veux analyser, crée .vscode/mcp.json (copie de .vscode/mcp.json.example fourni dans ce repo) :

{
  "servers": {
    "codebase-memory": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "-m", "codebase_memory"],
      "cwd": "${workspaceFolder}/../codebase-memory"
    }
  }
}

• Ajuste cwd : chemin du clone de codebase-memory (ou clone-le dans le workspace).
• Recharge VS Code (Reload Window) puis accepte la connexion MCP quand Copilot le propose (onglet Copilot → section "MCP" pour vérifier que le serveur est vert).
• Indexe d'abord le code : uv run codebase-memory index "C:/chemin/de/ton/workspace".
• Ensuite, en Agent mode : "cherche où les patches WSI sont extraits", "analyse la qualité de ce fichier" → Copilot appelle mcp_codebase_memory_search_code / analyze_code.

Notes : les outils MCP ne sont utilisables que dans Chat / Agent mode (pas en complétion classique). JetBrains (2025.2+) sait aussi brancher des serveurs MCP pour Copilot (Settings → Tools → MCP Servers).

Installation sur une autre machine

git clone https://github.com/H-Gelender/codebase-memory
cd codebase-memory
uv sync                 # dépendances de base (fastembed ONNX, mcp, radon)
uv sync --extra openvino   # + fallback Gemma 2B OpenVINO (optionnel)
uv run codebase-memory index "C:/chemin/de/mon/repo"   # 1er run : télécharge bge-small (~130 Mo)
uv run codebase-memory search "comment X est implémenté"
uv run codebase-memory analyze "src/module.py"
uv run python -m codebase_memory     # serveur MCP (stdio) pour Hermes / Copilot

Windows + Smart App Control : si le python.exe du venv est bloqué (erreur 4551), base le venv sur un interpréteur déjà autorisé et remplace python.exe/pythonw.exe par des hardlinks (recette détaillée dans le skill Hermes hermes-agent → native-mcp.md).

Configuration par variables d'environnement (CODEBASE_MEMORY_*) : voir src/codebase_memory/config.py (backends embedding/LLM, chemins, seuils).

R&D

Hypothèses, design et résultats de benchmarks : docs/RND_BRIEF.md.