Table of Contents

🇬🇧 English version

SystÚme de mémoire

Interface et types

IMemoryProvider (Orkeon.Domain.Memory) dĂ©finit le contrat avec sept mĂ©thodes : StoreAsync, GetAsync, SearchAsync (recherche textuelle), DeleteAsync, ClearAsync, StoreWithEmbeddingAsync et SearchSimilarAsync (recherche vectorielle par similaritĂ© cosinus). Les deux derniĂšres ont un corps par dĂ©faut dans l'interface (celui de SearchSimilarAsync ne renvoie rien) ; tous les providers du dĂ©pĂŽt dĂ©rivent donc de MemoryProviderBase (Orkeon.Infrastructure.Memory.Base), qui redĂ©clare SearchSimilarAsync abstraite — sans quoi un provider qui aurait oubliĂ© la recherche vectorielle renverrait silencieusement zĂ©ro rĂ©sultat via l'interface. La classe de base ajoute aussi UpdateAsync, CountAsync et ListKeysAsync. Il n'y a pas d'Ă©tape d'initialisation : un provider reçoit ses options dans son constructeur et ouvre sa connexion Ă©ventuelle Ă  son premier appel.

Filtre de métadonnées

SearchAsync(query, limit, filter, cancellationToken) et SearchSimilarAsync prennent le mĂȘme filter optionnel (Dictionary<string, object>) : source est une Ă©galitĂ© sur la source de l'entrĂ©e, tag/tags une appartenance Ă  ses Ă©tiquettes, et toute autre clĂ© une Ă©galitĂ© sur la propriĂ©tĂ© personnalisĂ©e de ce nom. Chaque provider l'applique avant sa limite — une recherche filtrĂ©e rend toutes les correspondances que le magasin contient, jusqu'Ă  la limite, jamais moins parce que des entrĂ©es que le filtre rejette auraient rempli la page :

