# 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

```bash
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

```yaml
# ~/.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`](.vscode/mcp.json.example) fourni dans ce repo) :

```json
{
  "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

```bash
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`](docs/RND_BRIEF.md).