Stash — Mémoire Persistante pour Agents IA

Chaque conversation avec une IA part de zéro. Vous expliquez votre projet, vos préférences, votre contexte — et à la session suivante, vous devez tout réexpliquer. Cette amnésie n'est pas une fonctionnalité, c'est une limitation fondamentale des LLM.

Stash résout ce problème. C'est une couche de mémoire persistante open-source et auto-hébergée pour les agents IA. Considérez-la comme une infrastructure cognitive — les faits deviennent des relations, les relations deviennent des schémas, les schémas deviennent de la connaissance. Stash fonctionne comme un serveur MCP avec une consolidation en arrière-plan, offrant à tout agent compatible MCP un graphe de connaissances, des objectifs, un raisonnement causal et un auto-modèle qui persiste entre les sessions.

Dans ce tutoriel, vous découvrirez ce qu'est Stash, pourquoi il gagne en popularité, comment fonctionne son architecture, et comment le déployer en quelques minutes avec Docker Compose.

Pourquoi Stash Gagne en Popularité

L'écosystème des agents IA explose, mais la plupart des agents n'ont qu'une mémoire à court terme. Ils opèrent dans une seule fenêtre de contexte. Une fois cette fenêtre fermée, tout ce qui a été appris disparaît.

Stash comble cette lacune au bon moment. Le standard MCP (Model Context Protocol) permet désormais aux agents de se connecter à des outils externes, et Stash fournit le substrat de mémoire qui rend les agents véritablement utiles dans la durée. Avec plus de 700 étoiles GitHub en un mois, Stash a séduit les développeurs qui construisent des systèmes d'agents persistants, des assistants de codage aux compagnons IA personnels.

Raisons clés de son adoption rapide :

• Binaire unique en Go — pas de dépendances lourdes, empreinte réduite, déploiement facile
• Natif MCP — fonctionne avec tout agent compatible MCP (Claude Desktop, Cursor, Windsurf, Cline, Continue, OpenAI Agents)
• Pipeline de consolidation en 8 étapes — les observations brutes deviennent automatiquement des connaissances structurées
• Auto-hébergé avec Docker Compose — vos données restent sur votre infrastructure
• Indépendant du modèle — fonctionne avec OpenAI, OpenRouter, Ollama ou tout endpoint compatible OpenAI

Architecture

Stash utilise une architecture en couches avec trois niveaux principaux :

1. Couche Serveur MCP — Le serveur MCP basé sur SSE reçoit les épisodes (événements, observations, interactions) des agents connectés. Il expose une interface MCP standard que tout client compatible MCP peut utiliser.

2. Stockage de Mémoire — Postgres avec pgvector stocke les embeddings vectoriels des épisodes, faits, objectifs et relations. La couche d'embedding convertit le texte en représentations vectorielles via tout modèle d'embedding compatible OpenAI.

3. Pipeline de Consolidation (Brain) — Le pipeline en arrière-plan traverse 8 étapes : assemblage de contexte, extraction de faits, modélisation des relations (causales, contradictions, hypothèses), suivi des objectifs, analyse des schémas d'échec et atténuation de la confiance.

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Docker et Docker Compose installés
• Une clé API OpenAI (ou une clé OpenRouter avec des modèles compatibles)
• Un client compatible MCP (Claude Desktop, Cursor, Windsurf, etc.)

Installation et Configuration

Étape 1 : Cloner et Configurer

git clone https://github.com/alash3al/stash.git
cd stash
cp .env.example .env

Étape 2 : Modifier les Variables d'Environnement

Ouvrez .env et définissez vos identifiants API :

# Base de données (géré automatiquement par Docker Compose)
STASH_POSTGRES_DSN=postgres://stash:stash_dev_password@postgres:5432/stash?sslmode=disable

# Dimension vectorielle pour text-embedding-3-small
STASH_VECTOR_DIM=1536

# API OpenAI ou compatible
STASH_OPENAI_API_KEY=sk-votre-cle-api-ici
STASH_OPENAI_BASE_URL=https://api.openai.com/v1
STASH_EMBEDDING_MODEL=text-embedding-3-small
STASH_REASONER_MODEL=gpt-4o-mini

Avec OpenRouter :

STASH_OPENAI_BASE_URL=https://openrouter.ai/api/v1
STASH_EMBEDDING_MODEL=openai/text-embedding-3-small
STASH_REASONER_MODEL=openai/gpt-4o-mini

Ou avec Ollama (modèles locaux) :

STASH_OPENAI_BASE_URL=http://host.docker.internal:11434/v1
STASH_EMBEDDING_MODEL=nomic-embed-text
STASH_REASONER_MODEL=llama3.2

Étape 3 : Lancer avec Docker Compose

docker compose up -d

Cela démarre deux services :

• postgres — PostgreSQL avec pgvector pour le stockage
• stash — Le serveur MCP avec consolidation en arrière-plan

Attendez que les deux services soient en bonne santé :

docker compose ps
# Les deux doivent afficher "healthy"

Étape 4 : Connecter Votre Agent

Stash expose un serveur MCP via SSE à l'adresse http://localhost:8080/sse.

Claude Desktop — ajoutez à claude_desktop_config.json :

{
  "mcpServers": {
    "stash": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Cursor — ajoutez à ~/.cursor/mcp.json :

{
  "mcpServers": {
    "stash": {
      "url": "http://localhost:8080/sse"
    }
  }
}

OpenCode — ajoutez à ~/.config/opencode/config.json :

{
  "mcp": {
    "stash": {
      "type": "remote",
      "url": "http://localhost:8080/sse",
      "enabled": true
    }
  }
}

Une fois connecté, votre agent commence immédiatement à persister les épisodes. Chaque conversation, observation et interaction devient un souvenir que les sessions futures pourront rappeler.

Fonctionnement

Stash transforme les interactions brutes en connaissances structurées via un pipeline de consolidation en 8 étapes :

1. Assemblage de Contexte — Regroupe les épisodes connexes en fenêtres de contexte cohérentes
2. Extraction de Faits — Identifie les déclarations factuelles et les stocke avec des scores de confiance
3. Cartographie des Relations — Lie les faits entre eux (causes, contradictions, supports)
4. Suivi des Objectifs — Extrait les objectifs et suit leur progression entre les sessions
5. Modélisation Causale — Construit des chaînes cause-effet à partir des observations
6. Vérification d'Hypothèses — Teste les nouvelles observations contre les faits existants
7. Analyse des Schémas d'Échec — Identifie les modes d'échec récurrents
8. Atténuation de Confiance — Applique une dégradation temporelle aux souvenirs plus anciens

Chaque étape ne traite que les nouvelles données depuis la dernière exécution, rendant le pipeline efficace pour un fonctionnement continu.

Liste de Vérification

Après le déploiement, vérifiez que tout fonctionne :

• Le serveur MCP Stash est accessible : curl -s http://localhost:8080/sse doit retourner un flux
• Votre agent affiche Stash comme outil MCP connecté
• Après une conversation, les faits persistent entre les sessions (redémarrez et demandez "que sais-tu de moi ?")
• Vérifiez les logs de consolidation : docker compose logs stash | grep consolidation
• Postgres contient des données : docker compose exec postgres psql -U stash -c "SELECT COUNT(*) FROM episodes;"

Ressources

• GitHub : github.com/alash3al/stash
• Documentation : alash3al.github.io/stash
• Licence : Apache 2.0
• Auteur : Mohamed Al-Ashaal