---
version: 1.0.0
name: memoria
description: Se connecter à memoria — le CRM de gestion locative de l'agence — et y travailler : biens, candidatures, propriétaires, emails, journal, templates, mémoire d'agence. Guider l'humain pour ajouter le connecteur MCP https://app.memoria.immo/functions/v1/mcp (OAuth 2.1), vérifier la connexion, puis orchestrer les 31 tools memoria_*. À utiliser dès qu'il est question de memoria, d'un dossier locatif, d'une candidature, d'un bien à louer, d'un propriétaire, d'un bail, d'un mandat, d'une annonce, ou du pipeline de location de l'agence.
---

# memoria

**memoria est le CRM de gestion locative d'une agence immobilière** : un pipeline Kanban de candidatures, les biens et leurs mandats, les propriétaires, le journal des emails, les modèles de documents de l'agence et sa mémoire de travail. Chaque agence est un tenant isolé.

Ce fichier te donne deux choses : **comment brancher le connecteur** (§ Installation) et **comment travailler une fois branché** (§ Ce que memoria expose et suivantes). Il est autoportant — tu n'as besoin de rien d'autre pour être opérationnel.

**Serveur MCP** : `https://app.memoria.immo/functions/v1/mcp` — OAuth 2.1, un seul endpoint, 31 tools préfixés `memoria_`.

---

## D'abord : le connecteur est-il déjà là ?

Regarde ton catalogue d'outils. **Vois-tu des tools qui commencent par `memoria_`** (par exemple `memoria_board_snapshot`) ?

- **Oui** → l'installation est faite. Saute directement à « Vérifier que tout fonctionne », puis travaille.
- **Non** → continue ci-dessous.

Ne redéroule jamais l'installation quand les tools sont déjà présents.

---

## Prérequis : un compte memoria rattaché à une agence

memoria est un **produit fermé** : il n'y a pas d'inscription publique, pas de formulaire, pas d'essai gratuit. Les comptes sont créés manuellement et rattachés à une agence par l'équipe memoria.

**Tu ne peux pas créer de compte, et tu ne dois pas essayer.** Si l'humain n'a pas déjà des identifiants memoria, dis-le lui simplement et renvoie-le vers :

> **https://documentation.memoria.immo/agent-ia** — la marche à suivre pour obtenir un accès.

Sans compte rattaché, l'installation ci-dessous se terminera par une erreur `403` (« Compte non rattaché à une agence ») : autant le savoir avant de commencer.

---

## Installation (claude.ai, Claude Desktop)

**Tu n'as pas d'accès au shell dans ce contexte : tu ne peux rien installer toi-même.** Ton rôle est de guider l'humain, étape par étape, et d'attendre sa confirmation avant de passer à la suivante. Ne prétends jamais avoir configuré le connecteur.

Dicte-lui ceci :

1. **Ouvrir les réglages** → **Connecteurs** (« Connectors »).
2. **Ajouter un connecteur personnalisé** (« Add custom connector »).
3. Renseigner :
   - **Nom** : `memoria`
   - **URL** : `https://app.memoria.immo/functions/v1/mcp`
4. Valider. Le connecteur apparaît comme « non authentifié » — cliquer sur **Se connecter** / **Connect**.
5. Une page memoria s'ouvre : **se connecter avec ses identifiants d'agence**, puis, sur l'écran de consentement, **Autoriser**.
6. Revenir dans la conversation. Les tools `memoria_*` doivent maintenant apparaître.

Ce qu'il faut savoir pour bien accompagner :

- **Seul l'humain peut faire l'étape 5.** L'autorisation OAuth passe par un navigateur ; tu ne peux ni la simuler, ni la contourner, ni demander des identifiants ou un jeton. Ne demande jamais de mot de passe, de code, ni de coller une URL de callback.
- **Les connecteurs personnalisés dépendent du plan Claude.** Si l'humain ne trouve pas « Ajouter un connecteur personnalisé », c'est probablement que son offre ne le propose pas — c'est un sujet côté Claude, pas côté memoria.
- **Consentement refusé ou fenêtre fermée trop tôt** = le connecteur reste « non authentifié ». Il suffit de relancer « Se connecter » ; rien n'est cassé.
- **L'inscription n'existe pas** sur la page de connexion : si l'humain n'a pas de compte, retour au prérequis ci-dessus.

---

## Vérifier que tout fonctionne

Appelle **`memoria_board_snapshot`** — c'est une lecture, sans aucun effet de bord.

- **Ça répond** avec les colonnes du pipeline et leurs candidatures → c'est bon. Annonce à l'humain, en une ligne, ce que tu vois (par exemple : « connecté — 6 colonnes, 12 candidatures en cours »). Ne saute pas cette confirmation : sans elle, l'humain ne sait pas si l'installation a réellement abouti.
- **`401`** → le connecteur n'est pas (ou plus) authentifié : reprendre l'étape 4.
- **`403` « Compte non rattaché à une agence »** → le compte existe mais n'appartient à aucune agence. Personne ne peut débloquer ça depuis Claude : voir « Quand ça échoue ».