Provider Comment le filtre est appliqué
In-Memory En mémoire, sur chaque entrée, avant la limite ; valeurs comparées sans tenir compte de la casse
Redis Sur chaque entrĂ©e du parcours de l'espace de clĂ©s, qui s'arrĂȘte Ă  la limite ; valeurs comparĂ©es sans tenir compte de la casse
SQLite Lignes correspondantes lues de la plus récente à la plus ancienne et vérifiées une à une jusqu'à la limite ; valeurs comparées sans tenir compte de la casse
ChromaDB La clause where de la requĂȘte (un $eq par clĂ©, sous un seul $and) — de la requĂȘte vectorielle, et du /get qui sert une recherche textuelle ; valeurs exactes
Pinecone Le filtre de mĂ©tadonnĂ©es de la requĂȘte vectorielle (un $eq par clĂ©) ; valeurs exactes. Pinecone n'a pas de recherche textuelle : son SearchAsync lĂšve NotSupportedException
LanceDB Le prĂ©dicat SQL de la requĂȘte, en prĂ©filtre ; une propriĂ©tĂ© personnalisĂ©e correspond par sa paire "clĂ©":"valeur" dans metadata_json (exacte, les jokers LIKE d'une valeur matchent largement)
EncryptedMemoryProviderDecorator Transmis au provider enveloppé : les métadonnées sont stockées en clair

ChromaDB et Pinecone gardent les propriĂ©tĂ©s personnalisĂ©es d'une entrĂ©e dans ses mĂ©tadonnĂ©es — dans la collection ou l'espace de noms par dĂ©faut comme dans les nommĂ©s — et les restituent Ă  la lecture : un filtre sur une propriĂ©tĂ© personnalisĂ©e la trouve.

Cinq types de mémoire sont définis par MemoryType (Orkeon.Domain.Memory) : ShortTerm (contexte immédiat), LongTerm (informations persistantes), Episodic (séquences d'événements), Entity (informations sur des entités spécifiques), Procedural (compétences apprises).

Capacités optionnelles

Au-delà du contrat de base, un provider adopte des interfaces de capacité (Orkeon.Domain.Memory) quand son backend les honore nativement :

Capacité Membres Implémentée par
IScoredVectorSearch SearchSimilarWithScoresAsync (clé + score par résultat) In-Memory, SQLite, ChromaDB, Pinecone, LanceDB
IBatchUpsert UpsertBatchAsync In-Memory, SQLite
IHybridSearchCapable HybridSearchAsync (vectoriel + plein texte dans le store) LanceDB
ICollectionAwareMemory store / upsert / recherche par collection, DeleteByFilterAsync, DropCollectionAsync ChromaDB (collections), Pinecone (namespaces), LanceDB (tables)

On les dĂ©couvre avec provider.TryGetCapability<TCapability>(out var capability) (MemoryCapabilityExtensions), pas avec un simple test is : un dĂ©corateur comme EncryptedMemoryProviderDecorator implĂ©mente statiquement toutes les capacitĂ©s et signale, via IMemoryCapabilityProbe, celles que son provider enveloppĂ© possĂšde rĂ©ellement. Les consommateurs se replient quand une capacitĂ© manque — le sous-systĂšme RAG, par exemple, utilise des clĂ©s prĂ©fixĂ©es (rag:{collection}:
) sur un provider sans ICollectionAwareMemory et sa fusion BM25 + RRF in-process sur un provider sans IHybridSearchCapable.

Implémentations

Provider Classe Caractéristiques
In-Memory InMemoryProvider ConcurrentDictionary, recherche vectorielle cosinus, développement/tests
Redis RedisMemoryProvider Clés préfixées orkeon:memory: par défaut, politique de retry Polly (ResiliencePolicies.GetRedisRetryPolicy), sérialisation JSON camelCase. Options RedisMemoryOptions (Orkeon:Redis : ConnectionString, défaut localhost:6379 ; KeyPrefix). La connexion s'ouvre au premier appel, une seule fois quel que soit le nombre d'appelants concurrents ; un serveur injoignable remonte en RedisConnectionException sur cet appel, et l'appel suivant réessaie
SQLite SqliteMemoryProvider Microsoft.Data.Sqlite, persistance locale (fichier ou :memory:, défaut Data Source=:memory:), embeddings en BLOB, recherche plein texte LIKE + recherche vectorielle cosinus (scan en mémoire), identifiants et métadonnées préservés à la relecture. Une Data Source fichier est un chemin virtuel résolu par le VFS et doit se trouver sur un montage accessible en écriture (ex. Data Source=/output/orkeon-memory.db), sinon le constructeur lÚve FileAccessDeniedException
ChromaDB ChromaDbMemoryProvider API REST v2 (routes tenant/database), base vectorielle. Un enregistrement s'ajoute avec son embedding seulement — StoreAsync refuse une entrĂ©e qui n'en a pas, avant toute requĂȘte. Une recherche textuelle (SearchAsync) est un /get des documents qui contiennent la requĂȘte (where_document $contains, sensible Ă  la casse comme le serveur la fait), dans le filtre ; une requĂȘte vide envoie le filtre seul. L'API HTTP n'a pas de requĂȘte textuelle : query_texts n'existe que dans les clients, qui calculent le vecteur eux-mĂȘmes
Pinecone PineconeMemoryProvider Base vectorielle cloud — en-tĂȘte Api-Key. Les requĂȘtes visent l'hĂŽte de l'index : Orkeon:Pinecone:Host s'il est renseignĂ©, sinon le host que Pinecone renvoie pour IndexName Ă  un unique appel describe_index (GET https://api.pinecone.io/indexes/{IndexName}) fait au premier usage. Un vecteur exige des valeurs : StoreAsync refuse une entrĂ©e sans embedding, avant toute requĂȘte. On cherche par vecteur (SearchSimilarAsync) : SearchAsync lĂšve NotSupportedException — il n'y a pas de recherche textuelle pour la servir
LanceDB LanceDbMemoryProvider Serveur distant LanceDB Cloud/Enterprise — REST + Arrow IPC, recherche vectorielle et plein-texte cĂŽtĂ© serveur

LanceDB (intégration distante réelle)

LanceDbMemoryProvider cible un serveur LanceDB Cloud / Enterprise via le protocole Lance REST Namespace (HttpClient brut, aucun SDK). Il n'y a pas de stockage local : les données et le scoring vivent sur le serveur.

Protocole

Opération provider Endpoint REST Payload
Premier appel (table auto-créée) POST /v1/table/{t}/exists, POST /v1/table/{t}/create, POST /v1/table/{t}/create_index (FTS) JSON / Arrow IPC stream
StoreAsync / UpdateAsync (upsert) POST /v1/table/{t}/merge_insert?on=id&when_matched_update_all=true&when_not_matched_insert_all=true Arrow IPC stream
GetAsync / ListKeysAsync POST /v1/table/{t}/query (filtre SQL / pagination k+offset) JSON → Arrow IPC file
SearchAsync (plein-texte BM25) POST /v1/table/{t}/query avec full_text_query JSON → Arrow IPC file
SearchSimilarAsync (vectoriel) POST /v1/table/{t}/query avec vector.single_vector + distance_type JSON → Arrow IPC file
DeleteAsync / ClearAsync POST /v1/table/{t}/delete (prédicat SQL) JSON
CountAsync POST /v1/table/{t}/count_rows JSON → entier brut

L'authentification utilise l'en-tĂȘte x-api-key (+ x-lancedb-database optionnel). Les payloads de donnĂ©es sont encodĂ©s/dĂ©codĂ©s en Arrow IPC via le paquet Apache.Arrow (Apache-2.0, cf. THIRD-PARTY-NOTICES.md). Le schĂ©ma de table est fixe : id, content, vector (FixedSizeList<float32>[dim]), importance, source, tags (JSON), created_at, metadata_json.

Configuration

{
  "Orkeon": {
    "LanceDb": {
      "Endpoint": "https://my-deployment.us-east-1.api.lancedb.com",
      "ApiKey": "
",
      "Database": "optionnel",
      "TableName": "orkeon_memories",
      "EmbeddingDimension": 1536,
      "DistanceType": "cosine",
      "CreateFullTextIndexOnInit": true
    }
  }
}

Autres clés : DefaultTopK (10), MinSimilarityScore (0), VectorWeight / FullTextWeight (poids de la fusion hybride, 0,7 / 0,3). Valeurs par défaut des clés montrées : TableName orkeon_memories, EmbeddingDimension 1536, DistanceType cosine, CreateFullTextIndexOnInit true.

Tout chemin qui sĂ©lectionne lancedb lit cette section (voir SĂ©lection par configuration). services.AddOrkeonLanceDb(configuration) expose en plus le LanceDbMemoryProvider partagĂ© par sa classe, avec LanceDbMigrationService ; l'extension ne rĂ©associe pas IMemoryProvider. Sans Endpoint, rĂ©soudre cette classe lĂšve InvalidOperationException, et sĂ©lectionner lancedb par type aussi — Memory:Provider et Orkeon:Rag:Provider refusent le dĂ©marrage de l'hĂŽte en nommant la clĂ©.

Limites connues

  • Plein-texte : SearchAsync exige un index FTS sur content. Le provider tente de le crĂ©er Ă  la crĂ©ation de la table (CreateFullTextIndexOnInit) ; si la crĂ©ation Ă©choue, un avertissement est journalisĂ© et l'erreur serveur est propagĂ©e telle quelle aux appels SearchAsync suivants (aucune simulation locale).
  • Hybride : l'endpoint query n'exĂ©cute pas la fusion vectoriel+plein-texte en un appel ; HybridSearchAsync Ă©met deux requĂȘtes serveur (classements _distance et _score calculĂ©s cĂŽtĂ© serveur) puis fusionne localement les deux listes classĂ©es avec VectorWeight/FullTextWeight — mĂȘme approche que les rerankers des SDK officiels LanceDB.
  • Scores : la similaritĂ© retournĂ©e vaut 1 − _distance, pertinente pour la mĂ©trique cosine (dĂ©faut) ; pour l2/dot l'Ă©chelle diffĂšre.
  • DeleteAsync/UpdateAsync : l'API delete renvoie une version de commit, pas un compteur — le provider vĂ©rifie d'abord l'existence de la clĂ© (1 requĂȘte query supplĂ©mentaire) pour prĂ©server le contrat boolĂ©en.
  • Filtres mĂ©tadonnĂ©es : source se traduit en Ă©galitĂ© SQL ; tag/tags en LIKE '%
%' sur le JSON des Ă©tiquettes ; une clĂ© personnalisĂ©e en LIKE '%"clĂ©":"valeur"%' sur metadata_json, la paire Ă©crite comme l'encodeur JSON du provider l'a Ă©crite — la clĂ© et la valeur entiĂšre, casse comprise. Les caractĂšres jokers SQL %/_ d'une valeur matchent encore largement.
  • Dimension fixe : un embedding dont la taille diffĂšre de EmbeddingDimension provoque une InvalidOperationException explicite (le schĂ©ma serveur est figĂ©).

ChromaDB — version supportĂ©e et configuration

ChromaDbMemoryProvider cible l'API REST v2 de ChromaDB (/api/v2/tenants/{tenant}/databases/{database}/collections/...), c'est-Ă -dire les serveurs ChromaDB ≄ 0.6.x, y compris la sĂ©rie 1.x. Le fournisseur ne parle que les routes v2 ; les serveurs qui ne servent que /api/v1 (≀ 0.5.x) ne sont donc pas supportĂ©s (les serveurs actuels rĂ©pondent 410 sur /api/v1).

Le tenant et la base de données ciblés sont configurables via ChromaDbOptions (section de configuration Orkeon:ChromaDb) et valent par défaut default_tenant/default_database, les valeurs créées d'office par un serveur ChromaDB mono-tenant. Un tenant ou une base non par défaut doit déjà exister sur le serveur (le provider ne les crée pas ; seule la collection est créée à la volée via get_or_create).

{
  "Orkeon": {
    "ChromaDb": {
      "BaseUrl": "http://localhost:8000",
      "Tenant": "default_tenant",
      "Database": "default_database",
      "CollectionName": "orkeon_memories",
      "DefaultTopK": 10
    }
  }
}

Le provider expose en outre HeartbeatAsync() qui sonde la vivacité du serveur via GET /api/v2/heartbeat et renvoie false (sans lever) si le serveur est injoignable ou répond en erreur.

Sélection par configuration

Une section par provider

L'hĂŽte configure chaque provider une fois, dans sa propre section ; tout le reste nomme un type :

Type Alias Section Clés
inmemory in-memory, vide — —
redis Orkeon:Redis ConnectionString (défaut localhost:6379, toute chaßne StackExchange.Redis), KeyPrefix (défaut orkeon:memory:)
sqlite Orkeon:Sqlite ConnectionString (défaut Data Source=:memory: ; une Data Source fichier est un chemin virtuel sur un montage inscriptible, ex. Data Source=/output/orkeon-memory.db), TableName (identifiant validé contre l'injection SQL), DefaultTopK, MinSimilarityScore
chromadb chroma Orkeon:ChromaDb BaseUrl (défaut http://localhost:8000), Tenant, Database, CollectionName, DefaultTopK
pinecone Orkeon:Pinecone ApiKey, IndexName (défaut orkeon-memories), Host (facultatif, voir le tableau plus haut), Namespace (défaut default)
lancedb lance Orkeon:LanceDb Endpoint (obligatoire : sans lui, le type est refusĂ© — au dĂ©marrage de l'hĂŽte pour Memory:Provider et Orkeon:Rag:Provider), ApiKey, TableName, Database, 
 (plus haut)
{
  "Memory": { "Provider": "redis" },
  "Orkeon": {
    "Redis": { "ConnectionString": "redis.internal:6379,password=
", "KeyPrefix": "team-a:" },
    "Sqlite": { "ConnectionString": "Data Source=/output/orkeon-memory.db" }
  }
}

Les secrets restent cÎté hÎte : un fichier de crew ne porte jamais de chaßne de connexion ni de clé d'API.

MemoryProviderFactory (port IMemoryProviderFactory, GetProvider(type), insensible Ă  la casse) distribue une instance par type : le provider de l'application, chaque crew qui nomme ce type et le store RAG de ce type la partagent — une connexion Redis, un client HTTP, une connexion SQLite. La factory possĂšde ces instances et les libĂšre avec le conteneur. CrĂ©er un provider ne connecte jamais ; la connexion s'ouvre Ă  son premier appel. Un type qu'elle ne sert pas est refusĂ© lĂ  oĂč il est atteint, en nommant les types connus ; SupportedTypes liste les alias. Memory:Provider et Orkeon:Rag:Provider sont jugĂ©s au dĂ©marrage de l'hĂŽte, avec ce que le fournisseur nommĂ© attend de sa section (Orkeon:LanceDb:Endpoint ; Orkeon:Pinecone:ApiKey et IndexName, ou Host), et le memoryProvider: d'une crew YAML Ă  son chargement.

Le provider de l'application

AddOrkeonInfrastructure() lie les cinq sections et enregistre IMemoryProviderFactory et le singleton IMemoryProvider, dont le type est Memory:Provider (absent → In-Memory). Memory:Provider ne porte que le type ; la connexion est la section du provider choisi. C'est aussi lĂ  que vit la mĂ©moire d'une crew nommĂ©e qui ne dĂ©clare aucun memoryProvider: (plus bas).

Extensions d'injection de dépendances

Extension Enregistre
AddOrkeonInfrastructure() Les cinq sections, IMemoryProviderFactory + le singleton IMemoryProvider ci-dessus
AddOrkeonRedisMemory(configuration) Lie Orkeon:Redis depuis configuration, expose le RedisMemoryProvider partagĂ© par sa classe et rĂ©associe IMemoryProvider Ă  lui — comme Memory:Provider = redis
AddOrkeonChromaDb(configuration) Lie Orkeon:ChromaDb et expose le ChromaDbMemoryProvider partagé par sa classe (client HTTP issu d'IHttpClientFactory). Appelée par AddOrkeonInfrastructure(configuration) quand la section existe
AddOrkeonPinecone(configuration) MĂȘme forme sur Orkeon:Pinecone (ApiKey, IndexName, Host, Namespace). Aussi appelĂ©e par AddOrkeonInfrastructure(configuration) quand la section existe
AddOrkeonLanceDb(configuration) MĂȘme forme sur Orkeon:LanceDb, plus LanceDbMigrationService (MigrateToLanceDbAsync, copie un provider existant dans la table LanceDB)
AddOrkeonMemoryMigration() MemoryMigrationService — MigrateAsync copie toutes les entrĂ©es d'un provider vers un autre. Non enregistrĂ©e par AddOrkeonInfrastructure() : l'appeler quand on dĂ©place un store (p. ex. In-Memory ou SQLite vers une base vectorielle), rĂ©soudre le service et lui passer les providers source et cible (deux instances de MemoryProviderBase — la source est parcourue clĂ© par clĂ©)

Seule AddOrkeonRedisMemory remplace l'IMemoryProvider de l'application ; les trois extensions de bases vectorielles rendent le provider partagé injectable par sa classe, à cÎté de celui que Memory:Provider a sélectionné.

La mémoire d'une crew : provider et portée

memory: dĂ©cide si une crew se souvient — memory: true en YAML, .memory(true) en .ork.ts, CrewBuilder.EnableMemory() en C# ; coupĂ©e par dĂ©faut dans les trois, comme chez CrewAI :

  • memory: true : la crew range le rĂ©sultat que chaque tĂąche garde, et rappelle ses souvenirs avant chaque tĂąche (plus bas).
  • memory: false, ou rien : rien n'est rangĂ©, rien n'est rappelĂ©, et aucun systĂšme de mĂ©moire n'est matĂ©rialisĂ© pour la crew.

memoryProvider: dit oĂč vit la mĂ©moire d'une crew, et exige memory: true : un provider nommĂ© pour une crew sans mĂ©moire est refusĂ© — au chargement (memoryProvider: 'sqlite' needs memory: true 
), et par Crew.Create(CrewCreateOptions) / CrewBuilder.Build() en C#, tous deux avec le remĂšde.

  1. memory et memoryProvider sont mappĂ©s dans CrewConfiguration.Memory / .MemoryProvider, que CrewFactory reporte sur l'agrĂ©gat de domaine Crew (Crew.MemoryEnabled, Crew.MemoryProvider), avec le nom de la crew (Crew.Name : le name: de sa configuration — fichier YAML, dossier de crew, crew .ork.ts — ou CrewBuilder.Name en C#).
  2. Au kickoff, l'orchestrateur enregistre les trois dans le singleton CrewMemoryProviderRegistry (Record(crewId, providerType, crewName, memoryEnabled) ; indexé par crew, donc les sélections ne fuient jamais d'une crew à l'autre ; IsMemoryEnabled(crewId) est ce que le run demande).
  3. Quand MemoryService matĂ©rialise le systĂšme de mĂ©moire de cette crew, il adosse sa mĂ©moire long terme (la mĂ©moire court terme reste une fenĂȘtre glissante in-process) Ă  :
    • le provider partagĂ© du type que la crew a dĂ©clarĂ©, demandĂ© Ă  MemoryProviderFactory — connectĂ© depuis la section de l'hĂŽte ; un type auquel aucun provider ne rĂ©pond est refusĂ© — celui d'une crew YAML Ă  son chargement, celui d'une crew C# (WithMemoryProvider) au premier usage de sa mĂ©moire ;
    • sinon, pour une crew nommĂ©e, le provider par dĂ©faut de l'hĂŽte — l'IMemoryProvider de l'application, dont le type est Memory:Provider (In-Memory s'il est absent) ;
    • sinon — une crew construite en C# sans nom — un magasin in-process Ă  elle, qui finit avec le run : sa portĂ©e serait un id qu'aucun run suivant ne porte, que nul ne relirait.

memoryProvider: est un type, rien de plus : memoryProvider: "Redis" se connecte avec Orkeon:Redis, "SQLite" avec Orkeon:Sqlite (une base :memory: in-process quand cette section est absente).

Ce que cela veut dire pour les hĂŽtes livrĂ©s : orkeon-host se souvient d'un message Ă  l'autre — son In-Memory vit avec le dĂ©mon —, tandis qu'orkeon run ne se souvient d'un processus Ă  l'autre qu'avec un provider durable : memoryProvider: sqlite (ou Redis, une base vectorielle), ou un Memory:Provider durable. Avec In-Memory, la mĂ©moire d'une crew vit en RAM, le temps du processus.

La portĂ©e est le nom de la crew. L'instance du provider est partagĂ©e — par toutes les crews de ce type, et par le magasin RAG de ce type : sans Orkeon:Rag:Provider, le magasin RAG est le provider ambiant, dont les fragments, manifestes et registres vivent dans le mĂȘme espace de clĂ©s. Chaque entrĂ©e que range la mĂ©moire long terme d'une crew porte deux propriĂ©tĂ©s personnalisĂ©es, kind = crew-memory et crew = <le nom de la crew> (CrewMemoryScope : Stamp(item, scope), Filter(scope)), et chaque recherche dans cette mĂ©moire les demande toutes deux au provider (filtre de mĂ©tadonnĂ©es, appliquĂ© avant la limite). Une crew lit donc ce qu'elle a rangĂ©, dans ce run et dans les runs prĂ©cĂ©dents d'une crew de ce nom — c'est ce qui rend la mĂ©moire durable — et jamais les entrĂ©es d'une autre crew, ni un fragment RAG. Une crew sans nom (construite en C# sans CrewBuilder.Name) a pour portĂ©e son id : sa mĂ©moire dure un run. Deux crews d'un mĂȘme nom partagent leur mĂ©moire — avec In-Memory, Redis et SQLite, deux noms qui ne diffĂšrent que par la casse aussi. MemoryCoordinator Ă©tiquette en outre chaque souvenir qu'il range crew:<nom> (l'id de la crew quand elle n'a pas de nom).

Vider la mĂ©moire d'une crew (IMemoryService.ClearMemoryAsync) supprime les entrĂ©es que ce systĂšme de mĂ©moire a rangĂ©es — celles du run en cours —, jamais le reste du magasin partagĂ©, et la libĂ©rer ne libĂšre jamais le provider partagĂ©. Il n'y a pas de rĂ©tention : la mĂ©moire d'une crew croĂźt d'une entrĂ©e par tĂąche rĂ©ussie, run aprĂšs run, et aucun verbe ne la remet Ă  zĂ©ro.

Ce qui est rangĂ©. AprĂšs chaque tĂąche rĂ©ussie, sa sortie — exactement la sortie de la tĂąche, sous l'agent qui l'a Ă©crite (IMemoryCoordinator.StoreTaskResultAsync) —, plongĂ©e sur sa tĂąche (la description, avec les variables du run) et le dĂ©but de sa sortie (1 000 caractĂšres), avec les propriĂ©tĂ©s personnalisĂ©es agent_id, agent_role, task_id, task_description et stored_at. Seulement ce qu'une tĂąche garde :

  • en mode Consensual, la rĂ©ponse retenue par le vote : les rĂ©ponses candidates et les bulletins s'exĂ©cutent avec SimpleExecutionContext.StoreResultInMemory Ă  faux, et la stratĂ©gie range la rĂ©ponse retenue une fois, sous l'agent qui l'a Ă©crite (Types de processus) ;
  • en mode Hierarchical, la sortie que le manager a acceptĂ©e : chaque essai s'exĂ©cute avec StoreResultInMemory Ă  faux, et la stratĂ©gie range l'acceptĂ©e une fois, sous l'agent assignĂ© — rien quand le manager rejette les trois essais, ni quand le travailleur Ă©choue (Types de processus) ;
  • en mode Autonomous, la sortie d'un pair qui a repris une tĂąche Ă©chouĂ©e : il s'exĂ©cute dans le contexte de la tentative Ă©chouĂ©e, dĂ©rivĂ© d'elle sous l'id de la crew, et sa sortie, quand elle rĂ©ussit, est le rĂ©sultat de la tĂąche — rangĂ©e une fois, sous le pair (Autonomous) ;
  • jamais la sous-rĂ©ponse d'un collĂšgue : delegate_work_to_coworker exĂ©cute le collĂšgue dans le contexte de la tĂąche qui dĂ©lĂšgue, dĂ©rivĂ© avec StoreResultInMemory Ă  faux — mĂȘme crew, mĂȘme portĂ©e, rĂ©glages du parent ;
  • jamais un bulletin, jamais un essai de forge (Forge).

Ce que rappelle une crew

Avant chaque tĂąche, AgentExecutionService demande Ă  IMemoryCoordinator.RecallAsync les souvenirs de la crew les plus proches de la tĂąche, et le prompt utilisateur les porte :

  • La requĂȘte est la tĂąche telle que la recherche de connaissance la voit : sa description et sa sortie attendue, avec les variables du run. Un souvenir est plongĂ© sur sa propre tĂąche et sa sortie : la mĂȘme tĂąche d'un run prĂ©cĂ©dent remonte ainsi en tĂȘte.
  • La recherche est vectorielle, dans la portĂ©e de la crew : le SearchSimilarAsync du provider, avec le filtre kind et crew (sur le magasin in-process d'une crew sans nom, un cosinus calculĂ© en processus).
  • Ce qui est Ă©cartĂ© : un souvenir Ă©gal Ă  l'une des sorties que le prompt porte dĂ©jĂ  de ce run. Le rappel demande autant de rĂ©sultats de plus qu'il y a de sorties prĂ©cĂ©dentes, et rend donc tout de mĂȘme RecallLimit souvenirs quand la crew en a autant d'autres ; un contenu rappelĂ© deux fois est gardĂ© une fois.
  • Les bornes viennent de la section Orkeon:CrewMemory (CrewMemoryOptions, liĂ©e par AddOrkeonInfrastructure()) : RecallLimit 5 souvenirs, MinScore 0,6 (cosinus), MaxChars 4 000 caractĂšres de contenu au total — le dernier souvenir qui ne tient pas est tronquĂ©, les suivants Ă©cartĂ©s. MinScore est Ă  l'Ă©chelle de l'embedder ; 0,6 a Ă©tĂ© mesurĂ© sur le modĂšle local (BGE-micro-v2), oĂč la mĂȘme tĂąche d'un run prĂ©cĂ©dent obtient 0,72 et plus, une tĂąche anglaise sans rapport 0,53 et moins, et un travail voisin entre les deux (de 0,59 Ă  0,72). La requĂȘte porte les variables du run : une longue entrĂ©e qui partage le sujet du souvenir a portĂ© une tĂąche sans rapport Ă  0,61. Ce modĂšle lit l'anglais : un texte français obtient un score Ă©levĂ© quoi qu'il dise (0,67 pour une paire sans rapport). Les providers distants (mistral-embed, un dĂ©ploiement Azure OpenAI, gemini-embedding-001) n'ont pas encore de mesure : garder 0,6 comme point de dĂ©part et fixer MinScore d'aprĂšs une passe sur vos propres donnĂ©es. Un autre embedder demande sa propre mesure.
  • Le format : une section du prompt utilisateur, aprĂšs les rĂ©sultats des tĂąches prĂ©cĂ©dentes et avant la connaissance rĂ©cupĂ©rĂ©e — l'en-tĂȘte From this crew's memory — earlier work, possibly outdated; use it only where it helps:, puis pour chaque souvenir une ligne --- 2026-09-30 · Analyst · Summarize the weekly news --- (sa date, le rĂŽle de l'agent, la tĂąche tronquĂ©e Ă  80 caractĂšres) suivie de son contenu. Le Guardian la filtre avec le reste du prompt (phase d'entrĂ©e).
  • Qui rappelle : toute exĂ©cution qui rĂ©pond Ă  une tĂąche — une candidate du consensuel, un essai du hiĂ©rarchique, un pair autonome qui reprend une tĂąche —, et un collĂšgue quand la tĂąche qui lui dĂ©lĂšgue rappelle, mais pas un bulletin (AgentBallotCollector l'exĂ©cute avec SimpleExecutionContext.RecallFromMemory Ă  faux).

Une crew relancĂ©e sans ĂȘtre rechargĂ©e — la boucle KickoffAsync en C#, le CrewAgent Ă  crew fixe — retrouve ses tours prĂ©cĂ©dents de la mĂȘme façon : n'est Ă©cartĂ© que ce que le prompt porte dĂ©jĂ .

Le kickoff en streaming (KickoffStreamingAsync) est le mĂȘme run que KickoffAsync : il rappelle et range la mĂ©moire d'une crew, et lit sa connaissance, de la mĂȘme façon.

L'embedder, et les échecs

Chaque souvenir est plongĂ© Ă  son rangement, et chaque rappel plonge sa requĂȘte, avec l'IEmbeddingProvider de l'hĂŽte — le port du RAG : le modĂšle local, qu'orkeon run et orkeon-host enregistrent par la section RaggableTree (RaggableTree:Enabled: false le retire) et le REPL toujours, sinon la section Orkeon:Embeddings. Pinecone et ChromaDB reçoivent donc le vecteur qu'ils exigent.

Une crew memory: true est vĂ©rifiĂ©e avant son premier appel LLM : l'orchestrateur appelle IMemoryCoordinator.EnsureReadyAsync, qui plonge un texte sonde puis cherche une fois dans la mĂ©moire de la crew. Un embedder absent, une clĂ© refusĂ©e, un magasin injoignable ou un vecteur de mauvaise dimension y fait Ă©chouer la crew, avec son nom et la cause dans son erreur. La dimension du magasin doit ĂȘtre celle de l'embedder : LanceDB est créé en 1 536 par dĂ©faut (Orkeon:LanceDb:EmbeddingDimension) quand le modĂšle local donne 384, et la dimension d'un index Pinecone est fixĂ©e Ă  sa crĂ©ation.

Pendant le run, une mémoire qui échoue est un avertissement, jamais une tùche en échec : un rangement ou un rappel qui lÚve est journalisé en Warning, avec la crew, la tùche, l'agent, le magasin et la cause ; la tùche garde sa sortie, et un rappel en échec la laisse sans souvenirs. Une annulation n'est jamais avalée. La rÚgle vit dans MemoryCoordinator, seul point d'entrée de la mémoire du run.

Les appels d'embedding ne sont pas comptés par le compteur de jetons (Limites connues).

Ce que le rappel ne fait pas

  • Pas de LLM dans le rappel : ni extraction de faits, ni rappel classĂ© par LLM, ni score composite rĂ©cence/importance (celui de CrewAI) : le rappel est vectoriel. La mĂ©moire cognitive est l'option C# qui analyse par LLM.

Chiffrement au repos

EncryptedMemoryProviderDecorator enveloppe n'importe quel IMemoryProvider (SQLite, Redis, In-Memory
) : le contenu est chiffrĂ© via IEncryptionProvider avant stockage et dĂ©chiffrĂ© Ă  la lecture. Les embeddings et les mĂ©tadonnĂ©es restent en clair (nĂ©cessaires Ă  l'indexation) ; la recherche vectorielle (SearchSimilarAsync) est dĂ©lĂ©guĂ©e au provider interne et le contenu des rĂ©sultats est dĂ©chiffrĂ© au retour. La recherche plein texte (SearchAsync) sur un store chiffrĂ© ne matche que le texte chiffrĂ© — utilisez la recherche vectorielle dans ce cas.

Le dĂ©corateur n'est jamais appliquĂ© automatiquement : l'hĂŽte enveloppe le provider qu'il veut protĂ©ger (new EncryptedMemoryProviderDecorator(inner, encryptionProvider, logger)), avec l'IEncryptionProvider AES-256-GCM enregistrĂ© par AddOrkeonInfrastructure() (Orkeon:Encryption). Rechiffrer un store existant sous une nouvelle clĂ© relĂšve de l'opt-in AddOrkeonKeyRotation() — voir Sous-systĂšmes opt-in.

Mémoire cognitive

Le sous-systĂšme cognitif (Orkeon.Infrastructure.Memory.Cognitive, opt-in AddOrkeonCognitiveMemory(configuration), branchĂ© par les exĂ©cuteurs sous Orkeon:CognitiveMemory:Enabled) superpose ICognitiveMemoryService — un IMemoryService enrichi de RememberAsync, RecallAsync, ConsolidateAsync, AnalyzeAsync et CheckContradictionsAsync — Ă  la mĂ©moire de la crew. Il requiert un fournisseur LLM (analyse, sur le profil que nomme Orkeon:CognitiveMemory:Profile) et un IEmbeddingProvider (chaque souvenir rangĂ©, chaque requĂȘte de rappel et chaque souvenir fusionnĂ© est plongĂ©). Ses types de rĂ©sultat vivent dans le Domain (CognitiveMemoryTypes.cs) :

  • MemoryAnalysis — importance notĂ©e par le LLM (0,0-1,0), catĂ©gorisation, extraction d'entitĂ©s (MemoryAnalyzer) ;
  • ContradictionCheck + ConflictResolution — dĂ©tection de conflits entre mĂ©moires (ContradictionDetector) ;
  • ScoredMemory — score de rappel composite calculĂ© par CompositeScorer : similaritĂ© sĂ©mantique 0,5 + rĂ©cence 0,3 + importance 0,2 par dĂ©faut (RecallOptions.SemanticWeight/RecencyWeight/ImportanceWeight, plus TopK 10 et MinScore 0,1) ; la rĂ©cence dĂ©croĂźt avec une demi-vie de RecencyHalfLifeHours ;
  • ConsolidationResult — consolidation, Ă©lagage et rĂ©solution de conflits (MemoryConsolidator).

Il travaille dans la mĂ©moire de la crew elle-mĂȘme : la mĂ©moire long terme qu'IMemoryService matĂ©rialise pour la crew — son provider dĂ©clarĂ©, sinon celui de l'hĂŽte pour une crew nommĂ©e, avec son nom pour portĂ©e (plus haut) ; un magasin in-process pour une crew sans nom. Une crew a ainsi une seule mĂ©moire : ce dont elle se souvient est estampillĂ© kind = crew-memory et crew = <portĂ©e> comme les souvenirs que rangent ses runs — ses runs le rappellent, et son rappel retrouve les leurs —, et ni la mĂ©moire d'une autre crew, ni un fragment RAG du mĂȘme magasin ne remontent jamais. La portĂ©e est celle que le kickoff de la crew a enregistrĂ©e : avant son premier kickoff, un id de crew est une crew sans nom.

  • RememberAsync range l'Ă©lĂ©ment une seule fois, dans cette mĂ©moire.
  • RecallAsync et les candidates de contradiction la cherchent par similaritĂ©, dans la portĂ©e.
  • Un conflit se rĂ©sout lĂ  d'oĂč viennent ses candidates : les souvenirs Ă  garder, retirer ou fusionner sont les candidates montrĂ©es au dĂ©tecteur, retirĂ©es de la mĂ©moire de la crew par la clĂ© qu'elle a rendue ; un souvenir fusionnĂ© y est plongĂ© puis rangĂ©.
  • ConsolidateAsync trouve les souvenirs de la crew par similaritĂ© dans la portĂ©e, sans seuil de score (jusqu'Ă  1 000 — ce que Pinecone rend Ă  une requĂȘte), les regroupe par cosinus, range chaque souvenir fusionnĂ© plongĂ© et retire ceux qu'il remplace, dans la mĂȘme mĂ©moire. Un souvenir qui revient sans son vecteur (ChromaDB n'en rend pas avec un rĂ©sultat de similaritĂ©) reste un groupe Ă  lui seul.

Dans un run

orkeon, orkeon-host et orkeon-repl branchent le service quand Orkeon:CognitiveMemory:Enabled vaut true (défaut false : l'analyse coûte des appels LLM, au compte de l'opérateur ; il n'y a pas de clé YAML pour cela). ICognitiveMemoryService est un singleton, résolvable depuis le fournisseur racine. Alors, pour une crew avec memory: true :

  • Le rappel passe par RecallAsync : souvenirs classĂ©s par score composite (similaritĂ©, rĂ©cence, importance), plancher Orkeon:CrewMemory:MinCompositeScore (0,4 ; distinct de MinScore, le plancher cosinus du chemin vectoriel) et Orkeon:CrewMemory:MinSemanticScore (0,5 : un souvenir frais d'importance par dĂ©faut atteint le plancher composite sur la seule rĂ©cence et la seule importance, la pertinence est donc exigĂ©e Ă  part), bornes RecallLimit et MaxChars conservĂ©es. Le composite de chaque souvenir rappelĂ© et ses trois composantes sont journalisĂ©s au niveau debug.
  • Le stockage passe par RememberAsync : la sortie est analysĂ©e (importance, catĂ©gorie), vĂ©rifiĂ©e contre les contradictions puis rangĂ©e. Quand l'analyse Ă©choue, le souvenir est rangĂ© avec l'importance par dĂ©faut et un avertissement memory.analysis.degraded est journalisĂ©.
  • La crew dĂ©tient l'outil memory_recall(query, limit), injectĂ© seulement avec memory: true et le service branchĂ© (distinct de memory_store, les notes typĂ©es de l'opĂ©rateur) ; il rĂ©pond avec les souvenirs de la crew de l'appel, sous les deux mĂȘmes planchers.
  • Orkeon:CrewMemory:ConsolidateOnRunEnd (false) consolide la mĂ©moire de la crew Ă  la fin d'un run, quel qu'en soit le rĂ©sultat (pas un run annulĂ©) ; une consolidation qui Ă©choue est un avertissement et ne remplace jamais le rĂ©sultat du run.
  • L'analyseur, le dĂ©tecteur de contradictions et le consolidateur appellent le LLM par le profil que nomme Orkeon:CognitiveMemory:Profile (le profil par dĂ©faut sinon) : leurs appels entrent donc dans le chemin mesurĂ© comme tout autre.

Sans le service, le chemin vectoriel est inchangé.

Options (Orkeon:CognitiveMemory, CognitiveMemoryOptions) : Enabled (false), Profile (null), EnableLlmAnalysis (true), EnableContradictionDetection (true), ContradictionCandidateCount (10), AnalysisModel (null = le modĂšle du provider), AnalysisTemperature (0,1), PruningThreshold (0,1), PruningMinAgeDays (30), RecencyHalfLifeHours (69), DefaultRecallOptions.


Voir aussi : Fournisseurs LLM · Sécurité · Référence de configuration · Retour à l'index