đŹđ§ 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 :
SearchAsyncexige un index FTS surcontent. 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 appelsSearchAsyncsuivants (aucune simulation locale). - Hybride : l'endpoint
queryn'exĂ©cute pas la fusion vectoriel+plein-texte en un appel ;HybridSearchAsyncĂ©met deux requĂȘtes serveur (classements_distanceet_scorecalculĂ©s cĂŽtĂ© serveur) puis fusionne localement les deux listes classĂ©es avecVectorWeight/FullTextWeightâ mĂȘme approche que les rerankers des SDK officiels LanceDB. - Scores : la similaritĂ© retournĂ©e vaut
1 â _distance, pertinente pour la mĂ©triquecosine(dĂ©faut) ; pourl2/dotl'Ă©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ĂȘtequerysupplĂ©mentaire) pour prĂ©server le contrat boolĂ©en.- Filtres mĂ©tadonnĂ©es :
sourcese traduit en Ă©galitĂ© SQL ;tag/tagsenLIKE '%âŠ%'sur le JSON des Ă©tiquettes ; une clĂ© personnalisĂ©e enLIKE '%"clĂ©":"valeur"%'surmetadata_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
EmbeddingDimensionprovoque uneInvalidOperationExceptionexplicite (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.
memoryetmemoryProvidersont mappĂ©s dansCrewConfiguration.Memory/.MemoryProvider, queCrewFactoryreporte sur l'agrĂ©gat de domaineCrew(Crew.MemoryEnabled,Crew.MemoryProvider), avec le nom de la crew (Crew.Name: lename:de sa configuration â fichier YAML, dossier de crew, crew.ork.tsâ ouCrewBuilder.Nameen C#).- 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). - Quand
MemoryServicematĂ©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'
IMemoryProviderde l'application, dont le type estMemory: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.
- le provider partagĂ© du type que la crew a dĂ©clarĂ©, demandĂ© Ă
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 avecSimpleExecutionContext.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 avecStoreResultInMemoryĂ 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_coworkerexĂ©cute le collĂšgue dans le contexte de la tĂąche qui dĂ©lĂšgue, dĂ©rivĂ© avecStoreResultInMemoryĂ 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
SearchSimilarAsyncdu provider, avec le filtrekindetcrew(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
RecallLimitsouvenirs 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 parAddOrkeonInfrastructure()) :RecallLimit5 souvenirs,MinScore0,6 (cosinus),MaxChars4 000 caractĂšres de contenu au total â le dernier souvenir qui ne tient pas est tronquĂ©, les suivants Ă©cartĂ©s.MinScoreest Ă 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 fixerMinScored'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 (
AgentBallotCollectorl'exécute avecSimpleExecutionContext.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Ă© parCompositeScorer: similaritĂ© sĂ©mantique 0,5 + rĂ©cence 0,3 + importance 0,2 par dĂ©faut (RecallOptions.SemanticWeight/RecencyWeight/ImportanceWeight, plusTopK10 etMinScore0,1) ; la rĂ©cence dĂ©croĂźt avec une demi-vie deRecencyHalfLifeHours;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.
RememberAsyncrange l'Ă©lĂ©ment une seule fois, dans cette mĂ©moire.RecallAsyncet 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Ă©.
ConsolidateAsynctrouve 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), plancherOrkeon:CrewMemory:MinCompositeScore(0,4 ; distinct deMinScore, le plancher cosinus du chemin vectoriel) etOrkeon: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), bornesRecallLimitetMaxCharsconservé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 avertissementmemory.analysis.degradedest journalisé. - La crew détient l'outil
memory_recall(query, limit), injectĂ© seulement avecmemory: trueet le service branchĂ© (distinct dememory_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