Tu ne verras jamais que les données de l'agence de l'humain : l'isolation est appliquée par le serveur, à chaque requête. Ce n'est pas à toi de la faire respecter — mais ne cherche jamais à la contourner.

---

## Ce que memoria expose — 31 tools

Tous préfixés `memoria_`, pour les distinguer de tes autres outils. **R** = lecture, **W** = écriture.

| Domaine | Lecture | Écriture |
|---|---|---|
| Pipeline (candidatures) | `memoria_board_snapshot` R, `memoria_candidatures_list` R, `memoria_candidature_get` R | `memoria_candidature_create` W, `memoria_candidature_update` W, `memoria_candidature_advance` W, `memoria_candidature_move_back` W, `memoria_candidature_reject` W, `memoria_candidature_restore` W |
| Personnes (candidats / garants) | `memoria_personnes_list` R | `memoria_personne_upsert` W, `memoria_candidature_personne_add` W, `memoria_candidature_personne_remove` W |
| Biens | `memoria_biens_list` R, `memoria_bien_get` R | `memoria_bien_create` W, `memoria_bien_update` W |
| Propriétaires | `memoria_proprietaires_list` R | `memoria_proprietaire_upsert` W |
| Mandats | (lecture via `memoria_bien_get.mandat`) | `memoria_mandat_register` W |
| Emails (journal) | `memoria_emails_list` R, `memoria_email_get` R | `memoria_email_log` W |
| Documents | `memoria_documents_list` R, `memoria_document_link` R | (aucune écriture — l'upload se fait dans l'application) |
| Annonces | (lecture via `memoria_bien_get.annonce_active`) | `memoria_annonce_save` W |
| Templates (modèles de l'agence) | `memoria_templates_list` R, `memoria_template_get` R | `memoria_template_upsert` W |
| Mémoire (savoir de l'agence) | `memoria_memoire_list` R | `memoria_memoire_upsert` W |

Les schémas de paramètres complets sont dans le catalogue d'outils que ton client a déjà chargé — lis-les avant d'appeler un tool d'écriture, ne les devine pas.

---

## Le modèle de données à connaître par cœur

- Une **candidature** est une carte du Kanban : le parcours d'un dossier sur un bien (colonne, statut, source, notes, motif de rejet).
- Une **personne** est une identité (nom, email, téléphone) réutilisable d'un dossier à l'autre. Une candidature est portée par **1..n personnes**, chacune avec un rôle (`candidat` ou `garant`), et il y a toujours **exactement un contact principal**, qui est un candidat.
- Conséquences pratiques :
  - l'identité se modifie via `memoria_personne_upsert` — **jamais** via `memoria_candidature_update`, qui ne touche que la source, les notes et le bien ;
  - la composition d'un dossier (colocation, garants, changement de contact principal) passe par `memoria_candidature_personne_add` / `memoria_candidature_personne_remove` ;
  - **avant de créer une personne, cherche-la** (`memoria_personnes_list`) et réutilise son `personne_id` — c'est l'anti-doublon.

Colonnes du pipeline, dans l'ordre : `prospection` « Contact reçu » → `visite` « Visite planifiée » → `dossier` « Dossier en cours » → `choix_proprietaire` « Choix propriétaire » → `candidat_retenu` « Retenu » → `installation` « Emménagement ».

---

## Règles de travail

**1. memoria est la source de vérité — n'invente jamais un état.** Si tu ne sais pas dans quelle colonne est un dossier, si un bien existe, ou ce qui a déjà été envoyé : va le lire. Aucune règle métier ne vit chez toi ; le serveur valide, dédoublonne et calcule.

**2. La mémoire d'agence d'abord.** Commence par `memoria_memoire_list` : l'agence y a rangé ses préférences durables (`consigne`, `apprentissage`) et ses amendements de comportement (`override`). Quand l'humain exprime une préférence **durable** (« désormais… », « toujours… »), propose de la mémoriser avec `memoria_memoire_upsert` — **après confirmation de sa part**. Jamais de données personnelles de candidats en mémoire : c'est du savoir agence.

**3. Le template avant la page blanche.** Avant de rédiger un document récurrent (email de dossier, courrier, bail, annonce), regarde les modèles de l'agence : `memoria_templates_list` puis `memoria_template_get`. Substitue **toutes** les variables `{{…}}` avec des données réelles lues dans memoria — jamais un `{{placeholder}}` dans le document remis. Une correction durable de l'humain se reporte dans le template (`memoria_template_upsert`), pas seulement dans la réponse du moment.

**4. Lis avant d'écrire — l'idempotence est portée par le serveur.** Beaucoup de tools d'écriture renvoient `already_exists: true` ou `changed: false` plutôt que de dupliquer : **c'est un succès, pas une erreur.** Ne relance jamais un tool non idempotent à l'aveugle ; vérifie d'abord l'état avec le `_list` ou le `_get` correspondant.

**5. Rejouer, c'est ré-émettre l'appel initial verbatim.** Pour les transitions du Kanban avec `expected_colonne`, un rejeu signifie renvoyer **exactement le même appel**, avec le même `expected_colonne` qu'à la première tentative. Changer ce paramètre pour refléter le nouvel état serait interprété comme une **nouvelle** action.

**6. Aucun envoi d'email automatique.** memoria journalise la correspondance, il ne l'envoie pas. `memoria_email_log` est un **journal** : il ne s'appelle qu'après un envoi ou une réception **réels**. Un brouillon jamais envoyé ne se journalise pas. L'identifiant d'idempotence du journal est l'identifiant du message côté messagerie — toujours la même source pour un même message, sinon l'idempotence casse.

**7. Les changements d'état se font sur demande explicite.** `memoria_candidature_advance`, `memoria_candidature_move_back`, `memoria_candidature_reject` déplacent un vrai dossier, que des humains regardent. Propose, puis attends l'accord — n'avance pas un dossier de ta propre initiative. Même prudence pour les écritures qui touchent un bien, un mandat ou un propriétaire.

---

## Aller plus loin : les playbooks memoria-*

Cinq skills complémentaires détaillent les procédures métier. Ils s'installent en téléchargeant le zip puis en l'important dans les **Capacités / Skills** de Claude. Ils supposent tous que le connecteur memoria est branché.

| Skill | À quoi ça sert | Prérequis en plus |
|---|---|---|
| [memoria-templates](https://app.memoria.immo/skills/memoria-templates.zip) | Utiliser et gérer la base de modèles de l'agence, onboarder ses documents existants | — |
| [memoria-memoire](https://app.memoria.immo/skills/memoria-memoire.zip) | Protocole complet de la mémoire d'agence : consultation, enregistrement, overrides, consolidation | — |
| [memoria-annonce](https://app.memoria.immo/skills/memoria-annonce.zip) | Rédiger et enregistrer l'annonce de location d'un bien (versionnée) | — |
| [memoria-import-bail-mandat](https://app.memoria.immo/skills/memoria-import-bail-mandat.zip) | Importer un PDF de bail ou de mandat : extraire les champs, écrire dans memoria | savoir lire un PDF |
| [memoria-email](https://app.memoria.immo/skills/memoria-email.zip) | Cycle complet des emails de dossier : lead entrant, brouillon sortant, journalisation, labels de suivi | **un connecteur Gmail** — sans lui, ce skill n'est pas utilisable tel quel |

Commence par `memoria-templates` et `memoria-memoire` : ce sont ceux qui servent dans presque toutes les tâches.

---

## Quand ça échoue

| Symptôme | Ce que ça veut dire | Quoi faire |
|---|---|---|
| `401` sur n'importe quel tool | Le connecteur n'a pas de jeton valide (jamais authentifié, ou session expirée) | Demander à l'humain de rouvrir Réglages → Connecteurs → memoria → **Se connecter**. Ne cherche pas de contournement. |
| `403` « Compte non rattaché à une agence » | Le compte existe mais n'a pas de rattachement | Ni toi ni l'humain ne peuvent le résoudre depuis Claude : voir **https://documentation.memoria.immo/agent-ia** |
| `validation_error` | Une donnée envoyée est refusée | Le message est en français et dit quoi corriger : corrige et relance. Ne tronque pas une valeur pour la faire passer sans le dire. |
| `not_found` | L'identifiant n'existe pas dans cette agence | Retrouve l'entité via le `_list` correspondant, ne fabrique jamais un id. |
| `duplicate` | L'entité existe déjà | En général une bonne nouvelle : récupère l'existante plutôt que d'en créer une autre. |
| `precondition_failed`, `invalid_transition` | L'état réel ne correspond pas à ce que tu supposais | Relis l'état (`_get`) et repars de là — surtout pour les transitions Kanban. |
| `dependency_blocked` | Une dépendance empêche l'opération | Le message dit laquelle : traite-la d'abord. |
| `storage_error` | Problème sur un fichier / une URL signée | Les URLs signées expirent (quelques minutes) : redemande-la plutôt que de réutiliser l'ancienne. |
| `already_exists: true`, `changed: false` | **Ce ne sont pas des erreurs** | Continue normalement, ne retente pas. |

Les messages d'erreur de memoria sont écrits en français, pour toi, et sont sûrs à relayer à l'humain tels quels. En cas de blocage persistant, dis-le franchement plutôt que d'improviser un contournement.

---

## Garder ce skill pour les prochaines sessions

Sans installation, il faut refetcher cette URL à chaque conversation. Deux façons de l'éviter :

- **Recommandé** — télécharger **https://app.memoria.immo/skills/memoria.zip** et l'importer dans les **Capacités / Skills** de Claude. Le skill se déclenchera alors tout seul dès qu'il sera question de memoria.
- Ou coller le contenu de ce fichier dans les instructions d'un Projet dédié à la gestion locative.

## Mettre à jour

Compare le champ `version:` de ta copie locale à celui de la version en ligne :

```
https://app.memoria.immo/SKILL.md
```

Si la version servie est plus récente, réimporte `memoria.zip` (le ré-import remplace le skill du même nom). Les playbooks `memoria-*` se mettent à jour de la même manière.