Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

fix: serialize Redis state mutations per key (#1568)

Rohit Ghumare062159c52f3f
diff --git a/README.md b/README.md
index 0e449c7e..38183721 100644
--- a/README.md
+++ b/README.md
@@ -1435,7 +1435,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin systems | `iii worker add <name>` |
-**232 source files · ~55,000 LOC · 3,300+ tests · 312 functions · 62 KV scopes**, all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.
+**230 source files · ~55,000 LOC · 3,300+ tests · 312 functions · 62 KV scopes**, all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.
---
diff --git a/READMEs/README.ar-SA.md b/READMEs/README.ar-SA.md
index a659b109..0d2c4855 100644
--- a/READMEs/README.ar-SA.md
+++ b/READMEs/README.ar-SA.md
@@ -1439,7 +1439,7 @@ fi
| Prometheus / Grafana | OTEL في iii + مراقب الحالة الصحية |
| أنظمة إضافات مخصصة | `iii worker add <name>` |
-**232 ملف مصدري · ~55,000 سطر برمجي · 3,300+ اختبار · 312 دالة · 62 نطاق KV**، كل ذلك على ثلاث بنى أساسية. لا يوجد أمر `agentmemory plugin install`. نظام الإضافات هو iii نفسه.
+**230 ملف مصدري · ~55,000 سطر برمجي · 3,300+ اختبار · 312 دالة · 62 نطاق KV**، كل ذلك على ثلاث بنى أساسية. لا يوجد أمر `agentmemory plugin install`. نظام الإضافات هو iii نفسه.
---
diff --git a/READMEs/README.bn-BD.md b/READMEs/README.bn-BD.md
index 7157c590..170027bb 100644
--- a/READMEs/README.bn-BD.md
+++ b/READMEs/README.bn-BD.md
@@ -1437,7 +1437,7 @@ fi
| Prometheus / Grafana | iii OTEL + হেলথ মনিটর |
| কাস্টম প্লাগইন সিস্টেম | `iii worker add <name>` |
-**232 সোর্স ফাইল · ~55,000 LOC · 3,300+ টেস্ট · 312 ফাংশন · 62 KV স্কোপ**, সবকিছু তিনটি প্রিমিটিভের উপর। কোনো `agentmemory plugin install` নেই। প্লাগইন সিস্টেমটাই iii নিজে।
+**230 সোর্স ফাইল · ~55,000 LOC · 3,300+ টেস্ট · 312 ফাংশন · 62 KV স্কোপ**, সবকিছু তিনটি প্রিমিটিভের উপর। কোনো `agentmemory plugin install` নেই। প্লাগইন সিস্টেমটাই iii নিজে।
---
diff --git a/READMEs/README.cs-CZ.md b/READMEs/README.cs-CZ.md
index 2009836a..2c674034 100644
--- a/READMEs/README.cs-CZ.md
+++ b/READMEs/README.cs-CZ.md
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Vlastní systémy pluginů | `iii worker add <name>` |
-**232 zdrojových souborů · ~55,000 řádků kódu · 3,300+ testů · 312 funkcí · 62 KV scopes**, vše na třech primitivech. Žádné `agentmemory plugin install`. Systém pluginů je samo iii.
+**230 zdrojových souborů · ~55,000 řádků kódu · 3,300+ testů · 312 funkcí · 62 KV scopes**, vše na třech primitivech. Žádné `agentmemory plugin install`. Systém pluginů je samo iii.
---
diff --git a/READMEs/README.da-DK.md b/READMEs/README.da-DK.md
index 803774ef..9035239a 100644
--- a/READMEs/README.da-DK.md
+++ b/READMEs/README.da-DK.md
@@ -1436,7 +1436,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin-systemer | `iii worker add <name>` |
-**232 kildefiler · ~55,000 LOC · 3,300+ tests · 312 funktioner · 62 KV-scopes**, alt på tre primitiver. Intet `agentmemory plugin install`. Plugin-systemet er iii selv.
+**230 kildefiler · ~55,000 LOC · 3,300+ tests · 312 funktioner · 62 KV-scopes**, alt på tre primitiver. Intet `agentmemory plugin install`. Plugin-systemet er iii selv.
---
diff --git a/READMEs/README.de-DE.md b/READMEs/README.de-DE.md
index 56028c04..19a2d1d6 100644
--- a/READMEs/README.de-DE.md
+++ b/READMEs/README.de-DE.md
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + Health-Monitor |
| Eigene Plugin-Systeme | `iii worker add <name>` |
-**232 Quelldateien · ~55,000 LOC · 3,300+ Tests · 312 Funktionen · 62 KV-Scopes**, alles auf drei Primitiven. Kein `agentmemory plugin install`. Das Plugin-System ist iii selbst.
+**230 Quelldateien · ~55,000 LOC · 3,300+ Tests · 312 Funktionen · 62 KV-Scopes**, alles auf drei Primitiven. Kein `agentmemory plugin install`. Das Plugin-System ist iii selbst.
---
diff --git a/READMEs/README.el-GR.md b/READMEs/README.el-GR.md
index 37c39a70..ae57444d 100644
--- a/READMEs/README.el-GR.md
+++ b/READMEs/README.el-GR.md
@@ -1438,7 +1438,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor υγείας |
| Προσαρμοσμένα συστήματα plugin | `iii worker add <name>` |
-**232 αρχεία πηγαίου κώδικα · ~55,000 LOC · 3,300+ δοκιμές · 312 functions · 62 KV scopes**, όλα πάνω σε τρία primitives. Δεν υπάρχει `agentmemory plugin install`. Το σύστημα plugin είναι το ίδιο το iii.
+**230 αρχεία πηγαίου κώδικα · ~55,000 LOC · 3,300+ δοκιμές · 312 functions · 62 KV scopes**, όλα πάνω σε τρία primitives. Δεν υπάρχει `agentmemory plugin install`. Το σύστημα plugin είναι το ίδιο το iii.
---
diff --git a/READMEs/README.es-ES.md b/READMEs/README.es-ES.md
index 59e996a8..a77a6fc1 100644
--- a/READMEs/README.es-ES.md
+++ b/READMEs/README.es-ES.md
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor de salud |
| Sistemas de plugins propios | `iii worker add <name>` |
-**232 ficheros de código · ~55,000 LOC · 3,300+ tests · 312 funciones · 62 scopes KV**, todo sobre tres primitivos. No hay `agentmemory plugin install`. El sistema de plugins es iii mismo.
+**230 ficheros de código · ~55,000 LOC · 3,300+ tests · 312 funciones · 62 scopes KV**, todo sobre tres primitivos. No hay `agentmemory plugin install`. El sistema de plugins es iii mismo.
---
diff --git a/READMEs/README.fi-FI.md b/READMEs/README.fi-FI.md
index 7c9445fd..e700bb37 100644
--- a/READMEs/README.fi-FI.md
+++ b/READMEs/README.fi-FI.md
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + terveysmonitori |
| Mukautetut plugin-järjestelmät | `iii worker add <name>` |
-**232 lähdetiedostoa · ~55,000 LOC · 3,300+ testiä · 312 funktiota · 62 KV-scopea**, kaikki kolmen primitiivin päällä. Ei `agentmemory plugin install` -komentoa. Plugin-järjestelmä on iii itse.
+**230 lähdetiedostoa · ~55,000 LOC · 3,300+ testiä · 312 funktiota · 62 KV-scopea**, kaikki kolmen primitiivin päällä. Ei `agentmemory plugin install` -komentoa. Plugin-järjestelmä on iii itse.
---
diff --git a/READMEs/README.fr-FR.md b/READMEs/README.fr-FR.md
index 3316bff2..289892fc 100644
--- a/READMEs/README.fr-FR.md
+++ b/READMEs/README.fr-FR.md
@@ -1448,7 +1448,7 @@ fi
| Prometheus / Grafana | iii OTEL + moniteur de santé |
| Systèmes de plugins custom | `iii worker add <name>` |
-**232 fichiers sources · ~55,000 LOC · 3,300+ tests · 312 fonctions · 62 scopes KV**, tout sur trois primitives. Pas de `agentmemory plugin install`. Le système de plugins, c'est iii lui-même.
+**230 fichiers sources · ~55,000 LOC · 3,300+ tests · 312 fonctions · 62 scopes KV**, tout sur trois primitives. Pas de `agentmemory plugin install`. Le système de plugins, c'est iii lui-même.
---
diff --git a/READMEs/README.he-IL.md b/READMEs/README.he-IL.md
index 850be463..0a0de75a 100644
--- a/READMEs/README.he-IL.md
+++ b/READMEs/README.he-IL.md
@@ -1439,7 +1439,7 @@ fi
| Prometheus / Grafana | iii OTEL + מוניטור health |
| מערכות plugin מותאמות אישית | `iii worker add <name>` |
-**232 קבצי מקור · ~55,000 LOC · 3,300+ בדיקות · 312 פונקציות · 62 תחומי KV**, הכול על שלושה primitives. אין `agentmemory plugin install`. מערכת ה-plugin היא iii עצמו.
+**230 קבצי מקור · ~55,000 LOC · 3,300+ בדיקות · 312 פונקציות · 62 תחומי KV**, הכול על שלושה primitives. אין `agentmemory plugin install`. מערכת ה-plugin היא iii עצמו.
---
diff --git a/READMEs/README.hi-IN.md b/READMEs/README.hi-IN.md
index 893c9e94..90eaabff 100644
--- a/READMEs/README.hi-IN.md
+++ b/READMEs/README.hi-IN.md
@@ -1449,7 +1449,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin systems | `iii worker add <name>` |
-**232 source files · ~55,000 LOC · 3,300+ tests · 312 functions · 62 KV scopes**, सब कुछ तीन primitives पर। कोई `agentmemory plugin install` नहीं। Plugin system iii स्वयं है।
+**230 source files · ~55,000 LOC · 3,300+ tests · 312 functions · 62 KV scopes**, सब कुछ तीन primitives पर। कोई `agentmemory plugin install` नहीं। Plugin system iii स्वयं है।
---
diff --git a/READMEs/README.hu-HU.md b/READMEs/README.hu-HU.md
index 50cfa084..bb3a7a05 100644
--- a/READMEs/README.hu-HU.md
+++ b/READMEs/README.hu-HU.md
@@ -1446,7 +1446,7 @@ A `/agentmemory/export` emellett elfogadja a `?maxSessions=`-t és a `?offset=`-
| Prometheus / Grafana | iii OTEL + egészségfigyelő |
| Egyéni plugin-rendszerek | `iii worker add <name>` |
-**232 forrásfájl · ~55,000 LOC · 3,300+ teszt · 312 funkció · 62 KV-hatókör**, mindez három primitíven. Nincs `agentmemory plugin install`. A plugin-rendszer maga az iii.
+**230 forrásfájl · ~55,000 LOC · 3,300+ teszt · 312 funkció · 62 KV-hatókör**, mindez három primitíven. Nincs `agentmemory plugin install`. A plugin-rendszer maga az iii.
---
diff --git a/READMEs/README.id-ID.md b/READMEs/README.id-ID.md
index ff5e4b8c..c76478fa 100644
--- a/READMEs/README.id-ID.md
+++ b/READMEs/README.id-ID.md
@@ -1447,7 +1447,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Sistem plugin custom | `iii worker add <name>` |
-**232 file sumber · ~55,000 LOC · 3,300+ pengujian · 312 fungsi · 62 scope KV**, semua di atas tiga primitif. Tidak ada `agentmemory plugin install`. Sistem plugin-nya adalah iii itu sendiri.
+**230 file sumber · ~55,000 LOC · 3,300+ pengujian · 312 fungsi · 62 scope KV**, semua di atas tiga primitif. Tidak ada `agentmemory plugin install`. Sistem plugin-nya adalah iii itu sendiri.
---
diff --git a/READMEs/README.it-IT.md b/READMEs/README.it-IT.md
index 69b95006..eb2426b4 100644
--- a/READMEs/README.it-IT.md
+++ b/READMEs/README.it-IT.md
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor di salute |
| Sistemi di plugin personalizzati | `iii worker add <name>` |
-**232 file sorgente · ~55,000 righe di codice · 3,300+ test · 312 funzioni · 62 scope KV**, tutto su tre primitive. Nessun `agentmemory plugin install`. Il sistema di plugin è iii stesso.
+**230 file sorgente · ~55,000 righe di codice · 3,300+ test · 312 funzioni · 62 scope KV**, tutto su tre primitive. Nessun `agentmemory plugin install`. Il sistema di plugin è iii stesso.
---
diff --git a/READMEs/README.ja-JP.md b/READMEs/README.ja-JP.md
index 17025d83..b3dbee41 100644
--- a/READMEs/README.ja-JP.md
+++ b/READMEs/README.ja-JP.md
@@ -1445,7 +1445,7 @@ fi
| Prometheus / Grafana | iii OTEL + ヘルスモニタ |
| カスタムプラグインシステム | `iii worker add <name>` |
-**232 ソースファイル · ~55,000 LOC · 3,300+ テスト · 312 functions · 62 KV スコープ** — すべて 3 つのプリミティブの上に。`agentmemory plugin install` はありません。プラグインシステムは iii そのものです。
+**230 ソースファイル · ~55,000 LOC · 3,300+ テスト · 312 functions · 62 KV スコープ** — すべて 3 つのプリミティブの上に。`agentmemory plugin install` はありません。プラグインシステムは iii そのものです。
---
diff --git a/READMEs/README.ko-KR.md b/READMEs/README.ko-KR.md
index bc43b221..472bfc63 100644
--- a/READMEs/README.ko-KR.md
+++ b/READMEs/README.ko-KR.md
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + health 모니터 |
| 커스텀 플러그인 시스템 | `iii worker add <name>` |
-**소스 파일 232개 · LOC ~55,000줄 · 테스트 3,300+개 · 함수 312개 · KV 스코프 62개**, 모두 세 가지 프리미티브 위에서 동작합니다. `agentmemory plugin install` 같은 것은 없습니다. 플러그인 시스템은 곧 iii 자체입니다.
+**소스 파일 230개 · LOC ~55,000줄 · 테스트 3,300+개 · 함수 312개 · KV 스코프 62개**, 모두 세 가지 프리미티브 위에서 동작합니다. `agentmemory plugin install` 같은 것은 없습니다. 플러그인 시스템은 곧 iii 자체입니다.
---
diff --git a/READMEs/README.nb-NO.md b/READMEs/README.nb-NO.md
index 9cd549c8..7ff308a4 100644
--- a/READMEs/README.nb-NO.md
+++ b/READMEs/README.nb-NO.md
@@ -1447,7 +1447,7 @@ fi
| Prometheus / Grafana | iii OTEL + helseovervåker |
| Egendefinerte plugin-systemer | `iii worker add <name>` |
-**232 kildefiler · ~55,000 LOC · 3,300+ tester · 312 funksjoner · 62 KV-scopes**, alt på tre primitiver. Ingen `agentmemory plugin install`. Plugin-systemet er iii selv.
+**230 kildefiler · ~55,000 LOC · 3,300+ tester · 312 funksjoner · 62 KV-scopes**, alt på tre primitiver. Ingen `agentmemory plugin install`. Plugin-systemet er iii selv.
---
diff --git a/READMEs/README.nl-NL.md b/READMEs/README.nl-NL.md
index 6a64e786..17956ec1 100644
--- a/READMEs/README.nl-NL.md
+++ b/READMEs/README.nl-NL.md
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin-systemen | `iii worker add <name>` |
-**232 bronbestanden · ~55,000 LOC · 3,300+ tests · 312 functies · 62 KV-scopes**, allemaal op drie primitieven. Geen `agentmemory plugin install`. Het pluginsysteem is iii zelf.
+**230 bronbestanden · ~55,000 LOC · 3,300+ tests · 312 functies · 62 KV-scopes**, allemaal op drie primitieven. Geen `agentmemory plugin install`. Het pluginsysteem is iii zelf.
---
diff --git a/READMEs/README.pl-PL.md b/READMEs/README.pl-PL.md
index 7845fa52..b14af39e 100644
--- a/READMEs/README.pl-PL.md
+++ b/READMEs/README.pl-PL.md
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor stanu |
| Niestandardowe systemy pluginów | `iii worker add <name>` |
-**232 plików źródłowych · ~55,000 LOC · 3,300+ testów · 312 funkcji · 62 zakresy KV**, wszystko na trzech prymitywach. Nie ma `agentmemory plugin install`. Systemem pluginów jest sam iii.
+**230 plików źródłowych · ~55,000 LOC · 3,300+ testów · 312 funkcji · 62 zakresy KV**, wszystko na trzech prymitywach. Nie ma `agentmemory plugin install`. Systemem pluginów jest sam iii.
---
diff --git a/READMEs/README.pt-BR.md b/READMEs/README.pt-BR.md
index 8f645853..b63aa3d0 100644
--- a/READMEs/README.pt-BR.md
+++ b/READMEs/README.pt-BR.md
@@ -1447,7 +1447,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor de saúde |
| Sistemas de plugin customizados | `iii worker add <name>` |
-**232 arquivos de código · ~55,000 LOC · 3,300+ testes · 312 funções · 62 escopos KV**, tudo em cima de três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
+**230 arquivos de código · ~55,000 LOC · 3,300+ testes · 312 funções · 62 escopos KV**, tudo em cima de três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
---
diff --git a/READMEs/README.pt-PT.md b/READMEs/README.pt-PT.md
index fffb16f0..8e74ba62 100644
--- a/READMEs/README.pt-PT.md
+++ b/READMEs/README.pt-PT.md
@@ -1446,7 +1446,7 @@ O `/agentmemory/export` também aceita `?maxSessions=` e `?offset=` para dividir
| Prometheus / Grafana | iii OTEL + monitor de saúde |
| Sistemas de plugins personalizados | `iii worker add <name>` |
-**232 ficheiros de código-fonte · ~55,000 LOC · 3,300+ testes · 312 funções · 62 âmbitos de KV**, tudo sobre três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
+**230 ficheiros de código-fonte · ~55,000 LOC · 3,300+ testes · 312 funções · 62 âmbitos de KV**, tudo sobre três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
---
diff --git a/READMEs/README.ro-RO.md b/READMEs/README.ro-RO.md
index 04968638..f79e9cdf 100644
--- a/READMEs/README.ro-RO.md
+++ b/READMEs/README.ro-RO.md
@@ -1430,7 +1430,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor de sănătate |
| Sisteme de plugin-uri personalizate | `iii worker add <name>` |
-**232 fișiere sursă · ~55,000 LOC · 3,300+ teste · 312 funcții · 62 de domenii KV**, toate pe trei primitive. Niciun `agentmemory plugin install`. Sistemul de plugin-uri este chiar iii.
+**230 fișiere sursă · ~55,000 LOC · 3,300+ teste · 312 funcții · 62 de domenii KV**, toate pe trei primitive. Niciun `agentmemory plugin install`. Sistemul de plugin-uri este chiar iii.
---
diff --git a/READMEs/README.ru-RU.md b/READMEs/README.ru-RU.md
index 3a5e2edc..a3e44316 100644
--- a/READMEs/README.ru-RU.md
+++ b/READMEs/README.ru-RU.md
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + монитор состояния |
| Самописные плагинные системы | `iii worker add <name>` |
-**232 исходных файлов · ~55,000 LOC · 3,300+ тестов · 312 функций · 62 KV-scope**, всё на трёх примитивах. Никакого `agentmemory plugin install`. Плагинная система — это сам iii.
+**230 исходных файлов · ~55,000 LOC · 3,300+ тестов · 312 функций · 62 KV-scope**, всё на трёх примитивах. Никакого `agentmemory plugin install`. Плагинная система — это сам iii.
---
diff --git a/READMEs/README.sv-SE.md b/READMEs/README.sv-SE.md
index 3de47dea..e3154061 100644
--- a/READMEs/README.sv-SE.md
+++ b/READMEs/README.sv-SE.md
@@ -1437,7 +1437,7 @@ fi
| Prometheus / Grafana | iii OTEL + hälsoövervakare |
| Anpassade pluginsystem | `iii worker add <name>` |
-**232 källkodsfiler · ~55,000 LOC · 3,300+ tester · 312 funktioner · 62 KV-scopes**, allt på tre primitiv. Inget `agentmemory plugin install`. Pluginsystemet är iii självt.
+**230 källkodsfiler · ~55,000 LOC · 3,300+ tester · 312 funktioner · 62 KV-scopes**, allt på tre primitiv. Inget `agentmemory plugin install`. Pluginsystemet är iii självt.
---
diff --git a/READMEs/README.th-TH.md b/READMEs/README.th-TH.md
index 305a9c36..f2acec87 100644
--- a/READMEs/README.th-TH.md
+++ b/READMEs/README.th-TH.md
@@ -1444,7 +1444,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin systems | `iii worker add <name>` |
-**232 source file · ~55,000 LOC · 3,300+ การทดสอบ · 312 function · 62 KV scope** ทั้งหมดอยู่บน primitive สามตัว ไม่มี `agentmemory plugin install` ระบบ plugin ก็คือ iii เองนั่นแหละ
+**230 source file · ~55,000 LOC · 3,300+ การทดสอบ · 312 function · 62 KV scope** ทั้งหมดอยู่บน primitive สามตัว ไม่มี `agentmemory plugin install` ระบบ plugin ก็คือ iii เองนั่นแหละ
---
diff --git a/READMEs/README.tl-PH.md b/READMEs/README.tl-PH.md
index aee04d7b..390c4c64 100644
--- a/READMEs/README.tl-PH.md
+++ b/READMEs/README.tl-PH.md
@@ -1446,7 +1446,7 @@ Tinatanggap din ng `/agentmemory/export` ang `?maxSessions=` at `?offset=` para
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom na plugin system | `iii worker add <name>` |
-**232 na source file · ~55,000 LOC · 3,300+ na test · 312 na function · 62 na KV scope**, lahat sa tatlong primitive. Walang `agentmemory plugin install`. Ang plugin system mismo ay ang iii.
+**230 na source file · ~55,000 LOC · 3,300+ na test · 312 na function · 62 na KV scope**, lahat sa tatlong primitive. Walang `agentmemory plugin install`. Ang plugin system mismo ay ang iii.
---
diff --git a/READMEs/README.tr-TR.md b/READMEs/README.tr-TR.md
index ba9d984d..cc43d8d9 100644
--- a/READMEs/README.tr-TR.md
+++ b/READMEs/README.tr-TR.md
@@ -1437,7 +1437,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom eklenti sistemleri | `iii worker add <name>` |
-**232 kaynak dosya · ~55,000 LOC · 3,300+ test · 312 fonksiyon · 62 KV scope**, hepsi üç primitif üzerinde. `agentmemory plugin install` yok. Eklenti sistemi, iii'nin kendisidir.
+**230 kaynak dosya · ~55,000 LOC · 3,300+ test · 312 fonksiyon · 62 KV scope**, hepsi üç primitif üzerinde. `agentmemory plugin install` yok. Eklenti sistemi, iii'nin kendisidir.
---
diff --git a/READMEs/README.uk-UA.md b/READMEs/README.uk-UA.md
index 587cc23e..d8013319 100644
--- a/READMEs/README.uk-UA.md
+++ b/READMEs/README.uk-UA.md
@@ -1447,7 +1447,7 @@ fi
| Prometheus / Grafana | iii OTEL + монітор стану здоров'я |
| Власні системи плагінів | `iii worker add <name>` |
-**232 вихідних файлів · ~55,000 LOC · 3,300+ тестів · 312 функцій · 62 KV-скоупів**, усе на трьох примітивах. Жодного `agentmemory plugin install`. Система плагінів — це сам iii.
+**230 вихідних файлів · ~55,000 LOC · 3,300+ тестів · 312 функцій · 62 KV-скоупів**, усе на трьох примітивах. Жодного `agentmemory plugin install`. Система плагінів — це сам iii.
---
diff --git a/READMEs/README.ur-PK.md b/READMEs/README.ur-PK.md
index 4199b7a4..6ef0c63c 100644
--- a/READMEs/README.ur-PK.md
+++ b/READMEs/README.ur-PK.md
@@ -1432,7 +1432,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| کسٹم plugin سسٹمز | `iii worker add <name>` |
-**232 سورس فائلز · ~55,000 لائنز کوڈ · 3,300+ ٹیسٹس · 312 فنکشنز · 62 KV اسکوپس**، سب تین primitives پر۔ کوئی `agentmemory plugin install` نہیں۔ plugin سسٹم خود iii ہی ہے۔
+**230 سورس فائلز · ~55,000 لائنز کوڈ · 3,300+ ٹیسٹس · 312 فنکشنز · 62 KV اسکوپس**، سب تین primitives پر۔ کوئی `agentmemory plugin install` نہیں۔ plugin سسٹم خود iii ہی ہے۔
---
diff --git a/READMEs/README.vi-VN.md b/READMEs/README.vi-VN.md
index 780ce1f0..c79cd17f 100644
--- a/READMEs/README.vi-VN.md
+++ b/READMEs/README.vi-VN.md
@@ -1437,7 +1437,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Hệ thống plugin tùy chỉnh | `iii worker add <name>` |
-**232 file source · ~55,000 LOC · 3,300+ test · 312 function · 62 KV scope**, tất cả trên ba primitive. Không có `agentmemory plugin install`. Hệ thống plugin chính là iii.
+**230 file source · ~55,000 LOC · 3,300+ test · 312 function · 62 KV scope**, tất cả trên ba primitive. Không có `agentmemory plugin install`. Hệ thống plugin chính là iii.
---
diff --git a/READMEs/README.zh-CN.md b/READMEs/README.zh-CN.md
index 78323988..8aedec90 100644
--- a/READMEs/README.zh-CN.md
+++ b/READMEs/README.zh-CN.md
@@ -1444,7 +1444,7 @@ fi
| Prometheus / Grafana | iii OTEL + 健康监控 |
| Custom plugin systems | `iii worker add <name>` |
-**232 个源文件 · ~55,000 行代码 · 3,300+ 个测试 · 312 个函数 · 62 个 KV 作用域**,全部基于三种原语。没有 `agentmemory plugin install`。插件系统就是 iii 本身。
+**230 个源文件 · ~55,000 行代码 · 3,300+ 个测试 · 312 个函数 · 62 个 KV 作用域**,全部基于三种原语。没有 `agentmemory plugin install`。插件系统就是 iii 本身。
---
diff --git a/READMEs/README.zh-TW.md b/READMEs/README.zh-TW.md
index 2d7b3969..6dd5ecc7 100644
--- a/READMEs/README.zh-TW.md
+++ b/READMEs/README.zh-TW.md
@@ -1430,7 +1430,7 @@ fi
| Prometheus / Grafana | iii OTEL + 健康監控 |
| 自訂外掛系統 | `iii worker add <name>` |
-**232 個原始檔 · ~55,000 行程式碼 · 3,300+ 測試 · 312 個函式 · 62 個 KV 範圍**,全部基於三種原語。沒有 `agentmemory plugin install`。外掛系統就是 iii 本身。
+**230 個原始檔 · ~55,000 行程式碼 · 3,300+ 測試 · 312 個函式 · 62 個 KV 範圍**,全部基於三種原語。沒有 `agentmemory plugin install`。外掛系統就是 iii 本身。
---
diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json
index a718cb68..c2b5a59e 100644
--- a/scripts/docs-sync.state.json
+++ b/scripts/docs-sync.state.json
@@ -26,7 +26,7 @@
"312"
],
"sourceFiles": [
- "232"
+ "230"
],
"loc": [
"55000"
diff --git a/src/state/kv.ts b/src/state/kv.ts
index f31e591e..fe6b7e6c 100644
--- a/src/state/kv.ts
+++ b/src/state/kv.ts
@@ -122,71 +122,62 @@ export class StateKV {
})
}
- async set<T = unknown>(scope: string, key: string, value: T): Promise<T> {
+ private async mutate<T>(
+ scope: string,
+ key: string,
+ operation: (resolvedScope: string) => Promise<T>,
+ ): Promise<T> {
scope = await resolveGraphScope(this, scope)
await ensureGraphConsistency(this, scope)
- noteGraphSnapshotWrite(this, scope, key)
- let result: T
- try {
- result = await this.sdk.trigger<{ scope: string; key: string; value: T }, T>({
- function_id: 'state::set',
- payload: { scope, key, value },
- })
- } finally {
+ const write = async () => {
noteGraphSnapshotWrite(this, scope, key)
+ try {
+ return await operation(scope)
+ } finally {
+ noteGraphSnapshotWrite(this, scope, key)
+ }
}
+ const result = this.backend === 'redis'
+ ? await withKeyedLock(`state-update:${scope}\u0000${key}`, write)
+ : await write()
await notifyGraphGenerationChange(this, scope, key)
return result
}
+ async set<T = unknown>(scope: string, key: string, value: T): Promise<T> {
+ return this.mutate(scope, key, (resolvedScope) =>
+ this.sdk.trigger<{ scope: string; key: string; value: T }, T>({
+ function_id: 'state::set',
+ payload: { scope: resolvedScope, key, value },
+ }),
+ )
+ }
+
async update<T = unknown>(scope: string, key: string, ops: UpdateOp[]): Promise<T> {
- scope = await resolveGraphScope(this, scope)
- await ensureGraphConsistency(this, scope)
- noteGraphSnapshotWrite(this, scope, key)
- if (this.backend === 'redis' && canApplyLocally(ops)) {
- return withKeyedLock(`state-update:${scope}\u0000${key}`, async () => {
- // Keep both halves on the scope resolved before acquiring the lock.
- let result: UpdateResult
- try {
- const oldValue = await this.sdk.trigger<{ scope: string; key: string }, unknown>({
- function_id: 'state::get', payload: { scope, key },
- })
- const newValue = applyUpdateOps(oldValue, ops)
- await this.sdk.trigger({ function_id: 'state::set', payload: { scope, key, value: newValue } })
- result = { old_value: oldValue, new_value: newValue, errors: [] }
- } finally {
- noteGraphSnapshotWrite(this, scope, key)
- }
- await notifyGraphGenerationChange(this, scope, key)
+ return this.mutate(scope, key, async (resolvedScope) => {
+ if (this.backend === 'redis' && canApplyLocally(ops)) {
+ const oldValue = await this.sdk.trigger<{ scope: string; key: string }, unknown>({
+ function_id: 'state::get', payload: { scope: resolvedScope, key },
+ })
+ const newValue = applyUpdateOps(oldValue, ops)
+ await this.sdk.trigger({ function_id: 'state::set', payload: { scope: resolvedScope, key, value: newValue } })
+ const result: UpdateResult = { old_value: oldValue, new_value: newValue, errors: [] }
return result as T
- })
- }
- let result: T
- try {
- result = await this.sdk.trigger<{ scope: string; key: string; ops: UpdateOp[] }, T>({
+ }
+ return this.sdk.trigger<{ scope: string; key: string; ops: UpdateOp[] }, T>({
function_id: 'state::update',
- payload: { scope, key, ops },
+ payload: { scope: resolvedScope, key, ops },
})
- } finally {
- noteGraphSnapshotWrite(this, scope, key)
- }
- await notifyGraphGenerationChange(this, scope, key)
- return result
+ })
}
async delete(scope: string, key: string): Promise<void> {
- scope = await resolveGraphScope(this, scope)
- await ensureGraphConsistency(this, scope)
- noteGraphSnapshotWrite(this, scope, key)
- try {
+ await this.mutate(scope, key, async (resolvedScope) => {
await this.sdk.trigger<{ scope: string; key: string }, void>({
function_id: 'state::delete',
- payload: { scope, key },
+ payload: { scope: resolvedScope, key },
})
- } finally {
- noteGraphSnapshotWrite(this, scope, key)
- }
- await notifyGraphGenerationChange(this, scope, key)
+ })
}
async list<T = unknown>(scope: string): Promise<T[]> {
diff --git a/test/state-mutation-order.test.ts b/test/state-mutation-order.test.ts
new file mode 100644
index 00000000..0f3b58ad
--- /dev/null
+++ b/test/state-mutation-order.test.ts
@@ -0,0 +1,236 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { StateKV, applyUpdateOps, type StateBackend } from "../src/state/kv.js";
+import { pinGraphState, setGraphGenerationListener } from "../src/state/graph-generation.js";
+import { KV } from "../src/state/schema.js";
+
+type Op = { type: string; path: string; value?: unknown };
+type Request = { function_id: string; payload: { scope: string; key: string; value?: unknown; ops?: Op[] } };
+type UpdateResult = { old_value: unknown; new_value: unknown; errors: unknown[] };
+
+function deferred() {
+ let resolve!: () => void;
+ const promise = new Promise<void>((done) => { resolve = done; });
+ return { promise, resolve };
+}
+
+function nextTurn() {
+ return new Promise<void>((resolve) => setImmediate(resolve));
+}
+
+function setup(backend: StateBackend = "redis") {
+ const rows = new Map<string, Map<string, unknown>>();
+ const read = (scope: string, key: string) => structuredClone(rows.get(scope)?.get(key) ?? null);
+ const write = (scope: string, key: string, value: unknown) => {
+ if (!rows.has(scope)) rows.set(scope, new Map());
+ rows.get(scope)!.set(key, structuredClone(value));
+ };
+ let gate: {
+ functionId: string; scope: string; key: string; after: boolean; error?: string;
+ entered: ReturnType<typeof deferred>; released: ReturnType<typeof deferred>;
+ } | undefined;
+ const sdk = {
+ trigger: vi.fn(async (request: Request) => {
+ const { function_id: id, payload: p } = request;
+ const active = gate?.functionId === id && gate.scope === p.scope && gate.key === p.key ? gate : undefined;
+ if (active) gate = undefined;
+ const wait = async () => {
+ active!.entered.resolve();
+ await active!.released.promise;
+ if (active!.error) throw new Error(active!.error);
+ };
+ if (active && !active.after) await wait();
+ const old = read(p.scope, p.key);
+ let result: unknown;
+ if (id === "state::get") result = old;
+ else if (id === "state::set") {
+ write(p.scope, p.key, p.value);
+ result = { old_value: old, new_value: p.value };
+ } else if (id === "state::delete") {
+ rows.get(p.scope)?.delete(p.key);
+ result = old;
+ } else if (id === "state::update") {
+ let next = old;
+ for (const op of p.ops ?? []) {
+ if (op.type === "increment") {
+ const current = (next ?? {}) as Record<string, unknown>;
+ next = { ...current, [op.path]: Number(current[op.path] ?? 0) + Number(op.value) };
+ } else next = applyUpdateOps(next, [op]);
+ }
+ write(p.scope, p.key, next);
+ result = { old_value: old, new_value: next, errors: [] };
+ } else throw new Error(`Unexpected state request: ${id}`);
+ if (active?.after) await wait();
+ return result;
+ }),
+ };
+ const kv = new StateKV(sdk as never, { backend });
+ function pause(functionId: string, scope: string, key: string, options: { after?: boolean; error?: string } = {}) {
+ const entered = deferred();
+ const released = deferred();
+ gate = { functionId, scope, key, after: options.after ?? false, error: options.error, entered, released };
+ return { entered: entered.promise, release: released.resolve };
+ }
+ return { kv, sdk, read, pause };
+}
+
+afterEach(() => setGraphGenerationListener(null));
+
+describe("Redis StateKV mutation ordering", () => {
+ it.each(["set", "delete"] as const)("keeps a later %s after an in-flight local update", async (operation) => {
+ const { kv, read, pause } = setup();
+ await kv.set("scope", "key", { original: true });
+ const gate = pause("state::get", "scope", "key", { after: true });
+ const update = kv.update("scope", "key", [{ type: "set", path: "updated", value: true }]);
+ await gate.entered;
+ const later = operation === "set" ? kv.set("scope", "key", { replacement: true }) : kv.delete("scope", "key");
+ await nextTurn();
+ gate.release();
+ await Promise.all([update, later]);
+ expect(read("scope", "key")).toEqual(operation === "set" ? { replacement: true } : null);
+ });
+
+ it.each(["set", "delete"] as const)("starts a local update from an earlier pending %s", async (operation) => {
+ const { kv, read, pause } = setup();
+ await kv.set("scope", "key", { original: true });
+ const gate = pause(`state::${operation}`, "scope", "key");
+ const earlier = operation === "set" ? kv.set("scope", "key", { replacement: true }) : kv.delete("scope", "key");
+ await gate.entered;
+ const update = kv.update<UpdateResult>("scope", "key", [{ type: "set", path: "updated", value: true }]);
+ await nextTurn();
+ gate.release();
+ const [, result] = await Promise.all([earlier, update]);
+ expect(result.old_value).toEqual(operation === "set" ? { replacement: true } : null);
+ expect(read("scope", "key")).toEqual(operation === "set" ? { replacement: true, updated: true } : { updated: true });
+ });
+
+ it.each([false, true])("serializes local and native updates, native first: %s", async (nativeFirst) => {
+ const { kv, read, pause } = setup();
+ await kv.set("scope", "key", { count: 0 });
+ const local = () => kv.update<UpdateResult>("scope", "key", [{ type: "set", path: "updated", value: true }]);
+ const native = () => kv.update<UpdateResult>("scope", "key", [{ type: "increment", path: "count", value: 1 }]);
+ const gate = pause(nativeFirst ? "state::update" : "state::get", "scope", "key", { after: !nativeFirst });
+ const first = nativeFirst ? native() : local();
+ await gate.entered;
+ const second = nativeFirst ? local() : native();
+ await nextTurn();
+ gate.release();
+ const [, result] = await Promise.all([first, second]);
+ expect(result.old_value).toEqual(nativeFirst ? { count: 1 } : { count: 0, updated: true });
+ expect(read("scope", "key")).toEqual({ count: 1, updated: true });
+ });
+
+ it("lets independent keys and scopes finish while another key is blocked", async () => {
+ const { kv, read, pause } = setup();
+ const gate = pause("state::get", "scope", "key", { after: true });
+ const blocked = kv.update("scope", "key", [{ type: "set", path: "updated", value: true }]);
+ await gate.entered;
+ try {
+ await Promise.all([kv.set("scope", "other", { independent: true }), kv.set("other", "key", { independent: true })]);
+ expect(read("scope", "other")).toEqual({ independent: true });
+ expect(read("other", "key")).toEqual({ independent: true });
+ expect(read("scope", "key")).toBeNull();
+ } finally {
+ gate.release();
+ await blocked;
+ }
+ });
+
+ it("orders mutations from StateKV instances sharing the same engine", async () => {
+ const { kv, sdk, read, pause } = setup();
+ const other = new StateKV(sdk as never, { backend: "redis" });
+ await kv.set("scope", "key", { original: true });
+ const gate = pause("state::get", "scope", "key", { after: true });
+ const update = kv.update("scope", "key", [{ type: "set", path: "updated", value: true }]);
+ await gate.entered;
+ const deletion = other.delete("scope", "key");
+ await nextTurn();
+ gate.release();
+ await Promise.all([update, deletion]);
+ expect(read("scope", "key")).toBeNull();
+ });
+
+ it.each(["get", "local-set", "set", "update", "delete"] as const)("releases the mutation queue after a %s failure", async (operation) => {
+ const { kv, read, pause } = setup();
+ await kv.set("scope", "key", { original: true });
+ const id = operation === "local-set" ? "set" : operation;
+ const gate = pause(`state::${id}`, "scope", "key", { error: "write unavailable" });
+ const failed = operation === "set" ? kv.set("scope", "key", { lost: true })
+ : operation === "delete" ? kv.delete("scope", "key")
+ : kv.update("scope", "key", [{ type: operation === "update" ? "increment" : "set", path: "lost", value: 1 }]);
+ const rejection = expect(failed).rejects.toThrow("write unavailable");
+ await gate.entered;
+ const next = kv.update("scope", "key", [{ type: "set", path: "recovered", value: true }]);
+ await nextTurn();
+ gate.release();
+ await Promise.all([rejection, next]);
+ expect(read("scope", "key")).toEqual({ original: true, recovered: true });
+ });
+
+ it("preserves set and native update responses while delete resolves without a value", async () => {
+ const { kv } = setup();
+ await expect(kv.set("scope", "key", { count: 1 })).resolves.toEqual({ old_value: null, new_value: { count: 1 } });
+ await expect(kv.update("scope", "key", [{ type: "increment", path: "count", value: 1 }])).resolves.toEqual({ old_value: { count: 1 }, new_value: { count: 2 }, errors: [] });
+ await expect(kv.delete("scope", "key")).resolves.toBeUndefined();
+ });
+
+ it("keeps file mutations on the engine's direct path", async () => {
+ const { kv, read, pause } = setup("file");
+ await kv.set("scope", "key", { original: true });
+ const gate = pause("state::set", "scope", "key");
+ const set = kv.set("scope", "key", { replacement: true });
+ await gate.entered;
+ try {
+ await kv.delete("scope", "key");
+ expect(read("scope", "key")).toBeNull();
+ } finally {
+ gate.release();
+ await set;
+ }
+ });
+});
+
+describe("Redis graph mutation ordering", () => {
+ const oldGeneration = "10000000-0000-4000-8000-000000000001";
+ const newGeneration = "10000000-0000-4000-8000-000000000002";
+
+ it.each(["set", "delete", "update", "native"] as const)("keeps a queued %s in its resolved graph generation", async (operation) => {
+ const { kv, read, pause } = setup();
+ await kv.set(KV.graphControl, "generation", oldGeneration);
+ await kv.set(KV.graphNodes, "key", { count: 0 });
+ const pinned = await pinGraphState(kv);
+ const oldScope = `${KV.graphNodes}:generation:${oldGeneration}`;
+ const gate = pause("state::get", oldScope, "key", { after: true });
+ const first = pinned.update(KV.graphNodes, "key", [{ type: "set", path: "first", value: true }]);
+ await gate.entered;
+ const queued = operation === "set" ? kv.set(KV.graphNodes, "key", { replacement: true })
+ : operation === "delete" ? kv.delete(KV.graphNodes, "key")
+ : kv.update(KV.graphNodes, "key", [{ type: operation === "native" ? "increment" : "set", path: "count", value: 1 }]);
+ await nextTurn();
+ await kv.set(KV.graphControl, "generation", newGeneration);
+ await kv.set(KV.graphNodes, "key", { fresh: true });
+ gate.release();
+ await Promise.all([first, queued]);
+ expect(await kv.get(KV.graphNodes, "key")).toEqual({ fresh: true });
+ expect(read(oldScope, "key")).toEqual(operation === "set" ? { replacement: true }
+ : operation === "delete" ? null : { count: 1, first: true });
+ });
+
+ it("releases the mutation lock before a graph listener updates the same key", async () => {
+ const { kv } = setup();
+ await kv.set(KV.graphControl, "generation", newGeneration);
+ await kv.set(KV.graphNodes, "reentrant", { count: 0 });
+ let reentered = false;
+ setGraphGenerationListener(async (kind) => {
+ if (kind !== "nodes" || reentered) return;
+ reentered = true;
+ await kv.update(KV.graphNodes, "reentrant", [{ type: "set", path: "count", value: 1 }]);
+ });
+ const updated = kv.update(KV.graphNodes, "reentrant", [{ type: "set", path: "updated", value: true }]);
+ await Promise.race([
+ updated,
+ nextTurn().then(() => { throw new Error("Graph listener cannot reenter the mutation queue"); }),
+ ]);
+ expect(reentered).toBe(true);
+ expect(await kv.get(KV.graphNodes, "reentrant")).toEqual({ count: 1, updated: true });
+ });
+});