Skip to content

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

fix: protect v0.9.30 memory writes and graph consistency (#1525)

Rohit Ghumarea5e036ccb933
diff --git a/.env.example b/.env.example
index 110a3291..ec8c26df 100644
--- a/.env.example
+++ b/.env.example
@@ -235,9 +235,16 @@
# 10. Claude Code bridge (opt-in)
# -----------------------------------------------------------------------------
-# CLAUDE_MEMORY_BRIDGE=true # Mirror compressed memories into Claude Code's CLAUDE.md
+# CLAUDE_MEMORY_BRIDGE=true # Export project memories into Claude Code's MEMORY.md
# CLAUDE_PROJECT_PATH=/path/to/your/project # Required when CLAUDE_MEMORY_BRIDGE=true
-# CLAUDE_MEMORY_LINE_BUDGET=200 # Lines of memory CLAUDE.md should hold
+# CLAUDE_MEMORY_LINE_BUDGET=200 # Maximum lines in the generated MEMORY.md
+# The bridge creates MEMORY.md only when absent. Every existing file is
+# preserved, including old generated exports and files edited by Claude Code.
+# An identical export is a no-op; different content returns an error. To
+# regenerate, deliberately move the existing file to a backup location first
+# (or remove it if no longer needed), then run memory_claude_bridge_sync again.
+# Only memories scoped to this project are exported; unscoped memories are
+# excluded. Reading MEMORY.md remains available regardless of who wrote it.
# -----------------------------------------------------------------------------
# 11. Obsidian export (opt-in)
diff --git a/AGENTS.md b/AGENTS.md
index 6cb59ff1..5250056f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -101,7 +101,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).
## Testing
-- Before every commit run, in order: `npm run build`, `npm run skills:gen`, `npm run docs:sync`, `npm run skills:check`, `npm test` (2,700+ tests). Commit anything the generators changed. CI runs the same build, skills check and tests.
+- Before every commit run, in order: `npm run build`, `npm run skills:gen`, `npm run docs:sync`, `npm run skills:check`, `npm test` (2,900+ tests). Commit anything the generators changed. CI runs the same build, skills check and tests.
- Before any npm publish: `npm run release:gate` must pass. It installs the packed tarballs into a clean home and runs capture, recovery, restart, export/import, MCP and status checks against the installed CLI (see CONTRIBUTING.md, Release process)
- Mock pattern: `vi.mock("iii-sdk")` with mock `sdk.trigger`, `kv.get/set/list`
- Test files go in `test/` with `.test.ts` extension
@@ -114,4 +114,4 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).
- 6 MCP resources, 3 MCP prompts
- 12 hooks, 17 skills
- 312+ iii functions
-- 2,700+ tests
+- 2,900+ tests
diff --git a/README.md b/README.md
index 0c7ad885..b9802af2 100644
--- a/README.md
+++ b/README.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tools.svg"><img src="assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-hooks.svg"><img src="assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-deps.svg"><img src="assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tests.svg"><img src="assets/tags/stat-tests.svg" alt="2,700+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tests.svg"><img src="assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1061,12 +1061,16 @@ Memories decay over time (Ebbinghaus curve). Frequently accessed memories streng
| **Auto-forgetting** | TTL expiry, contradiction detection, importance eviction |
| **Privacy first** | API keys, secrets, `<private>` tags stripped before storage |
| **Self-healing** | Circuit breaker, provider fallback chain, health monitoring |
-| **Claude bridge** | Bi-directional sync with MEMORY.md |
+| **Claude bridge** | Read MEMORY.md and export project memories without replacing existing files |
| **Knowledge graph** | Entity extraction + BFS traversal |
| **Team memory** | Namespaced shared + private across team members |
| **Citation provenance** | Trace any memory back to source observations |
| **Git snapshots** | Version, rollback, and diff memory state |
+The Claude bridge is opt-in: set `CLAUDE_MEMORY_BRIDGE=true` and `CLAUDE_PROJECT_PATH` to your project directory, then restart agentmemory. `memory_claude_bridge_sync` exports only the latest memories scoped to that project, excluding unscoped memories. The read direction continues to read existing `MEMORY.md` content.
+
+Export creates `MEMORY.md` only when it is absent. Existing files are preserved, including previous generated exports and edits made by you or Claude Code. Identical content returns `changed: false`; different content returns an error. To regenerate deliberately, move the existing file to a backup location (or remove it if no longer needed), then run the tool again. See the bridge settings in [`.env.example`](.env.example).
+
---
<h2 id="search"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-search.svg"><img src="assets/tags/section-search.svg" alt="Search" height="32" /></picture></h2>
@@ -1150,7 +1154,7 @@ Three tool surfaces, smallest to largest: `AGENTMEMORY_TOOLS=core` trims visibil
| `memory_relations` | Query relationship graph |
| `memory_graph_query` | Knowledge graph traversal |
| `memory_consolidate` | Run 4-tier consolidation |
-| `memory_claude_bridge_sync` | Sync with MEMORY.md |
+| `memory_claude_bridge_sync` | Read MEMORY.md or create a project export, preserving existing files |
| `memory_team_share` | Share with team members |
| `memory_team_feed` | Recent shared items |
| `memory_audit` | Audit trail of operations |
@@ -1446,7 +1450,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin systems | `iii worker add <name>` |
-**223 source files · ~53,000 LOC · 2,700+ tests · 312 functions · 60 KV scopes**, all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.
+**227 source files · ~54,000 LOC · 2,900+ tests · 312 functions · 62 KV scopes**, all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.
---
@@ -1829,6 +1833,7 @@ curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:31
| `GET` | `/agentmemory/export` | Export all data |
| `POST` | `/agentmemory/import` | Import from JSON |
| `POST` | `/agentmemory/graph/query` | Knowledge graph query |
+| `POST` | `/agentmemory/graph/reset` | Start an empty graph generation; retain observations and memories |
| `POST` | `/agentmemory/graph/compact` | Trim oversized graph provenance |
| `POST` | `/agentmemory/team/share` | Share with team |
| `GET` | `/agentmemory/audit` | Audit trail |
@@ -1851,6 +1856,10 @@ Failed events are retried every `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS` (10 s) w
When the server is down, does not answer in time or returns a 5xx, the hook appends the observation to a local spool file, `<data dir>/capture-spool/<host>-<port>.jsonl` (override the folder with `AGENTMEMORY_CAPTURE_SPOOL_DIR`). The file is private to your user (mode 600), secrets are redacted the same way the server redacts them, it holds at most `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES` (5 MiB) and drops entries older than `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS` (168). When it is full, new entries are dropped and counted, and `/agentmemory/status` reports it. The hook still exits 0 within its time limit and adds no request when the server is healthy. The spool is sent at the next start and by the first hook that reaches the server again, in a background process so the agent does not wait. Event ids make this safe: an observation that did arrive before a timeout is not stored twice. `npx @agentmemory/agentmemory capture` shows the spool and the server inbox, `--drain` sends the spool now, and `GET /agentmemory/capture` returns the same as JSON. Set `AGENTMEMORY_CAPTURE_SPOOL=false` to turn the spool off.
+**Resetting the graph.** Call `POST /agentmemory/graph/reset` to start a new graph generation. The previous graph becomes inaccessible to graph queries, node lookups, statistics, and MCP reads; new imports and extraction populate the new generation. Existing observations and memories remain available. Old graph storage is retained.
+
+**Upgrading from v0.9.30:** if you already reset the graph before upgrading, run `POST /agentmemory/graph/reset` again after the upgrade. Earlier reset timestamps are not used to infer a completed generation reset.
+
**Compacting graph provenance.** Each knowledge graph node and edge keeps the ids of the newest 32 observations it came from. Stores written before that cap can hold thousands of ids per hot node, which makes graph search and the viewer slow or drops the worker. agentmemory fixes this by itself: on the first start after upgrading it trims every node, edge, superseded edge (the temporal graph history) and the cached snapshot to the cap in the background, in small slices with a pause between them, so search, capture and the viewer keep working. It saves its progress, resumes after a restart and never runs again once it has finished. `/agentmemory/status` and the viewer Health page show it as pending, running (with the current scope and position), done or failed. Set `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false` to turn it off.
To run it by hand, call `POST /agentmemory/graph/compact`. It walks the name and edge-key indexes instead of listing every node and edge, and is safe to re-run. When it trims ids it writes a `graph_compact` audit entry.
@@ -1873,7 +1882,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.ar-SA.md b/READMEs/README.ar-SA.md
index d56c7779..8d993342 100644
--- a/READMEs/README.ar-SA.md
+++ b/READMEs/README.ar-SA.md
@@ -73,7 +73,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1439,7 +1439,7 @@ fi
| Prometheus / Grafana | OTEL في iii + مراقب الحالة الصحية |
| أنظمة إضافات مخصصة | `iii worker add <name>` |
-**223 ملف مصدري · ~53,000 سطر برمجي · 2,700+ اختبار · 312 دالة · 60 نطاق KV**، كل ذلك على ثلاث بنى أساسية. لا يوجد أمر `agentmemory plugin install`. نظام الإضافات هو iii نفسه.
+**227 ملف مصدري · ~54,000 سطر برمجي · 2,900+ اختبار · 312 دالة · 62 نطاق KV**، كل ذلك على ثلاث بنى أساسية. لا يوجد أمر `agentmemory plugin install`. نظام الإضافات هو iii نفسه.
---
@@ -1863,7 +1863,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.bn-BD.md b/READMEs/README.bn-BD.md
index 6b69b8a3..625803cc 100644
--- a/READMEs/README.bn-BD.md
+++ b/READMEs/README.bn-BD.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP টুল" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 অটো হুক" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 এক্সটার্নাল ডিবি" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ টেস্ট পাস" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ টেস্ট পাস" height="38" /></picture>
</p>
<p align="center">
@@ -1437,7 +1437,7 @@ fi
| Prometheus / Grafana | iii OTEL + হেলথ মনিটর |
| কাস্টম প্লাগইন সিস্টেম | `iii worker add <name>` |
-**223 সোর্স ফাইল · ~53,000 LOC · 2,700+ টেস্ট · 312 ফাংশন · 60 KV স্কোপ**, সবকিছু তিনটি প্রিমিটিভের উপর। কোনো `agentmemory plugin install` নেই। প্লাগইন সিস্টেমটাই iii নিজে।
+**227 সোর্স ফাইল · ~54,000 LOC · 2,900+ টেস্ট · 312 ফাংশন · 62 KV স্কোপ**, সবকিছু তিনটি প্রিমিটিভের উপর। কোনো `agentmemory plugin install` নেই। প্লাগইন সিস্টেমটাই iii নিজে।
---
@@ -1861,7 +1861,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.cs-CZ.md b/READMEs/README.cs-CZ.md
index a57e3cfc..fe64e766 100644
--- a/READMEs/README.cs-CZ.md
+++ b/READMEs/README.cs-CZ.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP nástrojů" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automatických hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 externích databází" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ testů úspěšně proběhlo" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ testů úspěšně proběhlo" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Vlastní systémy pluginů | `iii worker add <name>` |
-**223 zdrojových souborů · ~53,000 řádků kódu · 2,700+ testů · 312 funkcí · 60 KV scopes**, vše na třech primitivech. Žádné `agentmemory plugin install`. Systém pluginů je samo iii.
+**227 zdrojových souborů · ~54,000 řádků kódu · 2,900+ testů · 312 funkcí · 62 KV scopes**, vše na třech primitivech. Žádné `agentmemory plugin install`. Systém pluginů je samo iii.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.da-DK.md b/READMEs/README.da-DK.md
index 14098e09..e95f5209 100644
--- a/READMEs/README.da-DK.md
+++ b/READMEs/README.da-DK.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP-værktøjer" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automatiske hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 eksterne databaser" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ beståede tests" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ beståede tests" height="38" /></picture>
</p>
<p align="center">
@@ -1436,7 +1436,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin-systemer | `iii worker add <name>` |
-**223 kildefiler · ~53,000 LOC · 2,700+ tests · 312 funktioner · 60 KV-scopes**, alt på tre primitiver. Intet `agentmemory plugin install`. Plugin-systemet er iii selv.
+**227 kildefiler · ~54,000 LOC · 2,900+ tests · 312 funktioner · 62 KV-scopes**, alt på tre primitiver. Intet `agentmemory plugin install`. Plugin-systemet er iii selv.
---
@@ -1860,7 +1860,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.de-DE.md b/READMEs/README.de-DE.md
index d3a21162..cfa0822c 100644
--- a/READMEs/README.de-DE.md
+++ b/READMEs/README.de-DE.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP-Tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 Auto-Hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 externe DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ bestandene Tests" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ bestandene Tests" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + Health-Monitor |
| Eigene Plugin-Systeme | `iii worker add <name>` |
-**223 Quelldateien · ~53,000 LOC · 2,700+ Tests · 312 Funktionen · 60 KV-Scopes**, alles auf drei Primitiven. Kein `agentmemory plugin install`. Das Plugin-System ist iii selbst.
+**227 Quelldateien · ~54,000 LOC · 2,900+ Tests · 312 Funktionen · 62 KV-Scopes**, alles auf drei Primitiven. Kein `agentmemory plugin install`. Das Plugin-System ist iii selbst.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.el-GR.md b/READMEs/README.el-GR.md
index 57226dee..ea1d4291 100644
--- a/READMEs/README.el-GR.md
+++ b/READMEs/README.el-GR.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 εργαλεία MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 αυτόματα hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 εξωτερικές βάσεις δεδομένων" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ επιτυχημένες δοκιμές" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ επιτυχημένες δοκιμές" height="38" /></picture>
</p>
<p align="center">
@@ -1438,7 +1438,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor υγείας |
| Προσαρμοσμένα συστήματα plugin | `iii worker add <name>` |
-**223 αρχεία πηγαίου κώδικα · ~53,000 LOC · 2,700+ δοκιμές · 312 functions · 60 KV scopes**, όλα πάνω σε τρία primitives. Δεν υπάρχει `agentmemory plugin install`. Το σύστημα plugin είναι το ίδιο το iii.
+**227 αρχεία πηγαίου κώδικα · ~54,000 LOC · 2,900+ δοκιμές · 312 functions · 62 KV scopes**, όλα πάνω σε τρία primitives. Δεν υπάρχει `agentmemory plugin install`. Το σύστημα plugin είναι το ίδιο το iii.
---
@@ -1862,7 +1862,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.es-ES.md b/READMEs/README.es-ES.md
index 2abc256c..360b7711 100644
--- a/READMEs/README.es-ES.md
+++ b/READMEs/README.es-ES.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 tools MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hooks automáticos" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 bases de datos externas" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ tests superados" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests superados" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor de salud |
| Sistemas de plugins propios | `iii worker add <name>` |
-**223 ficheros de código · ~53,000 LOC · 2,700+ tests · 312 funciones · 60 scopes KV**, todo sobre tres primitivos. No hay `agentmemory plugin install`. El sistema de plugins es iii mismo.
+**227 ficheros de código · ~54,000 LOC · 2,900+ tests · 312 funciones · 62 scopes KV**, todo sobre tres primitivos. No hay `agentmemory plugin install`. El sistema de plugins es iii mismo.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.fi-FI.md b/READMEs/README.fi-FI.md
index bdcdebc1..ac6ae128 100644
--- a/READMEs/README.fi-FI.md
+++ b/READMEs/README.fi-FI.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP-työkalua" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automaattista hookia" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 ulkoista tietokantaa" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ testiä läpäisty" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ testiä läpäisty" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + terveysmonitori |
| Mukautetut plugin-järjestelmät | `iii worker add <name>` |
-**223 lähdetiedostoa · ~53,000 LOC · 2,700+ testiä · 312 funktiota · 60 KV-scopea**, kaikki kolmen primitiivin päällä. Ei `agentmemory plugin install` -komentoa. Plugin-järjestelmä on iii itse.
+**227 lähdetiedostoa · ~54,000 LOC · 2,900+ testiä · 312 funktiota · 62 KV-scopea**, kaikki kolmen primitiivin päällä. Ei `agentmemory plugin install` -komentoa. Plugin-järjestelmä on iii itse.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.fr-FR.md b/READMEs/README.fr-FR.md
index 2e7baa1e..8319c433 100644
--- a/READMEs/README.fr-FR.md
+++ b/READMEs/README.fr-FR.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1448,7 +1448,7 @@ fi
| Prometheus / Grafana | iii OTEL + moniteur de santé |
| Systèmes de plugins custom | `iii worker add <name>` |
-**223 fichiers sources · ~53,000 LOC · 2,700+ tests · 312 fonctions · 60 scopes KV**, tout sur trois primitives. Pas de `agentmemory plugin install`. Le système de plugins, c'est iii lui-même.
+**227 fichiers sources · ~54,000 LOC · 2,900+ 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.
---
@@ -1872,7 +1872,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.he-IL.md b/READMEs/README.he-IL.md
index 598907af..8a2e9947 100644
--- a/READMEs/README.he-IL.md
+++ b/READMEs/README.he-IL.md
@@ -73,7 +73,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 כלי MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hooks אוטומטיים" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 מסדי נתונים חיצוניים" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ בדיקות עוברות" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ בדיקות עוברות" height="38" /></picture>
</p>
<p align="center">
@@ -1439,7 +1439,7 @@ fi
| Prometheus / Grafana | iii OTEL + מוניטור health |
| מערכות plugin מותאמות אישית | `iii worker add <name>` |
-**223 קבצי מקור · ~53,000 LOC · 2,700+ בדיקות · 312 פונקציות · 60 תחומי KV**, הכול על שלושה primitives. אין `agentmemory plugin install`. מערכת ה-plugin היא iii עצמו.
+**227 קבצי מקור · ~54,000 LOC · 2,900+ בדיקות · 312 פונקציות · 62 תחומי KV**, הכול על שלושה primitives. אין `agentmemory plugin install`. מערכת ה-plugin היא iii עצמו.
---
@@ -1863,7 +1863,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.hi-IN.md b/READMEs/README.hi-IN.md
index 936158b0..7a6c698c 100644
--- a/READMEs/README.hi-IN.md
+++ b/READMEs/README.hi-IN.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1449,7 +1449,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin systems | `iii worker add <name>` |
-**223 source files · ~53,000 LOC · 2,700+ tests · 312 functions · 60 KV scopes**, सब कुछ तीन primitives पर। कोई `agentmemory plugin install` नहीं। Plugin system iii स्वयं है।
+**227 source files · ~54,000 LOC · 2,900+ tests · 312 functions · 62 KV scopes**, सब कुछ तीन primitives पर। कोई `agentmemory plugin install` नहीं। Plugin system iii स्वयं है।
---
@@ -1873,7 +1873,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.hu-HU.md b/READMEs/README.hu-HU.md
index dce76e6d..1094c112 100644
--- a/READMEs/README.hu-HU.md
+++ b/READMEs/README.hu-HU.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP eszköz" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automatikus hook" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 külső adatbázis" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ sikeres teszt" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ sikeres teszt" height="38" /></picture>
</p>
<p align="center">
@@ -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>` |
-**223 forrásfájl · ~53,000 LOC · 2,700+ teszt · 312 funkció · 60 KV-hatókör**, mindez három primitíven. Nincs `agentmemory plugin install`. A plugin-rendszer maga az iii.
+**227 forrásfájl · ~54,000 LOC · 2,900+ teszt · 312 funkció · 62 KV-hatókör**, mindez három primitíven. Nincs `agentmemory plugin install`. A plugin-rendszer maga az iii.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.id-ID.md b/READMEs/README.id-ID.md
index 52fd8a99..ff5e3cf4 100644
--- a/READMEs/README.id-ID.md
+++ b/READMEs/README.id-ID.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 tool MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hook otomatis" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 DB eksternal" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ pengujian lolos" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ pengujian lolos" height="38" /></picture>
</p>
<p align="center">
@@ -1447,7 +1447,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Sistem plugin custom | `iii worker add <name>` |
-**223 file sumber · ~53,000 LOC · 2,700+ pengujian · 312 fungsi · 60 scope KV**, semua di atas tiga primitif. Tidak ada `agentmemory plugin install`. Sistem plugin-nya adalah iii itu sendiri.
+**227 file sumber · ~54,000 LOC · 2,900+ pengujian · 312 fungsi · 62 scope KV**, semua di atas tiga primitif. Tidak ada `agentmemory plugin install`. Sistem plugin-nya adalah iii itu sendiri.
---
@@ -1871,7 +1871,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.it-IT.md b/READMEs/README.it-IT.md
index 770b3dd0..c85e4ac3 100644
--- a/READMEs/README.it-IT.md
+++ b/READMEs/README.it-IT.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor di salute |
| Sistemi di plugin personalizzati | `iii worker add <name>` |
-**223 file sorgente · ~53,000 righe di codice · 2,700+ test · 312 funzioni · 60 scope KV**, tutto su tre primitive. Nessun `agentmemory plugin install`. Il sistema di plugin è iii stesso.
+**227 file sorgente · ~54,000 righe di codice · 2,900+ test · 312 funzioni · 62 scope KV**, tutto su tre primitive. Nessun `agentmemory plugin install`. Il sistema di plugin è iii stesso.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.ja-JP.md b/READMEs/README.ja-JP.md
index fedf3758..043adbd7 100644
--- a/READMEs/README.ja-JP.md
+++ b/READMEs/README.ja-JP.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP ツール" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 自動 hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="外部 DB 0 個" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ 件のテストが成功" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ 件のテストが成功" height="38" /></picture>
</p>
<p align="center">
@@ -1445,7 +1445,7 @@ fi
| Prometheus / Grafana | iii OTEL + ヘルスモニタ |
| カスタムプラグインシステム | `iii worker add <name>` |
-**223 ソースファイル · ~53,000 LOC · 2,700+ テスト · 312 functions · 60 KV スコープ** — すべて 3 つのプリミティブの上に。`agentmemory plugin install` はありません。プラグインシステムは iii そのものです。
+**227 ソースファイル · ~54,000 LOC · 2,900+ テスト · 312 functions · 62 KV スコープ** — すべて 3 つのプリミティブの上に。`agentmemory plugin install` はありません。プラグインシステムは iii そのものです。
---
@@ -1869,7 +1869,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.ko-KR.md b/READMEs/README.ko-KR.md
index b164c32a..e0dadacb 100644
--- a/READMEs/README.ko-KR.md
+++ b/READMEs/README.ko-KR.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + health 모니터 |
| 커스텀 플러그인 시스템 | `iii worker add <name>` |
-**소스 파일 223개 · LOC ~53,000줄 · 테스트 2,700+개 · 함수 312개 · KV 스코프 60개**, 모두 세 가지 프리미티브 위에서 동작합니다. `agentmemory plugin install` 같은 것은 없습니다. 플러그인 시스템은 곧 iii 자체입니다.
+**소스 파일 227개 · LOC ~54,000줄 · 테스트 2,900+개 · 함수 312개 · KV 스코프 62개**, 모두 세 가지 프리미티브 위에서 동작합니다. `agentmemory plugin install` 같은 것은 없습니다. 플러그인 시스템은 곧 iii 자체입니다.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.nb-NO.md b/READMEs/README.nb-NO.md
index 2e10f52f..694280e9 100644
--- a/READMEs/README.nb-NO.md
+++ b/READMEs/README.nb-NO.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1447,7 +1447,7 @@ fi
| Prometheus / Grafana | iii OTEL + helseovervåker |
| Egendefinerte plugin-systemer | `iii worker add <name>` |
-**223 kildefiler · ~53,000 LOC · 2,700+ tester · 312 funksjoner · 60 KV-scopes**, alt på tre primitiver. Ingen `agentmemory plugin install`. Plugin-systemet er iii selv.
+**227 kildefiler · ~54,000 LOC · 2,900+ tester · 312 funksjoner · 62 KV-scopes**, alt på tre primitiver. Ingen `agentmemory plugin install`. Plugin-systemet er iii selv.
---
@@ -1871,7 +1871,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.nl-NL.md b/READMEs/README.nl-NL.md
index 749663b7..92ca4769 100644
--- a/READMEs/README.nl-NL.md
+++ b/READMEs/README.nl-NL.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin-systemen | `iii worker add <name>` |
-**223 bronbestanden · ~53,000 LOC · 2,700+ tests · 312 functies · 60 KV-scopes**, allemaal op drie primitieven. Geen `agentmemory plugin install`. Het pluginsysteem is iii zelf.
+**227 bronbestanden · ~54,000 LOC · 2,900+ tests · 312 functies · 62 KV-scopes**, allemaal op drie primitieven. Geen `agentmemory plugin install`. Het pluginsysteem is iii zelf.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.pl-PL.md b/READMEs/README.pl-PL.md
index 453f1b72..b1b98c54 100644
--- a/READMEs/README.pl-PL.md
+++ b/READMEs/README.pl-PL.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 narzędzia MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automatycznych hooków" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 zewnętrznych baz danych" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ zaliczonych testów" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ zaliczonych testów" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor stanu |
| Niestandardowe systemy pluginów | `iii worker add <name>` |
-**223 plików źródłowych · ~53,000 LOC · 2,700+ testów · 312 funkcji · 60 zakresów KV**, wszystko na trzech prymitywach. Nie ma `agentmemory plugin install`. Systemem pluginów jest sam iii.
+**227 plików źródłowych · ~54,000 LOC · 2,900+ testów · 312 funkcji · 62 zakresy KV**, wszystko na trzech prymitywach. Nie ma `agentmemory plugin install`. Systemem pluginów jest sam iii.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.pt-BR.md b/READMEs/README.pt-BR.md
index 306ef159..852cd6fc 100644
--- a/READMEs/README.pt-BR.md
+++ b/READMEs/README.pt-BR.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1447,7 +1447,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor de saúde |
| Sistemas de plugin customizados | `iii worker add <name>` |
-**223 arquivos de código · ~53,000 LOC · 2,700+ testes · 312 funções · 60 escopos KV**, tudo em cima de três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
+**227 arquivos de código · ~54,000 LOC · 2,900+ 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.
---
@@ -1871,7 +1871,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.pt-PT.md b/READMEs/README.pt-PT.md
index 97146fc4..6b82ab4d 100644
--- a/READMEs/README.pt-PT.md
+++ b/READMEs/README.pt-PT.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 ferramentas MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hooks automáticos" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 bases de dados externas" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ testes aprovados" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ testes aprovados" height="38" /></picture>
</p>
<p align="center">
@@ -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>` |
-**223 ficheiros de código-fonte · ~53,000 LOC · 2,700+ testes · 312 funções · 60 âmbitos de KV**, tudo sobre três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
+**227 ficheiros de código-fonte · ~54,000 LOC · 2,900+ 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.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.ro-RO.md b/READMEs/README.ro-RO.md
index ddbac809..6f73b5ee 100644
--- a/READMEs/README.ro-RO.md
+++ b/READMEs/README.ro-RO.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 de instrumente MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hook-uri automate" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 baze de date externe" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ teste trecute" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ teste trecute" height="38" /></picture>
</p>
<p align="center">
@@ -1430,7 +1430,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor de sănătate |
| Sisteme de plugin-uri personalizate | `iii worker add <name>` |
-**223 fișiere sursă · ~53,000 LOC · 2,700+ teste · 312 funcții · 60 domenii KV**, toate pe trei primitive. Niciun `agentmemory plugin install`. Sistemul de plugin-uri este chiar iii.
+**227 fișiere sursă · ~54,000 LOC · 2,900+ teste · 312 funcții · 62 de domenii KV**, toate pe trei primitive. Niciun `agentmemory plugin install`. Sistemul de plugin-uri este chiar iii.
---
@@ -1854,7 +1854,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.ru-RU.md b/READMEs/README.ru-RU.md
index 5159f1cd..d04a8ada 100644
--- a/READMEs/README.ru-RU.md
+++ b/READMEs/README.ru-RU.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + монитор состояния |
| Самописные плагинные системы | `iii worker add <name>` |
-**223 исходных файлов · ~53,000 LOC · 2,700+ тестов · 312 функция · 60 KV-scope'ов**, всё на трёх примитивах. Никакого `agentmemory plugin install`. Плагинная система — это сам iii.
+**227 исходных файлов · ~54,000 LOC · 2,900+ тестов · 312 функций · 62 KV-scope**, всё на трёх примитивах. Никакого `agentmemory plugin install`. Плагинная система — это сам iii.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.sv-SE.md b/READMEs/README.sv-SE.md
index 5d2e43e6..895aa777 100644
--- a/READMEs/README.sv-SE.md
+++ b/READMEs/README.sv-SE.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP-verktyg" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automatiska hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 externa databaser" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ godkända tester" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ godkända tester" height="38" /></picture>
</p>
<p align="center">
@@ -1437,7 +1437,7 @@ fi
| Prometheus / Grafana | iii OTEL + hälsoövervakare |
| Anpassade pluginsystem | `iii worker add <name>` |
-**223 källkodsfiler · ~53,000 LOC · 2,700+ tester · 312 funktioner · 60 KV-scopes**, allt på tre primitiv. Inget `agentmemory plugin install`. Pluginsystemet är iii självt.
+**227 källkodsfiler · ~54,000 LOC · 2,900+ tester · 312 funktioner · 62 KV-scopes**, allt på tre primitiv. Inget `agentmemory plugin install`. Pluginsystemet är iii självt.
---
@@ -1861,7 +1861,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.th-TH.md b/READMEs/README.th-TH.md
index 21f84656..3a1ac15d 100644
--- a/READMEs/README.th-TH.md
+++ b/READMEs/README.th-TH.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 เครื่องมือ MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hook อัตโนมัติ" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="ไม่ต้องพึ่ง external DB เลย" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="ผ่านการทดสอบ 2,700+ รายการ" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="ผ่านการทดสอบ 2,900+ รายการ" height="38" /></picture>
</p>
<p align="center">
@@ -1444,7 +1444,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin systems | `iii worker add <name>` |
-**223 source file · ~53,000 LOC · 2,700+ การทดสอบ · 312 function · 60 KV scope** ทั้งหมดอยู่บน primitive สามตัว ไม่มี `agentmemory plugin install` ระบบ plugin ก็คือ iii เองนั่นแหละ
+**227 source file · ~54,000 LOC · 2,900+ การทดสอบ · 312 function · 62 KV scope** ทั้งหมดอยู่บน primitive สามตัว ไม่มี `agentmemory plugin install` ระบบ plugin ก็คือ iii เองนั่นแหละ
---
@@ -1868,7 +1868,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.tl-PH.md b/READMEs/README.tl-PH.md
index e5576d32..884e3ebb 100644
--- a/READMEs/README.tl-PH.md
+++ b/READMEs/README.tl-PH.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tool" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 awtomatikong hook" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 panlabas na DB" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ pumapasang test" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ pumapasang test" height="38" /></picture>
</p>
<p align="center">
@@ -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>` |
-**223 na source file · ~53,000 LOC · 2,700+ na test · 312 na function · 60 na KV scope**, lahat sa tatlong primitive. Walang `agentmemory plugin install`. Ang plugin system mismo ay ang iii.
+**227 na source file · ~54,000 LOC · 2,900+ na test · 312 na function · 62 na KV scope**, lahat sa tatlong primitive. Walang `agentmemory plugin install`. Ang plugin system mismo ay ang iii.
---
@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.tr-TR.md b/READMEs/README.tr-TR.md
index 558838ee..e44fe39b 100644
--- a/READMEs/README.tr-TR.md
+++ b/READMEs/README.tr-TR.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1437,7 +1437,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom eklenti sistemleri | `iii worker add <name>` |
-**223 kaynak dosya · ~53,000 LOC · 2,700+ test · 312 fonksiyon · 60 KV scope**, hepsi üç primitif üzerinde. `agentmemory plugin install` yok. Eklenti sistemi, iii'nin kendisidir.
+**227 kaynak dosya · ~54,000 LOC · 2,900+ test · 312 fonksiyon · 62 KV scope**, hepsi üç primitif üzerinde. `agentmemory plugin install` yok. Eklenti sistemi, iii'nin kendisidir.
---
@@ -1861,7 +1861,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.uk-UA.md b/READMEs/README.uk-UA.md
index 3ee2bb63..23ed1f21 100644
--- a/READMEs/README.uk-UA.md
+++ b/READMEs/README.uk-UA.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 інструменти MCP" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 автоматичних хуків" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 зовнішніх БД" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ тестів пройдено" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ тестів пройдено" height="38" /></picture>
</p>
<p align="center">
@@ -1447,7 +1447,7 @@ fi
| Prometheus / Grafana | iii OTEL + монітор стану здоров'я |
| Власні системи плагінів | `iii worker add <name>` |
-**223 вихідних файлів · ~53,000 LOC · 2,700+ тестів · 312 функцій · 60 KV-скоупів**, усе на трьох примітивах. Жодного `agentmemory plugin install`. Система плагінів — це сам iii.
+**227 вихідних файлів · ~54,000 LOC · 2,900+ тестів · 312 функцій · 62 KV-скоупів**, усе на трьох примітивах. Жодного `agentmemory plugin install`. Система плагінів — це сам iii.
---
@@ -1871,7 +1871,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.ur-PK.md b/READMEs/README.ur-PK.md
index ddff308c..19cf115c 100644
--- a/READMEs/README.ur-PK.md
+++ b/READMEs/README.ur-PK.md
@@ -73,7 +73,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP ٹولز" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 خودکار ہکس" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 خارجی ڈیٹابیسز" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ ٹیسٹس پاس ہو رہے ہیں" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ ٹیسٹس پاس ہو رہے ہیں" height="38" /></picture>
</p>
<p align="center">
@@ -1432,7 +1432,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| کسٹم plugin سسٹمز | `iii worker add <name>` |
-**223 سورس فائلز · ~53,000 لائنز کوڈ · 2,700+ ٹیسٹس · 312 فنکشنز · 60 KV اسکوپس**، سب تین primitives پر۔ کوئی `agentmemory plugin install` نہیں۔ plugin سسٹم خود iii ہی ہے۔
+**227 سورس فائلز · ~54,000 لائنز کوڈ · 2,900+ ٹیسٹس · 312 فنکشنز · 62 KV اسکوپس**، سب تین primitives پر۔ کوئی `agentmemory plugin install` نہیں۔ plugin سسٹم خود iii ہی ہے۔
---
@@ -1854,7 +1854,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.vi-VN.md b/READMEs/README.vi-VN.md
index 1dec686e..43c1b769 100644
--- a/READMEs/README.vi-VN.md
+++ b/READMEs/README.vi-VN.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ tests passing" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1437,7 +1437,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Hệ thống plugin tùy chỉnh | `iii worker add <name>` |
-**223 file source · ~53,000 LOC · 2,700+ test · 312 function · 60 KV scope**, tất cả trên ba primitive. Không có `agentmemory plugin install`. Hệ thống plugin chính là iii.
+**227 file source · ~54,000 LOC · 2,900+ 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.
---
@@ -1861,7 +1861,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.zh-CN.md b/READMEs/README.zh-CN.md
index 51250d3b..94d4a82d 100644
--- a/READMEs/README.zh-CN.md
+++ b/READMEs/README.zh-CN.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 个 MCP 工具" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 个自动 hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 个外部数据库" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ 项测试通过" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ 项测试通过" height="38" /></picture>
</p>
<p align="center">
@@ -1444,7 +1444,7 @@ fi
| Prometheus / Grafana | iii OTEL + 健康监控 |
| Custom plugin systems | `iii worker add <name>` |
-**223 个源文件 · ~53,000 行代码 · 2,700+ 个测试 · 312 个函数 · 60 个 KV 作用域**,全部基于三种原语。没有 `agentmemory plugin install`。插件系统就是 iii 本身。
+**227 个源文件 · ~54,000 行代码 · 2,900+ 个测试 · 312 个函数 · 62 个 KV 作用域**,全部基于三种原语。没有 `agentmemory plugin install`。插件系统就是 iii 本身。
---
@@ -1868,7 +1868,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/READMEs/README.zh-TW.md b/READMEs/README.zh-TW.md
index d8f7704f..83605600 100644
--- a/READMEs/README.zh-TW.md
+++ b/READMEs/README.zh-TW.md
@@ -71,7 +71,7 @@
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 個 MCP 工具" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 個自動 hooks" height="38" /></picture>
<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 個外部資料庫" height="38" /></picture>
- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,700+ 測試通過" height="38" /></picture>
+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ 測試通過" height="38" /></picture>
</p>
<p align="center">
@@ -1430,7 +1430,7 @@ fi
| Prometheus / Grafana | iii OTEL + 健康監控 |
| 自訂外掛系統 | `iii worker add <name>` |
-**223 個原始檔 · ~53,000 行程式碼 · 2,700+ 測試 · 312 個函式 · 60 個 KV 範圍**,全部基於三種原語。沒有 `agentmemory plugin install`。外掛系統就是 iii 本身。
+**227 個原始檔 · ~54,000 行程式碼 · 2,900+ 測試 · 312 個函式 · 62 個 KV 範圍**,全部基於三種原語。沒有 `agentmemory plugin install`。外掛系統就是 iii 本身。
---
@@ -1854,7 +1854,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a
```bash
npm run dev # Hot reload
npm run build # Production build
-npm test # 2,700+ tests
+npm test # 2,900+ tests
npm run test:integration # API tests (requires running services)
```
diff --git a/assets/tags/light/stat-tests.svg b/assets/tags/light/stat-tests.svg
index a6acf266..955556fb 100644
--- a/assets/tags/light/stat-tests.svg
+++ b/assets/tags/light/stat-tests.svg
@@ -1,5 +1,5 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 48" fill="none" role="img" aria-label="TESTS PASSING: 2700+">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 48" fill="none" role="img" aria-label="TESTS PASSING: 2900+">
<rect x="0" y="0" width="140" height="48" rx="10" fill="#FFFFFF" stroke="#E5E7EB" stroke-width="1"/>
- <text x="70" y="24" fill="#16A34A" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="18" font-weight="900" text-anchor="middle" letter-spacing="-0.3">2700+</text>
+ <text x="70" y="24" fill="#16A34A" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="18" font-weight="900" text-anchor="middle" letter-spacing="-0.3">2900+</text>
<text x="70" y="38" fill="#64748B" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="9" font-weight="600" text-anchor="middle" letter-spacing="1.5">TESTS PASSING</text>
</svg>
diff --git a/assets/tags/stat-tests.svg b/assets/tags/stat-tests.svg
index 25a0b0c8..8e120b66 100644
--- a/assets/tags/stat-tests.svg
+++ b/assets/tags/stat-tests.svg
@@ -1,5 +1,5 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 48" fill="none" role="img" aria-label="TESTS PASSING: 2700+">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 48" fill="none" role="img" aria-label="TESTS PASSING: 2900+">
<rect x="0" y="0" width="140" height="48" rx="10" fill="#1A1A1A" stroke="#2A2A2A" stroke-width="1"/>
- <text x="70" y="24" fill="#00D26A" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="18" font-weight="900" text-anchor="middle" letter-spacing="-0.3">2700+</text>
+ <text x="70" y="24" fill="#00D26A" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="18" font-weight="900" text-anchor="middle" letter-spacing="-0.3">2900+</text>
<text x="70" y="38" fill="#9CA3AF" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="9" font-weight="600" text-anchor="middle" letter-spacing="1.5">TESTS PASSING</text>
</svg>
diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json
index 2e1b5e92..7ba2ceb9 100644
--- a/scripts/docs-sync.state.json
+++ b/scripts/docs-sync.state.json
@@ -20,19 +20,19 @@
"12"
],
"tests": [
- "2700+"
+ "2900+"
],
"functions": [
"312"
],
"sourceFiles": [
- "223"
+ "227"
],
"loc": [
- "53000"
+ "54000"
],
"kvScopes": [
- "60"
+ "62"
]
}
}
diff --git a/scripts/docs-sync.ts b/scripts/docs-sync.ts
index 967ad935..1bf67ae1 100644
--- a/scripts/docs-sync.ts
+++ b/scripts/docs-sync.ts
@@ -181,7 +181,7 @@ const FACTS: Fact[] = [
value: () => String(countKvScopes()),
nouns: [
"KV scopes", "KV-Scopes", "KV scope", "KV-scope", "scopes KV", "scopes de KV", "escopos KV", "областей KV", "個 KV", "个 KV", "개 KV", "KV スコープ",
- "KV kapsam", "نطاق KV", "KV স্কোপ", "תחומי KV", "KV-hatókör", "scope KV", "개", "zakresów KV", "âmbitos de KV", "domenii KV", "na KV scope",
+ "KV kapsam", "نطاق KV", "KV স্কোপ", "תחומי KV", "KV-hatókör", "scope KV", "개", "zakresów KV", "zakresy KV", "âmbitos de KV", "domenii KV", "de domenii KV", "na KV scope",
"KV-скоуп", "KV اسکوپ",
],
},
diff --git a/src/eval/schemas.ts b/src/eval/schemas.ts
index bf5bfca4..0d0d06f7 100644
--- a/src/eval/schemas.ts
+++ b/src/eval/schemas.ts
@@ -29,6 +29,7 @@ const ObservationTypeEnum = z.enum([
"subagent",
"notification",
"task",
+ "image",
"other",
]);
diff --git a/src/eval/self-correct.ts b/src/eval/self-correct.ts
index 68fc34db..e8966ac3 100644
--- a/src/eval/self-correct.ts
+++ b/src/eval/self-correct.ts
@@ -4,25 +4,31 @@ const STRICTER_SUFFIX = `
IMPORTANT: Your previous response was invalid. Please ensure your output strictly follows the required XML format. Every required field must be present with valid values.`;
-export async function compressWithRetry(
+type ValidationResult<T> =
+ | { valid: true; data: T }
+ | { valid: false; errors?: string[] };
+
+export async function compressWithRetry<T>(
provider: MemoryProvider,
systemPrompt: string,
userPrompt: string,
- validator: (response: string) => { valid: boolean; errors?: string[] },
+ validator: (response: string) => ValidationResult<T>,
maxRetries = 1,
-): Promise<{ response: string; retried: boolean }> {
+): Promise<ValidationResult<T> & { retried: boolean }> {
const first = await provider.compress(systemPrompt, userPrompt);
- const result = validator(first);
- if (result.valid) return { response: first, retried: false };
+ let result = validator(first);
+ if (result.valid) return { ...result, retried: false };
+ let retried = false;
for (let i = 0; i < maxRetries; i++) {
+ retried = true;
const retry = await provider.compress(
systemPrompt + STRICTER_SUFFIX,
userPrompt,
);
- const retryResult = validator(retry);
- if (retryResult.valid) return { response: retry, retried: true };
+ result = validator(retry);
+ if (result.valid) return { ...result, retried };
}
- return { response: first, retried: true };
+ return { ...result, retried };
}
diff --git a/src/functions/cascade.ts b/src/functions/cascade.ts
index b2959676..cfa65720 100644
--- a/src/functions/cascade.ts
+++ b/src/functions/cascade.ts
@@ -1,3 +1,4 @@
+import { pinGraphState } from "../state/graph-generation.js";
import type { IIIClient } from "iii-sdk";
import type { StateKV } from "../state/kv.js";
import { KV } from "../state/schema.js";
@@ -5,9 +6,10 @@ import { withKeyedLock } from "../state/keyed-mutex.js";
import type { Memory, GraphNode, GraphEdge } from "../types.js";
import { recordAudit } from "./audit.js";
-export function registerCascadeFunction(sdk: IIIClient, kv: StateKV): void {
+export function registerCascadeFunction(sdk: IIIClient, state: StateKV): void {
sdk.registerFunction("mem::cascade-update",
async (data: { supersededMemoryId: string }) => {
+ const kv = await pinGraphState(state);
if (!data.supersededMemoryId || typeof data.supersededMemoryId !== "string") {
return { success: false, error: "supersededMemoryId is required" };
}
diff --git a/src/functions/claude-bridge.ts b/src/functions/claude-bridge.ts
index 1c7c245e..c67f6db6 100644
--- a/src/functions/claude-bridge.ts
+++ b/src/functions/claude-bridge.ts
@@ -1,11 +1,62 @@
import type { IIIClient } from "iii-sdk";
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { dirname } from "node:path";
+import {
+ closeSync, constants, existsSync, fstatSync, linkSync, lstatSync,
+ mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync,
+} from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
import type { Memory, ClaudeBridgeConfig } from "../types.js";
import { KV } from "../state/schema.js";
import type { StateKV } from "../state/kv.js";
import { recordAudit } from "./audit.js";
import { logger } from "../logger.js";
+import { resolveProject } from "../hooks/_project.js";
+
+function hasIdenticalContent(path: string, content: string): boolean {
+ let fd: number | undefined;
+ try {
+ if (!lstatSync(path).isFile()) return false;
+ fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+ const opened = fstatSync(fd);
+ if (!opened.isFile()) return false;
+ const identical = readFileSync(fd, "utf-8") === content;
+ const current = lstatSync(path);
+ return identical && current.isFile() && current.dev === opened.dev && current.ino === opened.ino;
+ } catch {
+ return false;
+ } finally {
+ if (fd !== undefined) closeSync(fd);
+ }
+}
+
+function publishMemoryFile(path: string, content: string): "created" | "unchanged" {
+ const dir = dirname(path);
+ mkdirSync(dir, { recursive: true });
+ const temporaryPath = join(dir, `.agentmemory-${randomUUID()}.tmp`);
+ const fd = openSync(temporaryPath, "wx", 0o600);
+ try {
+ try {
+ writeFileSync(fd, content, "utf-8");
+ } finally {
+ closeSync(fd);
+ }
+ try {
+ // Publishing a complete inode with link never replaces a file created
+ // or edited by another process while the bridge was loading state.
+ linkSync(temporaryPath, path);
+ return "created";
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+ if (hasIdenticalContent(path, content)) return "unchanged";
+ throw new Error(
+ `Refusing to replace existing Claude memory file "${path}". ` +
+ "Existing files, including generated files, are preserved. Move or remove it deliberately before regenerating.",
+ );
+ }
+ } finally {
+ unlinkSync(temporaryPath);
+ }
+}
function parseMemoryMd(content: string): {
sections: Map<string, string>;
@@ -39,7 +90,7 @@ function serializeToMemoryMd(
lineBudget: number,
): string {
const lines: string[] = [];
- lines.push("# Agent Memory (auto-synced by agentmemory)");
+ lines.push("# Agent Memory (exported by agentmemory)");
lines.push("");
if (projectSummary) {
@@ -113,45 +164,47 @@ export function registerClaudeBridgeFunction(
sdk.registerFunction("mem::claude-bridge-sync",
async () => {
- if (!config.enabled || !config.memoryFilePath) {
+ if (!config.enabled || !config.memoryFilePath || !config.projectPath.trim()) {
return { success: false, error: "Claude bridge not configured" };
}
try {
+ const project = resolveProject(config.projectPath);
const memories = await kv.list<Memory>(KV.memories);
- const latestMemories = memories.filter((m) => m.isLatest);
-
- let projectSummary = "";
- if (config.projectPath) {
- const profile = await kv
- .get<{ summary?: string }>(KV.profiles, config.projectPath)
- .catch(() => null);
- projectSummary = profile?.summary || "";
+ const latestMemories = memories.filter(
+ (m) => m.isLatest && (m.project === project || m.project === config.projectPath),
+ );
+
+ let profile = await kv
+ .get<{ summary?: string }>(KV.profiles, config.projectPath)
+ .catch(() => null);
+ if (!profile && project !== config.projectPath) {
+ profile = await kv.get<{ summary?: string }>(KV.profiles, project).catch(() => null);
}
const md = serializeToMemoryMd(
latestMemories,
- projectSummary,
+ profile?.summary || "",
config.lineBudget,
);
+ const lines = md.split("\n").length;
- const dir = dirname(config.memoryFilePath);
- if (!existsSync(dir)) {
- mkdirSync(dir, { recursive: true });
+ const action = publishMemoryFile(config.memoryFilePath, md);
+ if (action === "unchanged") {
+ return { success: true, path: config.memoryFilePath, lines, changed: false };
}
- writeFileSync(config.memoryFilePath, md, "utf-8");
await recordAudit(kv, "export", "mem::claude-bridge-sync", [], {
path: config.memoryFilePath,
memoryCount: latestMemories.length,
- lines: md.split("\n").length,
+ lines,
});
logger.info("Claude bridge: synced to MEMORY.md", {
path: config.memoryFilePath,
memories: latestMemories.length,
});
- return { success: true, path: config.memoryFilePath, lines: md.split("\n").length };
+ return { success: true, path: config.memoryFilePath, lines, changed: true };
} catch (err) {
const msg = err instanceof Error ? err.message : String(err);
logger.error("Claude bridge sync failed", { error: msg });
diff --git a/src/functions/compress.ts b/src/functions/compress.ts
index eb30b1ce..6771dc61 100644
--- a/src/functions/compress.ts
+++ b/src/functions/compress.ts
@@ -4,7 +4,6 @@ import { isManagedImagePath } from "../utils/image-store.js";
import type {
RawObservation,
CompressedObservation,
- ObservationType,
MemoryProvider,
} from "../types.js";
import { KV, STREAM } from "../state/schema.js";
@@ -14,7 +13,7 @@ import {
buildCompressionPrompt,
} from "../prompts/compression.js";
import { VISION_DESCRIPTION_PROMPT } from "../prompts/vision.js";
-import { getXmlTag, getXmlChildren } from "../prompts/xml.js";
+import { parseCompressionXml } from "../prompts/compression-output.js";
import { getSearchIndex, scheduleIndexSave, vectorIndexAddGuarded } from "./search.js";
import { CompressOutputSchema } from "../eval/schemas.js";
import { validateOutput } from "../eval/validator.js";
@@ -27,47 +26,6 @@ import { budgetLiveObservationSource } from "./observation-source-budget.js";
import { withKeyedLock } from "../state/keyed-mutex.js";
import { scrubRecord, stripPrivateData } from "./privacy.js";
-const VALID_TYPES = new Set<string>([
- "file_read",
- "file_write",
- "file_edit",
- "command_run",
- "search",
- "web_fetch",
- "conversation",
- "error",
- "decision",
- "discovery",
- "subagent",
- "notification",
- "task",
- "image",
- "other",
-]);
-
-function parseCompressionXml(
- xml: string,
-): Omit<CompressedObservation, "id" | "sessionId" | "timestamp"> | null {
- const rawType = getXmlTag(xml, "type");
- const title = getXmlTag(xml, "title");
- if (!rawType || !title) return null;
- const type = VALID_TYPES.has(rawType) ? rawType : "other";
-
- return {
- type: type as ObservationType,
- title,
- subtitle: getXmlTag(xml, "subtitle") || undefined,
- facts: getXmlChildren(xml, "facts", "fact"),
- narrative: getXmlTag(xml, "narrative"),
- concepts: getXmlChildren(xml, "concepts", "concept"),
- files: getXmlChildren(xml, "files", "file"),
- importance: Math.max(
- 1,
- Math.min(10, parseInt(getXmlTag(xml, "importance") || "5", 10) || 5),
- ),
- };
-}
-
export function registerCompressFunction(
sdk: IIIClient,
kv: StateKV,
@@ -129,18 +87,18 @@ export function registerCompressFunction(
try {
const validator = (response: string) => {
const parsed = parseCompressionXml(response);
- if (!parsed) return { valid: false, errors: ["xml_parse_failed"] };
+ if (!parsed) return { valid: false as const, errors: ["xml_parse_failed"] };
const result = validateOutput(
CompressOutputSchema,
- parsed,
+ scrubRecord(parsed),
"mem::compress",
);
return result.valid
- ? { valid: true }
- : { valid: false, errors: result.result.errors };
+ ? result
+ : { valid: false as const, errors: result.result.errors };
};
- const { response, retried } = await compressWithRetry(
+ const result = await compressWithRetry(
provider,
COMPRESSION_SYSTEM,
prompt,
@@ -148,19 +106,22 @@ export function registerCompressFunction(
1,
);
- const parsed = parseCompressionXml(response);
- if (!parsed) {
+ if (!result.valid) {
const latencyMs = Date.now() - startMs;
if (metricsStore) {
await metricsStore.record("mem::compress", latencyMs, false);
}
- logger.warn("Failed to parse compression XML", {
+ logger.warn("Compression output rejected after validation", {
obsId: data.observationId,
- retried,
+ retried: result.retried,
});
- return { success: false, error: "parse_failed" };
+ return {
+ success: false,
+ error: result.errors?.includes("xml_parse_failed") ? "parse_failed" : "validation_failed",
+ };
}
+ const parsed = result.data;
const qualityScore = scoreCompression(parsed);
const candidate: CompressedObservation = {
@@ -168,7 +129,7 @@ export function registerCompressFunction(
sessionId: data.sessionId,
timestamp: data.raw.timestamp,
compressedAt: new Date().toISOString(),
- ...scrubRecord(parsed),
+ ...parsed,
confidence: qualityScore / 100,
source: createObservationSource(data.raw),
...(hasImage ? { modality: data.raw.modality } : {}),
@@ -250,7 +211,7 @@ export function registerCompressFunction(
type: compressed.type,
importance: compressed.importance,
qualityScore,
- retried,
+ retried: result.retried,
});
return { success: true, compressed: withoutObservationSource(compressed), qualityScore };
diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts
index c2a0add0..c7938f21 100644
--- a/src/functions/export-import.ts
+++ b/src/functions/export-import.ts
@@ -1,3 +1,5 @@
+import { pinGraphState } from "../state/graph-generation.js";
+import { persistGraphRecords, validateGraphRecords } from "../state/graph-ingestion.js";
import type { IIIClient } from "iii-sdk";
import { markCaptureEventDeleted } from "../capture/event-record.js";
import type {
@@ -34,14 +36,13 @@ import {
indexObservationSession,
unindexObservationSession,
} from "../state/obs-index.js";
-import { withKeyedLock, withKeyedLocks } from "../state/keyed-mutex.js";
+import { withKeyedLocks } from "../state/keyed-mutex.js";
import { VERSION } from "../version.js";
import { recordAudit } from "./audit.js";
import { indexRecords } from "./search.js";
import { resetLessonIndex } from "./lessons.js";
import { logger } from "../logger.js";
import { budgetImportedObservationSources } from "./observation-source-budget.js";
-import { boundRecordSources } from "./graph.js";
// Bounded-concurrency chunk size for the import delete/write loops. A
// "replace" or "merge" of a large export (up to MAX_TOTAL_OBSERVATIONS,
@@ -103,9 +104,10 @@ export class ExportBudget {
}
}
-export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void {
+export function registerExportImportFunction(sdk: IIIClient, state: StateKV): void {
sdk.registerFunction("mem::export",
async (data?: { maxSessions?: number; offset?: number }) => {
+ const kv = await pinGraphState(state);
const rawMax = Number(data?.maxSessions);
const maxSessions = Number.isFinite(rawMax) && rawMax > 0 ? Math.min(Math.floor(rawMax), 1000) : undefined;
const rawOffset = Number(data?.offset);
@@ -216,6 +218,7 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void
exportData: ExportData;
strategy?: "merge" | "replace" | "skip";
}) => {
+ const kv = await pinGraphState(state);
if (
!data?.exportData ||
typeof data.exportData !== "object" ||
@@ -304,6 +307,11 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void
error: `Too many total observations (max ${MAX_TOTAL_OBSERVATIONS})`,
};
}
+ try {
+ validateGraphRecords(importData.graphNodes ?? [], importData.graphEdges ?? []);
+ } catch (error) {
+ return { success: false, error: error instanceof Error ? error.message : String(error) };
+ }
const stats = {
sessions: 0,
@@ -409,18 +417,6 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void
await kv.list<Insight>(KV.insights).catch(() => []),
(i) => kv.delete(KV.insights, i.id),
);
- await withKeyedLock("graph:persist", async () =>
- runChunked(
- await kv.list<{ id: string }>(KV.graphNodes).catch(() => []),
- (n) => kv.delete(KV.graphNodes, n.id),
- ),
- );
- await withKeyedLock("graph:persist", async () =>
- runChunked(
- await kv.list<{ id: string }>(KV.graphEdges).catch(() => []),
- (e) => kv.delete(KV.graphEdges, e.id),
- ),
- );
await runChunked(
await kv.list<{ id: string }>(KV.semantic).catch(() => []),
(s) => kv.delete(KV.semantic, s.id),
@@ -512,27 +508,12 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void
stats.summaries++;
});
- if (importData.graphNodes) {
- await withKeyedLock("graph:persist", () =>
- runChunked(importData.graphNodes!, async (node) => {
- if (strategy === "skip") {
- const existing = await kv.get(KV.graphNodes, node.id).catch(() => null);
- if (existing) { stats.skipped++; return; }
- }
- await kv.set(KV.graphNodes, node.id, boundRecordSources(node));
- }),
- );
- }
- if (importData.graphEdges) {
- await withKeyedLock("graph:persist", () =>
- runChunked(importData.graphEdges!, async (edge) => {
- if (strategy === "skip") {
- const existing = await kv.get(KV.graphEdges, edge.id).catch(() => null);
- if (existing) { stats.skipped++; return; }
- }
- await kv.set(KV.graphEdges, edge.id, boundRecordSources(edge));
- }),
- );
+ if (strategy === "replace" || importData.graphNodes || importData.graphEdges) {
+ const graph = await persistGraphRecords(kv, importData.graphNodes ?? [], importData.graphEdges ?? [], {
+ mode: strategy === "skip" ? "skip" : "merge",
+ replace: strategy === "replace",
+ });
+ stats.skipped += graph.nodesSkipped + graph.edgesSkipped;
}
if (importData.semanticMemories) {
await runChunked(importData.semanticMemories, async (sem) => {
diff --git a/src/functions/graph-import.ts b/src/functions/graph-import.ts
index f9a9a9fd..b6f70ae5 100644
--- a/src/functions/graph-import.ts
+++ b/src/functions/graph-import.ts
@@ -5,6 +5,7 @@ import type { IIIClient } from "iii-sdk";
import type { GraphEdge, GraphEdgeType, GraphNode, GraphNodeType } from "../types.js";
import { KV, generateId } from "../state/schema.js";
import type { StateKV } from "../state/kv.js";
+import { pinGraphState } from "../state/graph-generation.js";
import { persistGraphDelta } from "./graph.js";
import { recordAudit } from "./audit.js";
import { logger } from "../logger.js";
@@ -193,10 +194,11 @@ export function parseGraphifyGraph(raw: string): {
};
}
-export function registerGraphImportFunction(sdk: IIIClient, kv: StateKV): void {
+export function registerGraphImportFunction(sdk: IIIClient, state: StateKV): void {
sdk.registerFunction(
"mem::graph::import-graphify",
async (data?: { path?: string; cwd?: string }): Promise<GraphifyImportResult> => {
+ const kv = await pinGraphState(state);
const explicitPath = typeof data?.path === "string" ? data.path : undefined;
const cwd = typeof data?.cwd === "string" ? data.cwd : process.cwd();
const requested = explicitPath ?? join(cwd, "graphify-out", "graph.json");
diff --git a/src/functions/graph-node.ts b/src/functions/graph-node.ts
index 98caea47..5c782c6c 100644
--- a/src/functions/graph-node.ts
+++ b/src/functions/graph-node.ts
@@ -1,4 +1,5 @@
import type { StateKV } from "../state/kv.js";
+import { pinGraphState } from "../state/graph-generation.js";
import { KV } from "../state/schema.js";
import type { CompressedObservation, GraphEdge, GraphNode, Memory, Session } from "../types.js";
import { getSearchIndex } from "./search.js";
@@ -53,6 +54,7 @@ function matchesName(values: string[] | undefined, name: string): boolean {
}
export async function describeGraphNode(kv: StateKV, nodeId: string): Promise<GraphNodeDetail | null> {
+ kv = await pinGraphState(kv);
const node = await kv.get<GraphNode>(KV.graphNodes, nodeId);
if (!node) return null;
diff --git a/src/functions/graph-retrieval.ts b/src/functions/graph-retrieval.ts
index b12a9d8a..67fbc76e 100644
--- a/src/functions/graph-retrieval.ts
+++ b/src/functions/graph-retrieval.ts
@@ -1,3 +1,4 @@
+import { pinGraphState } from "../state/graph-generation.js";
import type {
GraphNode,
GraphEdge,
@@ -48,8 +49,9 @@ export class GraphRetrieval {
maxResults = 20,
targetLayer: SearchLayer = "all",
): Promise<GraphRetrievalResult[]> {
- const allNodes = (await this.kv.list<GraphNode>(KV.graphNodes)).filter((n) => !n.stale);
- const allEdges = (await this.kv.list<GraphEdge>(KV.graphEdges)).filter((e) => !e.stale);
+ const kv = await pinGraphState(this.kv);
+ const allNodes = (await kv.list<GraphNode>(KV.graphNodes)).filter((n) => !n.stale);
+ const allEdges = (await kv.list<GraphEdge>(KV.graphEdges)).filter((e) => !e.stale);
const matchingNodes = allNodes.filter((n) => {
const nameLower = n.name.toLowerCase();
@@ -122,8 +124,9 @@ export class GraphRetrieval {
maxResults = 10,
targetLayer: SearchLayer = "all",
): Promise<GraphRetrievalResult[]> {
- const allNodes = (await this.kv.list<GraphNode>(KV.graphNodes)).filter((n) => !n.stale);
- const allEdges = (await this.kv.list<GraphEdge>(KV.graphEdges)).filter((e) => !e.stale);
+ const kv = await pinGraphState(this.kv);
+ const allNodes = (await kv.list<GraphNode>(KV.graphNodes)).filter((n) => !n.stale);
+ const allEdges = (await kv.list<GraphEdge>(KV.graphEdges)).filter((e) => !e.stale);
const linkedNodes = allNodes.filter((n) =>
n.sourceObservationIds.some((id) => obsIds.includes(id)),
@@ -166,8 +169,9 @@ export class GraphRetrieval {
currentState: GraphEdge[];
history: GraphEdge[];
}> {
- const allNodes = (await this.kv.list<GraphNode>(KV.graphNodes)).filter((n) => !n.stale);
- const allEdges = (await this.kv.list<GraphEdge>(KV.graphEdges)).filter((e) => !e.stale);
+ const kv = await pinGraphState(this.kv);
+ const allNodes = (await kv.list<GraphNode>(KV.graphNodes)).filter((n) => !n.stale);
+ const allEdges = (await kv.list<GraphEdge>(KV.graphEdges)).filter((e) => !e.stale);
const entity = allNodes.find(
(n) => n.name.toLowerCase() === entityName.toLowerCase(),
diff --git a/src/functions/graph.ts b/src/functions/graph.ts
index 5b26530e..993e87c2 100644
--- a/src/functions/graph.ts
+++ b/src/functions/graph.ts
@@ -1,3 +1,4 @@
+import { isLegacyGraphState, pinGraphState, resetGraphGeneration } from "../state/graph-generation.js";
import type { IIIClient } from "iii-sdk";
import type {
GraphNode,
@@ -182,11 +183,12 @@ function paginateFromSnapshot(
depth: 0,
totalNodes: total,
totalEdges: snap.stats.totalEdges,
- truncated: total > pageNodes.length,
+ truncated: total > pageNodes.length || snap.sampleIncomplete === true,
limit,
offset,
fromSnapshot: true,
degrees,
+ ...(snap.sampleIncomplete ? { warning: "Graph counts are current; the bounded snapshot sample may omit nodes or edges after replacements. Use a graph search for specific entities." } : {}),
};
}
@@ -552,10 +554,12 @@ export async function persistGraphDelta(
rawNodes: GraphNode[],
rawEdges: GraphEdge[],
): Promise<{ newNodeCount: number; newEdgeCount: number }> {
+ kv = await pinGraphState(kv);
const nodes = rawNodes.map((node) => scrubRecord(node));
const edges = rawEdges.map((edge) => scrubRecord(edge));
return withKeyedLock("graph:persist", async () => {
const snap = (await readSnapshotStrict(kv)) ?? emptySnapshot();
+ const legacyResetAt = await isLegacyGraphState(kv) ? snap.resetAt : undefined;
const capturedAt = new Date().toISOString();
let newNodeCount = 0;
let newEdgeCount = 0;
@@ -578,9 +582,9 @@ export async function persistGraphDelta(
existing = await kv.get<GraphNode>(KV.graphNodes, existingId);
if (
existing &&
- snap.resetAt &&
+ legacyResetAt &&
typeof existing.createdAt === "string" &&
- existing.createdAt < snap.resetAt
+ existing.createdAt < legacyResetAt
) {
existing = null;
}
@@ -629,9 +633,9 @@ export async function persistGraphDelta(
existing = await kv.get<GraphEdge>(KV.graphEdges, existingId);
if (
existing &&
- snap.resetAt &&
+ legacyResetAt &&
typeof existing.createdAt === "string" &&
- existing.createdAt < snap.resetAt
+ existing.createdAt < legacyResetAt
) {
existing = null;
}
@@ -705,6 +709,7 @@ export async function compactGraphProvenance(
kv: StateKV,
opts: GraphCompactOptions = {},
): Promise<GraphCompactResult> {
+ kv = await pinGraphState(kv);
const { scope } = opts;
if (scope !== undefined && !COMPACT_SCOPES.includes(scope)) {
throw new Error(`unknown compact scope: ${String(scope)}`);
@@ -807,11 +812,13 @@ export async function compactGraphProvenance(
export function registerGraphFunction(
sdk: IIIClient,
- kv: StateKV,
+ state: StateKV,
provider: MemoryProvider,
): void {
+ const kv = state;
sdk.registerFunction("mem::graph-extract",
async (data: { observations: CompressedObservation[] }) => {
+ const kv = await pinGraphState(state);
if (!data.observations || data.observations.length === 0) {
return { success: false, error: "No observations provided" };
}
@@ -904,6 +911,7 @@ export function registerGraphFunction(
limit?: number;
offset?: number;
}): Promise<GraphQueryResult> => {
+ const kv = await pinGraphState(state);
const maxDepth = Math.min(data.maxDepth || 3, 5);
const { limit, offset } = resolvePagination(data.limit, data.offset);
@@ -1038,6 +1046,7 @@ export function registerGraphFunction(
);
sdk.registerFunction("mem::graph-stats", async () => {
+ const kv = await pinGraphState(state);
const snap = await readSnapshot(kv);
if (snap) {
return {
@@ -1069,6 +1078,7 @@ export function registerGraphFunction(
sdk.registerFunction(
"mem::graph-snapshot-rebuild",
async (data?: { force?: boolean }) => {
+ const kv = await pinGraphState(state);
const started = Date.now();
const forceRebuild = data?.force === true;
try {
@@ -1190,6 +1200,7 @@ export function registerGraphFunction(
});
sdk.registerFunction("mem::graph-compact", async (data?: GraphCompactOptions) => {
+ const kv = await pinGraphState(state);
const started = Date.now();
try {
const result = await compactGraphProvenance(kv, data ?? {});
@@ -1217,24 +1228,28 @@ export function registerGraphFunction(
sdk.registerFunction("mem::graph-reset", async () => {
const started = Date.now();
- // Stamp resetAt=now on the empty snapshot. Future
- // mem::graph-extract calls compare each name-index lookup's
- // existing node `createdAt` against this timestamp; anything
- // older counts as an orphan and is dropped from the merge path,
- // forcing extract to write a fresh row instead of reconnecting
- // to a pre-reset entry.
+ // Publish a fresh namespace without enumerating or deleting the old graph.
const resetSnapshot: GraphSnapshot = {
...emptySnapshot(),
resetAt: new Date().toISOString(),
+ updatedAt: new Date().toISOString(),
+ dirty: false,
};
await withKeyedLock("graph:persist", () =>
- kv.set(KV.graphSnapshot, SNAPSHOT_KEY, resetSnapshot),
+ resetGraphGeneration(kv, resetSnapshot),
);
const counts: Record<string, number> = {
[KV.graphSnapshot]: 1,
};
const tookMs = Date.now() - started;
logger.info("Graph state reset", { counts, tookMs });
- return { success: true, cleared: counts, tookMs };
+ return {
+ success: true,
+ cleared: counts,
+ resetMode: "generation",
+ physicalStorageRetained: true,
+ message: "The active graph is empty. Previous graph storage is retained; this operation does not reclaim disk space.",
+ tookMs,
+ };
});
}
diff --git a/src/functions/mesh.ts b/src/functions/mesh.ts
index 444e5105..794a004d 100644
--- a/src/functions/mesh.ts
+++ b/src/functions/mesh.ts
@@ -1,9 +1,10 @@
+import { pinGraphState } from "../state/graph-generation.js";
+import { persistGraphRecords } from "../state/graph-ingestion.js";
import type { IIIClient } from "iii-sdk";
import type { StateKV } from "../state/kv.js";
import { KV, generateId } from "../state/schema.js";
import { withKeyedLock } from "../state/keyed-mutex.js";
import { recordAudit } from "./audit.js";
-import { boundRecordSources } from "./graph.js";
import type {
MeshPeer,
Memory,
@@ -110,65 +111,12 @@ function graphNodeTs(node: GraphNode): string {
return node.updatedAt || node.createdAt;
}
-async function lwwMergeGraphNodes(
- kv: StateKV,
- items: GraphNode[] | undefined,
-): Promise<number> {
- if (!items || !Array.isArray(items)) return 0;
- let count = 0;
- for (const item of items) {
- if (!item.id || typeof item.id !== "string") continue;
- const ts = graphNodeTs(item);
- if (!ts || Number.isNaN(new Date(ts).getTime())) continue;
- const wrote = await withKeyedLock("graph:persist", async () => {
- const existing = await kv.get<GraphNode>(KV.graphNodes, item.id);
- if (!existing) {
- await kv.set(KV.graphNodes, item.id, boundRecordSources(item));
- return true;
- }
- if (new Date(ts) > new Date(graphNodeTs(existing))) {
- await kv.set(KV.graphNodes, item.id, boundRecordSources(item));
- return true;
- }
- return false;
- });
- if (wrote) count++;
- }
- return count;
-}
-
-async function lwwMergeGraphEdges(
- kv: StateKV,
- items: GraphEdge[] | undefined,
-): Promise<number> {
- if (!items || !Array.isArray(items)) return 0;
- let count = 0;
- for (const item of items) {
- if (!item.id || typeof item.id !== "string") continue;
- const ts = item.createdAt;
- if (!ts || Number.isNaN(new Date(ts).getTime())) continue;
- const wrote = await withKeyedLock("graph:persist", async () => {
- const existing = await kv.get<GraphEdge>(KV.graphEdges, item.id);
- if (!existing) {
- await kv.set(KV.graphEdges, item.id, boundRecordSources(item));
- return true;
- }
- if (new Date(ts) > new Date(existing.createdAt)) {
- await kv.set(KV.graphEdges, item.id, boundRecordSources(item));
- return true;
- }
- return false;
- });
- if (wrote) count++;
- }
- return count;
-}
-
export function registerMeshFunction(
sdk: IIIClient,
- kv: StateKV,
+ state: StateKV,
meshAuthToken?: string,
): void {
+ const kv = state;
sdk.registerFunction("mem::mesh-register",
async (data: {
url: string;
@@ -223,6 +171,7 @@ export function registerMeshFunction(
sdk.registerFunction("mem::mesh-sync",
async (data: { peerId?: string; scopes?: string[]; direction?: "push" | "pull" | "both" }) => {
+ const kv = await pinGraphState(state);
if (!meshAuthToken) {
return {
success: false,
@@ -362,6 +311,7 @@ export function registerMeshFunction(
sdk.registerFunction("mem::mesh-receive",
async (data: MeshSyncPayload) => {
+ const kv = await pinGraphState(state);
if (!data || typeof data !== "object") {
return { success: false, error: "payload required" };
}
@@ -388,8 +338,13 @@ export function registerMeshFunction(
});
}
}
- accepted += await lwwMergeGraphNodes(kv, data.graphNodes);
- accepted += await lwwMergeGraphEdges(kv, data.graphEdges);
+ const graph = await persistGraphRecords(
+ kv,
+ Array.isArray(data.graphNodes) ? data.graphNodes : [],
+ Array.isArray(data.graphEdges) ? data.graphEdges : [],
+ { mode: "lww" },
+ );
+ accepted += graph.nodesWritten + graph.edgesWritten;
await recordAudit(kv, "mesh_sync", "mem::mesh-receive", [], {
action: "mesh.receive",
accepted,
@@ -512,12 +467,13 @@ async function applySyncData(
if (wrote) applied++;
}
}
- if (scopes.includes("graph:nodes")) {
- applied += await lwwMergeGraphNodes(kv, data.graphNodes);
- }
- if (scopes.includes("graph:edges")) {
- applied += await lwwMergeGraphEdges(kv, data.graphEdges);
- }
+ const graph = await persistGraphRecords(
+ kv,
+ scopes.includes("graph:nodes") && Array.isArray(data.graphNodes) ? data.graphNodes : [],
+ scopes.includes("graph:edges") && Array.isArray(data.graphEdges) ? data.graphEdges : [],
+ { mode: "lww" },
+ );
+ applied += graph.nodesWritten + graph.edgesWritten;
return applied;
}
diff --git a/src/functions/reflect.ts b/src/functions/reflect.ts
index b93a5dc0..be0a0ada 100644
--- a/src/functions/reflect.ts
+++ b/src/functions/reflect.ts
@@ -1,3 +1,4 @@
+import { pinGraphState } from "../state/graph-generation.js";
import type { IIIClient } from "iii-sdk";
import type { StateKV } from "../state/kv.js";
import { KV, fingerprintId } from "../state/schema.js";
@@ -162,11 +163,13 @@ function buildJaccardClusters(
export function registerReflectFunctions(
sdk: IIIClient,
- kv: StateKV,
+ state: StateKV,
provider: MemoryProvider,
): void {
+ const kv = state;
sdk.registerFunction("mem::reflect",
async (data: { maxClusters?: number; project?: string }) => {
+ const kv = await pinGraphState(state);
const maxClusters = Math.min(data?.maxClusters ?? 10, 20);
const maxInsightsPerCluster = 5;
const maxTotal = 50;
diff --git a/src/functions/remember.ts b/src/functions/remember.ts
index b6720742..8fcfa07e 100644
--- a/src/functions/remember.ts
+++ b/src/functions/remember.ts
@@ -214,10 +214,10 @@ export function registerRememberFunction(sdk: IIIClient, kv: StateKV): void {
memory.sessionIds?.[0] ?? "memory",
memory.title + " " + memory.content,
{ kind: "memory", logId: memory.id },
- (embedding) =>
+ (embedding, isCurrent) =>
withKeyedLock("mem:remember", async () => {
const current = await kv.get<Memory>(KV.memories, memory.id);
- if (!current || current.isLatest === false) return false;
+ if (!isCurrent() || !current || current.isLatest === false) return false;
getVectorIndex()?.add(
memory.id,
memory.sessionIds?.[0] ?? "memory",
diff --git a/src/functions/search.ts b/src/functions/search.ts
index 8223f2e2..bae04b6c 100644
--- a/src/functions/search.ts
+++ b/src/functions/search.ts
@@ -4,7 +4,7 @@ import type { CompressedObservation, Memory, SearchResult, Session } from '../ty
import { KV } from '../state/schema.js'
import { StateKV } from '../state/kv.js'
import { getSearchResultLayer, isSearchLayer, matchesSearchLayer, type SearchLayer, type SearchResultLayer } from "../state/search-layer.js";
-import { SearchIndex } from '../state/search-index.js'
+import { SearchIndex, type SearchIndexRevision } from '../state/search-index.js'
import { VectorIndex } from '../state/vector-index.js'
import type { EmbeddingProvider } from '../types.js'
import { memoryToObservation } from '../state/memory-utils.js'
@@ -146,6 +146,7 @@ export async function rankMemoryIds(
}
export function vectorIndexRemove(id: string): void {
+ getSearchIndex().invalidateRevision(id);
vectorIndex?.remove(id);
}
@@ -204,40 +205,22 @@ export async function vectorIndexAddGuarded(
sessionId: string,
text: string,
context: { kind: "memory" | "observation" | "synthetic"; logId: string },
- commit?: (embedding: Float32Array) => Promise<boolean> | boolean,
+ commit?: (embedding: Float32Array, isCurrent: () => boolean) => Promise<boolean> | boolean,
): Promise<boolean> {
const vi = vectorIndex
const ep = currentEmbeddingProvider
if (!vi || !ep) return false
- let embedding: Float32Array
+ const keyword = getSearchIndex()
+ const revision = keyword.watchRevision(id)
+ const previous = vi.get(id)
+ const isCurrent = () => vectorIndex === vi && currentEmbeddingProvider === ep &&
+ revision.isCurrent() && vi.get(id) === previous
try {
- embedding = await ep.embed(clipEmbedInput(text))
- } catch (err) {
- logger.warn("vector-index add: embed failed — skipping", {
- kind: context.kind,
- id: context.logId,
- provider: ep.name,
- error: err instanceof Error ? err.message : String(err),
- })
- return false
- }
- if (embedding.length !== ep.dimensions) {
- logger.warn("vector-index add: dimension mismatch — skipping", {
- kind: context.kind,
- id: context.logId,
- provider: ep.name,
- expected: ep.dimensions,
- received: embedding.length,
- })
- return false
- }
- if (commit) {
+ let embedding: Float32Array
try {
- const committed = await commit(embedding)
- if (committed) scheduleIndexSave()
- return committed
+ embedding = await ep.embed(clipEmbedInput(text))
} catch (err) {
- logger.warn("vector-index add: commit failed — skipping", {
+ logger.warn("vector-index add: embed failed — skipping", {
kind: context.kind,
id: context.logId,
provider: ep.name,
@@ -245,10 +228,38 @@ export async function vectorIndexAddGuarded(
})
return false
}
+ if (!isCurrent()) return false
+ if (embedding.length !== ep.dimensions) {
+ logger.warn("vector-index add: dimension mismatch — skipping", {
+ kind: context.kind,
+ id: context.logId,
+ provider: ep.name,
+ expected: ep.dimensions,
+ received: embedding.length,
+ })
+ return false
+ }
+ if (commit) {
+ try {
+ const committed = await commit(embedding, isCurrent)
+ if (committed) scheduleIndexSave()
+ return committed
+ } catch (err) {
+ logger.warn("vector-index add: commit failed — skipping", {
+ kind: context.kind,
+ id: context.logId,
+ provider: ep.name,
+ error: err instanceof Error ? err.message : String(err),
+ })
+ return false
+ }
+ }
+ vi.add(id, sessionId, embedding)
+ scheduleIndexSave()
+ return true
+ } finally {
+ revision.release()
}
- vi.add(id, sessionId, embedding)
- scheduleIndexSave()
- return true
}
// Batched variant: calls EmbeddingProvider.embedBatch ONCE for the whole
@@ -262,70 +273,72 @@ export async function vectorIndexAddGuarded(
// - whole-batch network/provider error → all skipped, single warn line
// - per-item dimension mismatch → that item skipped, others continue
export async function vectorIndexAddBatchGuarded(
- items: Array<{
- id: string
- sessionId: string
- text: string
- context: { kind: "memory" | "observation" | "synthetic"; logId: string }
- }>,
-): Promise<{ ok: number; fail: number }> {
+ items: VectorBackfillJob[],
+): Promise<{ ok: number; fail: number; skipped: number }> {
const vi = vectorIndex
const ep = currentEmbeddingProvider
- if (!vi || !ep || items.length === 0) return { ok: 0, fail: 0 }
-
- let embeddings: Float32Array[]
+ if (!vi || !ep || items.length === 0) return { ok: 0, fail: 0, skipped: 0 }
+ const keyword = getSearchIndex()
+ const guarded = items.map((item) => ({ item, revision: item.revision ?? keyword.watchRevision(item.id), previous: vi.get(item.id) }))
+ const isCurrent = (job: typeof guarded[number]) => vectorIndex === vi && currentEmbeddingProvider === ep &&
+ job.revision.isCurrent() && vi.get(job.item.id) === job.previous
try {
- embeddings = await ep.embedBatch(items.map((i) => clipEmbedInput(i.text)))
- } catch (err) {
- logger.warn("vector-index add batch: embed failed — skipping batch", {
- batchSize: items.length,
- provider: ep.name,
- error: err instanceof Error ? err.message : String(err),
- })
- return { ok: 0, fail: items.length }
- }
-
- if (embeddings.length !== items.length) {
- logger.warn(
- "vector-index add batch: provider returned wrong length — skipping batch",
- {
- batchSize: items.length,
- returned: embeddings.length,
- provider: ep.name,
- },
- )
- return { ok: 0, fail: items.length }
- }
-
- let ok = 0
- let fail = 0
- for (let i = 0; i < items.length; i++) {
- const item = items[i]
- const embedding = embeddings[i]
- if (embedding.length !== ep.dimensions) {
- logger.warn("vector-index add batch: dimension mismatch — skipping item", {
- kind: item.context.kind,
- id: item.context.logId,
- provider: ep.name,
- expected: ep.dimensions,
- received: embedding.length,
- })
- fail++
- continue
+ const active = guarded.filter(isCurrent)
+ let skipped = items.length - active.length
+ if (!active.length) return { ok: 0, fail: 0, skipped }
+ const failedBatch = () => {
+ const fail = active.filter(isCurrent).length
+ return { ok: 0, fail, skipped: items.length - fail }
}
+
+ let embeddings: Float32Array[]
try {
- vi.add(item.id, item.sessionId, embedding)
- ok++
+ embeddings = await ep.embedBatch(active.map(({ item }) => clipEmbedInput(item.text)))
} catch (err) {
- logger.warn("vector-index add batch: index write failed — skipping item", {
- kind: item.context.kind,
- id: item.context.logId,
+ logger.warn("vector-index add batch: embed failed — skipping batch", {
+ batchSize: active.length,
+ provider: ep.name,
error: err instanceof Error ? err.message : String(err),
})
- fail++
+ return failedBatch()
+ }
+ if (embeddings.length !== active.length) {
+ logger.warn("vector-index add batch: provider returned wrong length — skipping batch", {
+ batchSize: active.length, returned: embeddings.length, provider: ep.name,
+ })
+ return failedBatch()
+ }
+
+ let ok = 0
+ let fail = 0
+ for (let i = 0; i < active.length; i++) {
+ const job = active[i]
+ if (!isCurrent(job)) { skipped++; continue }
+ const item = job.item
+ const embedding = embeddings[i]
+ if (embedding.length !== ep.dimensions) {
+ logger.warn("vector-index add batch: dimension mismatch — skipping item", {
+ kind: item.context.kind, id: item.context.logId, provider: ep.name,
+ expected: ep.dimensions, received: embedding.length,
+ })
+ fail++
+ continue
+ }
+ try {
+ vi.add(item.id, item.sessionId, embedding)
+ ok++
+ } catch (err) {
+ logger.warn("vector-index add batch: index write failed — skipping item", {
+ kind: item.context.kind, id: item.context.logId,
+ error: err instanceof Error ? err.message : String(err),
+ })
+ fail++
+ }
}
+ return { ok, fail, skipped }
+ } finally {
+ for (const job of guarded) if (!job.item.revision) job.revision.release()
}
- return { ok, fail }
}
// Embed-batch size for rebuild. Each item is one /v1/embeddings call's
@@ -358,50 +371,56 @@ export async function indexRecords(
const idx = getSearchIndex()
const vectorEnabled = Boolean(vectorIndex && currentEmbeddingProvider)
const batchSize = getRebuildEmbedBatchSize()
- type EmbedJob = {
- id: string
- sessionId: string
- text: string
- context: { kind: "memory" | "observation" | "synthetic"; logId: string }
- }
- const pending: EmbedJob[] = []
- const flush = async (): Promise<void> => {
- if (pending.length === 0) return
- await vectorIndexAddBatchGuarded(pending)
- pending.length = 0
- }
- const enqueue = async (job: EmbedJob): Promise<void> => {
- if (!vectorEnabled) return
- pending.push(job)
- if (pending.length >= batchSize) await flush()
- }
-
+ const revisions = new Map<Memory | CompressedObservation, SearchIndexRevision>()
let count = 0
for (const memory of memories) {
- if (memory.isLatest === false) continue
- if (!memory.title || !memory.content) continue
+ if (memory.isLatest === false || !memory.title || !memory.content) continue
idx.add(memoryToObservation(memory), "memory")
- await enqueue({
- id: memory.id,
- sessionId: memory.sessionIds?.[0] ?? 'memory',
- text: memory.title + ' ' + memory.content,
- context: { kind: "memory", logId: memory.id },
- })
+ if (vectorEnabled) revisions.set(memory, idx.watchRevision(memory.id))
count++
}
for (const obs of observations) {
if (!obs.title || !obs.narrative) continue
idx.add(obs)
- await enqueue({
- id: obs.id,
- sessionId: obs.sessionId,
- text: obs.title + ' ' + obs.narrative,
- context: { kind: "observation", logId: obs.id },
- })
+ if (vectorEnabled) revisions.set(obs, idx.watchRevision(obs.id))
count++
}
- await flush()
if (count > 0) scheduleIndexSave()
+ const pending: VectorBackfillJob[] = []
+ const flush = async (): Promise<void> => {
+ if (pending.length === 0) return
+ await vectorIndexAddBatchGuarded(pending)
+ pending.length = 0
+ }
+ const enqueue = async (job: VectorBackfillJob): Promise<void> => {
+ pending.push(job)
+ if (pending.length >= batchSize) await flush()
+ }
+ try {
+ for (const memory of memories) {
+ const revision = revisions.get(memory)
+ if (!revision?.isCurrent()) continue
+ await enqueue({
+ id: memory.id, revision,
+ sessionId: memory.sessionIds?.[0] ?? 'memory',
+ text: memory.title + ' ' + memory.content,
+ context: { kind: "memory", logId: memory.id },
+ })
+ }
+ for (const obs of observations) {
+ const revision = revisions.get(obs)
+ if (!revision?.isCurrent()) continue
+ await enqueue({
+ id: obs.id, revision, sessionId: obs.sessionId,
+ text: obs.title + ' ' + obs.narrative,
+ context: { kind: "observation", logId: obs.id },
+ })
+ }
+ await flush()
+ if (count > 0 && vectorEnabled) scheduleIndexSave()
+ } finally {
+ for (const revision of revisions.values()) revision.release()
+ }
return count
}
@@ -491,6 +510,7 @@ export async function rebuildIndex(kv: StateKV): Promise<number> {
export type VectorBackfillJob = {
id: string
+ revision?: SearchIndexRevision
sessionId: string
text: string
context: { kind: "memory" | "observation" | "synthetic"; logId: string }
@@ -569,7 +589,7 @@ async function runKeywordRebuild(
return
}
if (!backfillActive || (wholeStoreBackfill && vectorJobs.length >= backfillCap)) return
- vectorJobs.push({ id, sessionId, text, context: { kind, logId: id } })
+ vectorJobs.push({ id, sessionId, text, revision: idx.watchRevision(id), context: { kind, logId: id } })
}
let documents = 0
@@ -630,16 +650,18 @@ const VECTOR_BACKLOG_PAUSE_MS = 1000
async function embedBackfillJobs(
jobs: VectorBackfillJob[],
remainingAfter: number,
-): Promise<{ ok: number; fail: number }> {
+): Promise<{ ok: number; fail: number; skipped: number }> {
const batchSize = getRebuildEmbedBatchSize()
let ok = 0
let fail = 0
+ let skipped = 0
let batchesSinceSave = 0
setPendingVectorBackfillCount(remainingAfter + jobs.length)
for (let offset = 0; offset < jobs.length; offset += batchSize) {
const result = await vectorIndexAddBatchGuarded(jobs.slice(offset, offset + batchSize))
ok += result.ok
fail += result.fail
+ skipped += result.skipped
setPendingVectorBackfillCount(remainingAfter + jobs.length - Math.min(jobs.length, offset + batchSize))
batchesSinceSave++
if (batchesSinceSave >= BACKFILL_SAVE_EVERY_BATCHES) {
@@ -648,7 +670,7 @@ async function embedBackfillJobs(
}
}
if (ok > 0) await flushIndexSave()
- return { ok, fail }
+ return { ok, fail, skipped }
}
export async function backfillVectors(jobs: VectorBackfillJob[]): Promise<number> {
@@ -668,7 +690,7 @@ export async function backfillVectorBacklog(
for (let offset = 0; offset < jobs.length; offset += batchSize) {
if (offset > 0 && pauseMs > 0) await delay(pauseMs)
const after = Math.max(0, jobs.length - offset - batchSize)
- const batch = jobs.slice(offset, offset + batchSize).filter((job) => !vectorIndex?.has(job.id))
+ const batch = jobs.slice(offset, offset + batchSize).filter((job) => !vectorIndex?.has(job.id) && (!job.revision || job.revision.isCurrent()))
if (batch.length === 0) {
setPendingVectorBackfillCount(after)
continue
@@ -676,9 +698,10 @@ export async function backfillVectorBacklog(
const result = await embedBackfillJobs(batch, after)
added += result.ok
failed += result.fail
- if (result.ok === 0) {
- setPendingVectorBackfillCount(jobs.length - offset)
- return { added, failed, remaining: jobs.length - offset, complete: false }
+ if (result.ok === 0 && (result.fail > 0 || result.skipped === 0)) {
+ const remaining = after + failed + (result.fail === 0 ? batch.length : 0)
+ setPendingVectorBackfillCount(remaining)
+ return { added, failed, remaining, complete: false }
}
}
setPendingVectorBackfillCount(failed)
diff --git a/src/functions/snapshot.ts b/src/functions/snapshot.ts
index d43b60f4..543a45fe 100644
--- a/src/functions/snapshot.ts
+++ b/src/functions/snapshot.ts
@@ -1,21 +1,26 @@
+import { pinGraphState } from "../state/graph-generation.js";
import type { IIIClient } from "iii-sdk";
import { execFile } from "node:child_process";
import { promisify } from "node:util";
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import type {
SnapshotMeta,
Session,
Memory,
GraphNode,
+ GraphEdge,
+ CompressedObservation,
AccessLogExport,
} from "../types.js";
import { KV, generateId } from "../state/schema.js";
import type { StateKV } from "../state/kv.js";
+import type { SearchIndexRevision } from "../state/search-index.js";
import { addSessionToProjectIndex } from "../state/session-index.js";
import { withKeyedLock } from "../state/keyed-mutex.js";
import { recordAudit } from "./audit.js";
-import { boundRecordSources } from "./graph.js";
+import { persistGraphRecords, validateGraphRecords } from "../state/graph-ingestion.js";
+import { flushIndexSave, getSearchIndex, indexRecords, vectorIndexRemove } from "./search.js";
import { VERSION } from "../version.js";
import { logger } from "../logger.js";
@@ -23,8 +28,8 @@ const COMMIT_HASH_RE = /^[0-9a-f]{7,40}$/i;
const execFileAsync = promisify(execFile);
-async function gitExec(dir: string, args: string[]): Promise<string> {
- const { stdout } = await execFileAsync("git", args, { cwd: dir });
+async function gitExec(dir: string, args: string[], maxBuffer?: number): Promise<string> {
+ const { stdout } = await execFileAsync("git", args, { cwd: dir, maxBuffer });
return stdout.trim();
}
@@ -41,7 +46,7 @@ async function ensureGitRepo(dir: string): Promise<void> {
export function registerSnapshotFunction(
sdk: IIIClient,
- kv: StateKV,
+ state: StateKV,
snapshotDir: string,
): void {
// Serialize snapshots: the periodic timer, REST (api::snapshot-create), and
@@ -52,6 +57,7 @@ export function registerSnapshotFunction(
sdk.registerFunction("mem::snapshot-create",
async (data?: { message?: string }) => {
+ const kv = await pinGraphState(state);
if (snapshotInFlight) {
return { success: true, message: "Snapshot already in progress" };
}
@@ -64,6 +70,7 @@ export function registerSnapshotFunction(
const sessions = await kv.list<Session>(KV.sessions);
const memories = await kv.list<Memory>(KV.memories);
const graphNodes = await kv.list<GraphNode>(KV.graphNodes);
+ const graphEdges = await kv.list<GraphEdge>(KV.graphEdges);
const accessLogs = await kv
.list<AccessLogExport>(KV.accessLog)
.catch(() => [] as AccessLogExport[]);
@@ -84,6 +91,7 @@ export function registerSnapshotFunction(
sessions,
memories,
graphNodes,
+ graphEdges,
observations,
accessLogs,
};
@@ -170,6 +178,7 @@ export function registerSnapshotFunction(
sdk.registerFunction("mem::snapshot-restore",
async (data: { commitHash: string } | undefined) => {
+ const kv = await pinGraphState(state);
if (!data || typeof data.commitHash !== "string" || !data.commitHash.trim()) {
return { success: false, error: "commitHash is required" };
}
@@ -178,73 +187,98 @@ export function registerSnapshotFunction(
}
try {
- await gitExec(snapshotDir, [
- "checkout",
- data.commitHash,
- "--",
- "state.json",
- ]);
- const content = readFileSync(join(snapshotDir, "state.json"), "utf-8");
- const state = JSON.parse(content) as {
+ const content = await gitExec(snapshotDir, ["show", `${data.commitHash}:state.json`], Infinity);
+ const archive = JSON.parse(content) as {
sessions?: Array<{ id: string } & Record<string, unknown>>;
- memories?: Array<{ id: string } & Record<string, unknown>>;
- graphNodes?: Array<{ id: string } & Record<string, unknown>>;
- observations?: Record<
- string,
- Array<{ id: string } & Record<string, unknown>>
- >;
+ memories?: Memory[];
+ graphNodes?: GraphNode[];
+ graphEdges?: GraphEdge[];
+ observations?: Record<string, CompressedObservation[]>;
accessLogs?: AccessLogExport[];
};
-
- if (state.sessions) {
- for (const session of state.sessions) {
- await withKeyedLock(`obs:${session.id}`, () =>
- kv.set(KV.sessions, session.id, session),
- );
- const project = session.project;
- const startedAt = session.startedAt;
- if (typeof project === "string" && typeof startedAt === "string") {
- const agentId = session.agentId;
- await addSessionToProjectIndex(kv, project, {
- id: session.id,
- startedAt,
- ...(typeof agentId === "string" ? { agentId } : {}),
- }).catch(() => {});
+ validateGraphRecords(archive.graphNodes ?? [], archive.graphEdges ?? []);
+ const memoryIds = new Set<string>();
+ const observationSessions = new Map<string, string>();
+ let restoreError: unknown;
+ try {
+ if (archive.sessions) {
+ for (const session of archive.sessions) {
+ await withKeyedLock(`obs:${session.id}`, () =>
+ kv.set(KV.sessions, session.id, session),
+ );
+ const project = session.project;
+ const startedAt = session.startedAt;
+ if (typeof project === "string" && typeof startedAt === "string") {
+ const agentId = session.agentId;
+ await addSessionToProjectIndex(kv, project, {
+ id: session.id,
+ startedAt,
+ ...(typeof agentId === "string" ? { agentId } : {}),
+ }).catch(() => {});
+ }
}
}
- }
- if (state.memories) {
- for (const memory of state.memories) {
+ for (const memory of archive.memories ?? []) {
await kv.set(KV.memories, memory.id, memory);
+ getSearchIndex().remove(memory.id);
+ vectorIndexRemove(memory.id);
+ memoryIds.add(memory.id);
}
- }
- if (state.graphNodes) {
- for (const node of state.graphNodes) {
- await withKeyedLock("graph:persist", () =>
- kv.set(KV.graphNodes, node.id, boundRecordSources(node)),
- );
- }
- }
- if (state.observations) {
- for (const [sessionId, obs] of Object.entries(state.observations)) {
- for (const o of obs) {
- await kv.set(KV.observations(sessionId), o.id, o);
+ for (const [sessionId, observations] of Object.entries(archive.observations ?? {})) {
+ for (const observation of observations) {
+ await kv.set(KV.observations(sessionId), observation.id, observation);
+ getSearchIndex().remove(observation.id);
+ vectorIndexRemove(observation.id);
+ observationSessions.set(observation.id, sessionId);
}
}
- }
- if (state.accessLogs) {
- for (const log of state.accessLogs) {
+ if (archive.graphNodes?.length || archive.graphEdges?.length) {
+ await persistGraphRecords(kv, archive.graphNodes ?? [], archive.graphEdges ?? [], { mode: "merge" });
+ }
+ for (const log of archive.accessLogs ?? []) {
await kv.set(KV.accessLog, log.memoryId, log);
}
+ } catch (err) {
+ restoreError = err;
}
- await gitExec(snapshotDir, ["checkout", "HEAD", "--", "state.json"]);
+ let indexError: unknown;
+ if (memoryIds.size || observationSessions.size) {
+ const revisions: SearchIndexRevision[] = [];
+ try {
+ const memories: Array<{ record: Memory; revision: SearchIndexRevision }> = [];
+ const observations: Array<{ record: CompressedObservation; revision: SearchIndexRevision }> = [];
+ for (const id of memoryIds) {
+ const revision = getSearchIndex().watchRevision(id);
+ revisions.push(revision);
+ const current = await kv.get<Memory>(KV.memories, id);
+ if (current) memories.push({ record: current, revision });
+ }
+ for (const [id, sessionId] of observationSessions) {
+ const revision = getSearchIndex().watchRevision(id);
+ revisions.push(revision);
+ const current = await kv.get<CompressedObservation>(KV.observations(sessionId), id);
+ if (current) observations.push({ record: current, revision });
+ }
+ await indexRecords(
+ observations.filter(({ revision }) => revision.isCurrent()).map(({ record }) => record),
+ memories.filter(({ revision }) => revision.isCurrent()).map(({ record }) => record),
+ );
+ } catch (err) {
+ indexError = err;
+ } finally {
+ for (const revision of revisions) revision.release();
+ await flushIndexSave();
+ }
+ }
+ if (restoreError) throw restoreError;
+ if (indexError) throw indexError;
await recordAudit(kv, "import", "mem::snapshot-restore", [], {
commitHash: data.commitHash,
- sessions: state.sessions?.length || 0,
- memories: state.memories?.length || 0,
- graphNodes: state.graphNodes?.length || 0,
+ sessions: archive.sessions?.length || 0,
+ memories: archive.memories?.length || 0,
+ graphNodes: archive.graphNodes?.length || 0,
});
logger.info("Snapshot restored", {
diff --git a/src/functions/temporal-graph.ts b/src/functions/temporal-graph.ts
index d79dd04f..cdf27f6b 100644
--- a/src/functions/temporal-graph.ts
+++ b/src/functions/temporal-graph.ts
@@ -1,3 +1,4 @@
+import { pinGraphState } from "../state/graph-generation.js";
import type { IIIClient } from "iii-sdk";
import type {
GraphNode,
@@ -153,7 +154,7 @@ function parseTemporalGraphXml(
export function registerTemporalGraphFunctions(
sdk: IIIClient,
- kv: StateKV,
+ state: StateKV,
provider: MemoryProvider,
): void {
sdk.registerFunction("mem::temporal-graph-extract",
@@ -168,6 +169,7 @@ export function registerTemporalGraphFunctions(
timestamp: string;
}>;
}) => {
+ const kv = await pinGraphState(state);
if (!data.observations || data.observations.length === 0) {
return { success: false, error: "No observations provided" };
}
@@ -284,6 +286,7 @@ export function registerTemporalGraphFunctions(
asOf?: string;
includeHistory?: boolean;
}): Promise<TemporalState | { error: string }> => {
+ const kv = await pinGraphState(state);
const allNodes = await kv.list<GraphNode>(KV.graphNodes);
const allEdges = await kv.list<GraphEdge>(KV.graphEdges);
@@ -362,6 +365,7 @@ export function registerTemporalGraphFunctions(
from?: string;
to?: string;
}) => {
+ const kv = await pinGraphState(state);
const allNodes = await kv.list<GraphNode>(KV.graphNodes);
const allEdges = await kv.list<GraphEdge>(KV.graphEdges);
const historicalEdges = await kv
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index 8ea5b80d..d9268e10 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -2,6 +2,7 @@ import type { IIIClient } from "iii-sdk";
import type { HttpRequest } from "@iii-dev/helpers/http";
import type { StateKV } from "../state/kv.js";
import { KV } from "../state/schema.js";
+import { pinGraphState } from "../state/graph-generation.js";
import type {
SessionSummary,
Memory,
@@ -1484,8 +1485,9 @@ export function registerMcpEndpoints(
if (uri === "agentmemory://graph/stats") {
try {
- const nodes = await kv.list<GraphNode>(KV.graphNodes);
- const edges = await kv.list<GraphEdge>(KV.graphEdges);
+ const graphState = await pinGraphState(kv);
+ const nodes = await graphState.list<GraphNode>(KV.graphNodes);
+ const edges = await graphState.list<GraphEdge>(KV.graphEdges);
const nodesByType: Record<string, number> = {};
for (const n of nodes)
nodesByType[n.type] = (nodesByType[n.type] || 0) + 1;
diff --git a/src/prompts/compression-output.ts b/src/prompts/compression-output.ts
new file mode 100644
index 00000000..e55b8249
--- /dev/null
+++ b/src/prompts/compression-output.ts
@@ -0,0 +1,90 @@
+interface XmlElement {
+ name: string;
+ content: string;
+}
+
+function elements(xml: string): XmlElement[] | null {
+ const result: XmlElement[] = [];
+ let remaining = xml.trim();
+ while (remaining) {
+ const match = /^<([a-z][a-z0-9_-]*)\s*(?:\/>|>([\s\S]*?)<\/\1\s*>)/.exec(remaining);
+ if (!match) return null;
+ result.push({ name: match[1], content: match[2] ?? "" });
+ remaining = remaining.slice(match[0].length).trim();
+ }
+ return result;
+}
+
+function xmlText(content: string): string | null {
+ if (content.includes("<") || /&(?!(?:amp|lt|gt|quot|apos|#\d+|#x[\da-fA-F]+);)/.test(content)) {
+ return null;
+ }
+ const entities: Record<string, string> = {
+ amp: "&", lt: "<", gt: ">", quot: '"', apos: "'",
+ };
+ let valid = true;
+ const text = content.replace(/&([^;]+);/g, (_, entity: string) => {
+ if (entity in entities) return entities[entity];
+ const code = entity.startsWith("#x")
+ ? parseInt(entity.slice(2), 16)
+ : Number(entity.slice(1));
+ if (!(code === 9 || code === 10 || code === 13 ||
+ (code >= 0x20 && code <= 0xd7ff) ||
+ (code >= 0xe000 && code <= 0xfffd) ||
+ (code >= 0x10000 && code <= 0x10ffff))) {
+ valid = false;
+ return "";
+ }
+ return String.fromCodePoint(code);
+ });
+ return valid && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/.test(text) ? text.trim() : null;
+}
+
+const SCALARS = new Set(["type", "title", "subtitle", "narrative", "importance"]);
+const LISTS: Record<string, string> = { facts: "fact", concepts: "concept", files: "file" };
+
+export function parseCompressionXml(response: string) {
+ let xml = response.trim();
+ // Reasoning is outside the observation contract, even when it quotes XML fields.
+ xml = xml.replace(/^<(think|thought)>[\s\S]*?<\/\1>\s*/, "");
+ const fenced = /^```(?:xml)?\s*\n([\s\S]*?)\n```$/i.exec(xml);
+ if (fenced) xml = fenced[1].trim();
+
+ const roots = elements(xml);
+ if (!roots || roots.length !== 1 || roots[0].name !== "observation") return null;
+ const fields = elements(roots[0].content);
+ if (!fields) return null;
+ const seen = new Set<string>();
+ const scalars: Record<string, string> = {};
+ const lists: Record<string, string[]> = { facts: [], concepts: [], files: [] };
+ for (const field of fields) {
+ if (seen.has(field.name)) return null;
+ seen.add(field.name);
+ if (SCALARS.has(field.name)) {
+ const text = xmlText(field.content);
+ if (text === null) return null;
+ scalars[field.name] = text;
+ } else if (Object.hasOwn(LISTS, field.name)) {
+ const children = elements(field.content);
+ if (!children) return null;
+ for (const child of children) {
+ if (child.name !== LISTS[field.name]) return null;
+ const text = xmlText(child.content);
+ if (text === null || !text) return null;
+ lists[field.name].push(text);
+ }
+ } else {
+ return null;
+ }
+ }
+ return {
+ type: scalars.type ?? "",
+ title: scalars.title ?? "",
+ subtitle: scalars.subtitle || undefined,
+ facts: lists.facts,
+ narrative: scalars.narrative ?? "",
+ concepts: lists.concepts,
+ files: lists.files,
+ importance: /^\d+$/.test(scalars.importance ?? "") ? Number(scalars.importance) : NaN,
+ };
+}
diff --git a/src/prompts/compression.ts b/src/prompts/compression.ts
index 51183b0c..198c45bf 100644
--- a/src/prompts/compression.ts
+++ b/src/prompts/compression.ts
@@ -21,6 +21,7 @@ Output EXACTLY this XML format with no additional text:
</observation>
Rules:
+- Escape &, <, and > inside text as &amp;, &lt;, and &gt;. Use only the tags shown, with no attributes or nested tags inside text fields.
- Be concise but preserve ALL technically relevant details
- File paths must be exact
- Importance: 1-3 for routine reads, 4-6 for edits/commands, 7-9 for architectural decisions, 10 for breaking changes
diff --git a/src/providers/_fetch.ts b/src/providers/_fetch.ts
index 3b02d935..5223baba 100644
--- a/src/providers/_fetch.ts
+++ b/src/providers/_fetch.ts
@@ -15,8 +15,20 @@ const HARD_BUDGET_CAP_MS = 170000;
const MIN_ATTEMPT_FLOOR_MS = 100;
const RETRY_STATUS = new Set([429, 503]);
-const sleep = (ms: number): Promise<void> =>
- new Promise((resolve) => setTimeout(resolve, ms));
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+ signal.throwIfAborted();
+ return new Promise((resolve, reject) => {
+ const onAbort = () => {
+ clearTimeout(timer);
+ reject(signal.reason);
+ };
+ const timer = setTimeout(() => {
+ signal.removeEventListener("abort", onAbort);
+ resolve();
+ }, ms);
+ signal.addEventListener("abort", onAbort, { once: true });
+ });
+}
/**
* Parse a Retry-After header into a delay in milliseconds. Supports both the
@@ -42,19 +54,6 @@ function parseRetryAfter(header: string | null): number | undefined {
return undefined;
}
-async function fetchOnce(
- url: string,
- init: RequestInit,
- ms: number,
-): Promise<Response> {
- const ctl = new AbortController();
- const signal = init.signal
- ? AbortSignal.any([init.signal, ctl.signal])
- : ctl.signal;
- const t = setTimeout(() => ctl.abort(), ms);
- return fetch(url, { ...init, signal }).finally(() => clearTimeout(t));
-}
-
export async function fetchWithTimeout(
url: string,
init: RequestInit,
@@ -69,11 +68,15 @@ export async function fetchWithTimeout(
// capped so we never approach the iii invocation timeout.
const budgetMs = Math.min(ms, HARD_BUDGET_CAP_MS);
const start = Date.now();
+ // Fetch resolves at headers. Keep this same signal alive through retries
+ // and the caller's response-body reads, including non-success responses.
+ const deadline = AbortSignal.timeout(Math.max(1, Math.floor(budgetMs)));
+ const signal = init.signal
+ ? AbortSignal.any([init.signal, deadline])
+ : deadline;
+ signal.throwIfAborted();
- // The first attempt must honor the capped budget too — passing raw `ms`
- // here would let a large caller timeout hang past HARD_BUDGET_CAP_MS (and
- // the iii 180s invocation timeout) before any retry logic runs.
- let response: Response = await fetchOnce(url, init, budgetMs);
+ let response = await fetch(url, { ...init, signal });
for (let attempt = 1; attempt < MAX_ATTEMPTS; attempt++) {
if (!RETRY_STATUS.has(response.status)) return response;
@@ -92,15 +95,13 @@ export async function fetchWithTimeout(
// This response is being discarded for a retry; release its body so the
// underlying connection is returned to the pool instead of leaking.
await response.body?.cancel().catch(() => {});
- await sleep(delay);
+ await sleep(delay, signal);
- // Cap the per-attempt timeout to whatever budget is left so a late attempt
- // can't push total elapsed past the deadline.
- const attemptMs = Math.max(
- MIN_ATTEMPT_FLOOR_MS,
- Math.min(ms, budgetMs - (Date.now() - start)),
- );
- response = await fetchOnce(url, init, attemptMs);
+ signal.throwIfAborted();
+ if (Date.now() - start >= budgetMs) {
+ throw new DOMException("Provider request timed out", "TimeoutError");
+ }
+ response = await fetch(url, { ...init, signal });
}
return response;
}
diff --git a/src/providers/openai.ts b/src/providers/openai.ts
index 46500cf8..6e2e9c2c 100644
--- a/src/providers/openai.ts
+++ b/src/providers/openai.ts
@@ -90,9 +90,8 @@ export class OpenAIProvider implements MemoryProvider {
body.reasoning_effort = this.reasoningEffort;
}
- let response: Response;
try {
- response = await fetchWithTimeout(
+ const response = await fetchWithTimeout(
url,
{
method: "POST",
@@ -101,8 +100,33 @@ export class OpenAIProvider implements MemoryProvider {
},
this.timeoutMs,
);
+
+ if (!response.ok) {
+ const text = await response.text();
+ throw new Error(`OpenAI API error (${response.status}): ${text}`);
+ }
+
+ const data = (await response.json()) as {
+ choices?: Array<{
+ message?: { content?: string; reasoning?: string; reasoning_content?: string };
+ }>;
+ };
+ const message = data.choices?.[0]?.message;
+ const content = message?.content;
+ if (content) {
+ return content;
+ }
+ const reasoning = message?.reasoning ?? message?.reasoning_content;
+ if (reasoning) {
+ return reasoning;
+ }
+ throw new Error(
+ `OpenAI returned unexpected response: ${JSON.stringify(data).slice(0, 200)}`,
+ );
} catch (err) {
- const aborted = err instanceof Error && err.name === "AbortError";
+ const aborted =
+ err instanceof Error &&
+ (err.name === "AbortError" || err.name === "TimeoutError");
if (aborted) {
throw new Error(
`OpenAI API request timed out after ${this.timeoutMs}ms — set OPENAI_TIMEOUT_MS (or AGENTMEMORY_LLM_TIMEOUT_MS) to raise the bound or check the provider status.`,
@@ -110,29 +134,6 @@ export class OpenAIProvider implements MemoryProvider {
}
throw err;
}
-
- if (!response.ok) {
- const text = await response.text();
- throw new Error(`OpenAI API error (${response.status}): ${text}`);
- }
-
- const data = (await response.json()) as {
- choices?: Array<{
- message?: { content?: string; reasoning?: string; reasoning_content?: string };
- }>;
- };
- const message = data.choices?.[0]?.message;
- const content = message?.content;
- if (content) {
- return content;
- }
- const reasoning = message?.reasoning ?? message?.reasoning_content;
- if (reasoning) {
- return reasoning;
- }
- throw new Error(
- `OpenAI returned unexpected response: ${JSON.stringify(data).slice(0, 200)}`,
- );
}
}
diff --git a/src/state/graph-consistency.ts b/src/state/graph-consistency.ts
new file mode 100644
index 00000000..34d89862
--- /dev/null
+++ b/src/state/graph-consistency.ts
@@ -0,0 +1,85 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { StateKV } from "./kv.js";
+import type { GraphSnapshot } from "../types.js";
+import { KV } from "./schema.js";
+import { isKeyedLockHeld, withKeyedLock } from "./keyed-mutex.js";
+
+const recovering = new AsyncLocalStorage<boolean>();
+type SnapshotCheck = { clean: boolean };
+const checks = new WeakMap<StateKV, Map<string, SnapshotCheck>>();
+const scopes = [KV.graphNodes, KV.graphEdges, KV.graphEdgeHistory, KV.graphSnapshot,
+ KV.graphNameIndex, KV.graphEdgeKey, KV.graphNodeDegree, KV.graphMembership];
+
+function snapshotScope(scope: string): string | null {
+ for (const logical of scopes) {
+ if (scope === logical) return KV.graphSnapshot;
+ if (scope.startsWith(`${logical}:generation:`)) return KV.graphSnapshot + scope.slice(logical.length);
+ }
+ return null;
+}
+
+export function withoutGraphRecovery<T>(fn: () => Promise<T>): Promise<T> {
+ return recovering.run(true, fn);
+}
+
+export function noteGraphSnapshotWrite(kv: StateKV, scope: string, key: string): void {
+ if (key === "current" && (scope === KV.graphSnapshot || scope.startsWith(`${KV.graphSnapshot}:generation:`))) {
+ checks.get(kv)?.delete(scope);
+ }
+}
+
+function snapshotCheck(kv: StateKV, scope: string): SnapshotCheck {
+ let entries = checks.get(kv);
+ if (!entries) checks.set(kv, entries = new Map());
+ let check = entries.get(scope);
+ if (!check) {
+ if (entries.size >= 64) entries.clear();
+ check = { clean: false };
+ entries.set(scope, check);
+ }
+ return check;
+}
+
+function markChecked(kv: StateKV, scope: string, check: SnapshotCheck): void {
+ if (checks.get(kv)?.get(scope) === check) check.clean = true;
+}
+
+export async function ensureGraphConsistency(kv: StateKV, scope: string): Promise<void> {
+ if (recovering.getStore()) return;
+ const snapshot = snapshotScope(scope);
+ if (!snapshot) return;
+ const check = snapshotCheck(kv, snapshot);
+ if (check.clean) return;
+ const recover = () => withoutGraphRecovery(async () => {
+ const recoveryCheck = snapshotCheck(kv, snapshot);
+ const current = await kv.get<GraphSnapshot>(snapshot, "current");
+ const pending = current?.pendingMutation;
+ if (pending) {
+ if (!current.dirty || !Array.isArray(pending.writes) || pending.snapshot?.version !== 1 || pending.snapshot.pendingMutation) {
+ throw new Error("Invalid graph reconciliation journal");
+ }
+ const suffix = snapshot.slice(KV.graphSnapshot.length);
+ for (const write of pending.writes) {
+ if (!write || typeof write !== "object") throw new Error("Invalid graph reconciliation write");
+ if (!scopes.includes(write.scope as typeof scopes[number]) || write.scope === KV.graphSnapshot || typeof write.key !== "string") {
+ throw new Error("Invalid graph reconciliation write");
+ }
+ }
+ for (const write of pending.writes) {
+ if (write.value === null) await kv.delete(write.scope + suffix, write.key);
+ else await kv.set(write.scope + suffix, write.key, write.value);
+ }
+ await kv.set(snapshot, "current", pending.snapshot);
+ }
+ markChecked(kv, snapshot, recoveryCheck);
+ });
+ if (isKeyedLockHeld("graph:persist")) return recover();
+ const peek = await withoutGraphRecovery(() => kv.get<GraphSnapshot>(snapshot, "current"));
+ // Writes invalidate before and after awaiting the engine, including failures.
+ // Retain a clean check only if neither a write nor eviction replaced its token.
+ if (!peek?.pendingMutation) {
+ markChecked(kv, snapshot, check);
+ return;
+ }
+ await withKeyedLock("graph:persist", recover);
+}
diff --git a/src/state/graph-generation.ts b/src/state/graph-generation.ts
new file mode 100644
index 00000000..4b16f998
--- /dev/null
+++ b/src/state/graph-generation.ts
@@ -0,0 +1,106 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import type { StateKV } from "./kv.js";
+import { KV } from "./schema.js";
+import { afterKeyedLock } from "./keyed-mutex.js";
+
+const CONTROL_SCOPE = KV.graphControl;
+const CONTROL_KEY = "generation";
+const GRAPH_SCOPES = new Set<string>([
+ KV.graphNodes, KV.graphEdges, KV.graphEdgeHistory, KV.graphSnapshot,
+ KV.graphNameIndex, KV.graphEdgeKey, KV.graphNodeDegree, KV.graphMembership,
+]);
+const pinned = new AsyncLocalStorage<{ kv: StateKV; generation: string | null }>();
+const views = new WeakMap<StateKV, { target: StateKV; id: string | null }>();
+type GraphChange = "reset" | "snapshot" | "nodes" | "edges";
+let onGraphChange: ((kind: GraphChange) => Promise<void>) | null = null;
+
+export function setGraphGenerationListener(listener: typeof onGraphChange): void {
+ onGraphChange = listener;
+}
+
+// The engine's legacy scope subscriptions cannot follow a rotated namespace.
+export async function notifyGraphGenerationChange(kv: StateKV, scope: string, key: string): Promise<void> {
+ if (!onGraphChange) return;
+ const kind: GraphChange | undefined = scope === CONTROL_SCOPE && key === CONTROL_KEY ? "reset"
+ : scope.startsWith(`${KV.graphSnapshot}:generation:`) ? "snapshot"
+ : scope.startsWith(`${KV.graphNodes}:generation:`) ? "nodes"
+ : scope.startsWith(`${KV.graphEdges}:generation:`) ? "edges" : undefined;
+ if (!kind) return;
+ if (afterKeyedLock("graph:persist", () => notifyGraphGenerationChange(kv, scope, key), scope)) return;
+ if (afterKeyedLock("graph:viewer-events", () => notifyGraphGenerationChange(kv, scope, key), scope)) return;
+ try {
+ const current = await generation(kv);
+ if (kind !== "reset" && !scope.endsWith(`:generation:${current}`)) return;
+ await pinned.exit(() => onGraphChange!(kind));
+ } catch {
+ // Viewer delivery must not turn a committed state write into a failed mutation.
+ }
+}
+
+export async function isLegacyGraphState(kv: StateKV): Promise<boolean> {
+ return await generation(kv) === null;
+}
+
+async function generation(kv: StateKV): Promise<string | null> {
+ const value = await kv.get<unknown>(CONTROL_SCOPE, CONTROL_KEY);
+ if (value === null || value === undefined) return null;
+ if (typeof value !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value)) {
+ throw new Error("Invalid graph generation");
+ }
+ return value;
+}
+
+function physicalScope(scope: string, id: string | null): string {
+ return id !== null && GRAPH_SCOPES.has(scope) ? `${scope}:generation:${id}` : scope;
+}
+
+/** Used by StateKV so every graph consumer respects reset, including fallback reads. */
+export async function resolveGraphScope(kv: StateKV, scope: string): Promise<string> {
+ if (!GRAPH_SCOPES.has(scope)) return scope;
+ const context = pinned.getStore();
+ const id = context?.kv === kv ? context.generation : await generation(kv);
+ return physicalScope(scope, id);
+}
+
+/** Pin an operation before any awaits: late writes remain in its original generation. */
+export async function pinGraphState(kv: StateKV): Promise<StateKV> {
+ if (views.has(kv)) return kv;
+ const id = await generation(kv);
+ return graphView(kv, id);
+}
+
+function graphView(kv: StateKV, id: string | null): StateKV {
+ const methods = new Set(["get", "set", "update", "delete", "list"]);
+ const view = new Proxy(kv, {
+ get(target, property, receiver) {
+ const value = Reflect.get(target, property, receiver);
+ if (typeof property !== "string" || !methods.has(property)) return value;
+ return (scope: string, ...args: unknown[]) => pinned.run(
+ { kv: target, generation: id },
+ () => value.call(target, physicalScope(scope, id), ...args),
+ );
+ },
+ });
+ views.set(view, { target: kv, id });
+ return view;
+}
+
+/** Initialize first, publish last; failures cannot expose a half-reset graph. */
+export async function resetGraphGeneration(kv: StateKV, snapshot: unknown): Promise<void> {
+ const id = randomUUID();
+ await kv.set(physicalScope(KV.graphSnapshot, id), "current", snapshot);
+ await kv.set(CONTROL_SCOPE, CONTROL_KEY, id);
+}
+
+export async function replaceGraphGeneration<T>(kv: StateKV, initialize: (fresh: StateKV) => Promise<T>): Promise<T> {
+ const pinnedState = await pinGraphState(kv);
+ const { target, id: previous } = views.get(pinnedState)!;
+ const id = randomUUID();
+ const result = await initialize(graphView(target, id));
+ // A delayed import cannot replace a reset that happened after it was pinned.
+ if (await generation(target) === previous) {
+ await target.set(CONTROL_SCOPE, CONTROL_KEY, id);
+ }
+ return result;
+}
diff --git a/src/state/graph-ingestion.ts b/src/state/graph-ingestion.ts
new file mode 100644
index 00000000..c6392a75
--- /dev/null
+++ b/src/state/graph-ingestion.ts
@@ -0,0 +1,224 @@
+import type { GraphEdge, GraphNode, GraphSnapshot, GraphMutationWrite, GraphIndexMembership } from "../types.js";
+import type { StateKV } from "./kv.js";
+import { KV } from "./schema.js";
+import { pinGraphState, replaceGraphGeneration } from "./graph-generation.js";
+import { withKeyedLock } from "./keyed-mutex.js";
+import { withoutGraphRecovery } from "./graph-consistency.js";
+
+export interface GraphIngestionOptions {
+ mode?: "merge" | "skip" | "lww";
+ replace?: boolean;
+}
+
+const TOP_N = 500;
+const BATCH_SIZE = 50;
+const MAX_SNAPSHOT_EDGES = 2000;
+const nodeKey = (node: GraphNode) => `${node.type}|${node.name}`;
+const edgeKey = (edge: GraphEdge) => `${edge.sourceNodeId}|${edge.targetNodeId}|${edge.type}`;
+const membershipKey = (scope: string, key: string) => JSON.stringify([scope, key]);
+
+function emptySnapshot(): GraphSnapshot {
+ return { version: 1, topNodes: [], topEdges: [], topDegrees: {},
+ stats: { totalNodes: 0, totalEdges: 0, nodesByType: {}, edgesByType: {} },
+ dirty: false, updatedAt: new Date().toISOString() };
+}
+
+function valid(row: unknown, edge: boolean): row is GraphNode | GraphEdge {
+ if (!row || typeof row !== "object") return false;
+ const value = row as Record<string, unknown>;
+ return typeof value.id === "string" && value.id.length > 0 && typeof value.type === "string" && value.type.length > 0 &&
+ (edge ? typeof value.sourceNodeId === "string" && value.sourceNodeId.length > 0 && typeof value.targetNodeId === "string" && value.targetNodeId.length > 0
+ : typeof value.name === "string" && typeof value.properties === "object" && value.properties !== null && !Array.isArray(value.properties));
+}
+
+export function validateGraphRecords(nodes: unknown, edges: unknown): void {
+ if (!Array.isArray(nodes) || !Array.isArray(edges)) throw new Error("Graph nodes and edges must be arrays");
+ if (nodes.some((n) => !valid(n, false)) || edges.some((e) => !valid(e, true))) {
+ throw new Error("Invalid graph node or edge");
+ }
+}
+
+function bounded<T extends GraphNode | GraphEdge>(record: T): T {
+ const ids = Array.isArray(record.sourceObservationIds) ? record.sourceObservationIds : [];
+ return { ...record, sourceObservationIds: [...new Set(ids)].slice(-32) };
+}
+
+function changeCount(counts: Record<string, number>, type: string, amount: number): void {
+ const next = Math.max(0, (Object.hasOwn(counts, type) ? counts[type] : 0) + amount);
+ if (next) Object.defineProperty(counts, type, { value: next, writable: true, enumerable: true, configurable: true });
+ else delete counts[type];
+}
+
+export async function persistGraphRecords(
+ state: StateKV,
+ nodes: GraphNode[],
+ edges: GraphEdge[],
+ options: GraphIngestionOptions = {},
+): Promise<{ nodesWritten: number; edgesWritten: number; nodesSkipped: number; edgesSkipped: number }> {
+ const mode = options.mode ?? "merge";
+ if (!Array.isArray(nodes) || !Array.isArray(edges)) throw new Error("Graph nodes and edges must be arrays");
+ if (mode !== "lww") validateGraphRecords(nodes, edges);
+ const result = { nodesWritten: 0, edgesWritten: 0, nodesSkipped: 0, edgesSkipped: 0 };
+ if (!options.replace && nodes.length === 0 && edges.length === 0) return result;
+ const kv = await pinGraphState(state);
+ const run = async (target: StateKV, fresh = false) => {
+ // Reading through StateKV first recovers an interrupted prior batch.
+ const initial = await target.get<GraphSnapshot>(KV.graphSnapshot, "current");
+ if (initial && initial.version !== 1) throw new Error("Unsupported graph snapshot version");
+ let snapshot = initial ?? emptySnapshot();
+ if (fresh) await target.set(KV.graphSnapshot, "current", snapshot);
+ const records: Array<{ row: GraphNode | GraphEdge; edge: boolean }> = [
+ ...nodes.map((row) => ({ row, edge: false })), ...edges.map((row) => ({ row, edge: true })),
+ ];
+ for (let offset = 0; offset < records.length; offset += BATCH_SIZE) {
+ snapshot = await withoutGraphRecovery(async () => {
+ const before = structuredClone(snapshot);
+ const next = structuredClone(snapshot);
+ const writes = new Map<string, GraphMutationWrite>();
+ const get = async <T>(scope: string, key: string): Promise<T | null> => {
+ const staged = writes.get(JSON.stringify([scope, key]));
+ return staged ? staged.value as T | null : target.get<T>(scope, key);
+ };
+ const set = (scope: string, key: string, value: unknown) => {
+ writes.set(JSON.stringify([scope, key]), { scope, key, value });
+ };
+ const candidates = new Map(next.topNodes.filter((n) => !n.stale).map((n) => [n.id, n]));
+ const topEdges = new Map(next.topEdges.filter((e) => !e.stale).map((e) => [e.id, e]));
+ const changedDegrees = new Map<string, number>();
+ const degree = async (id: string) => changedDegrees.get(id) ?? (Object.hasOwn(next.topDegrees, id) ? next.topDegrees[id] : await get<number>(KV.graphNodeDegree, id) ?? 0);
+ const adjustDegree = async (id: string, delta: number) => {
+ const previous = await degree(id);
+ const value = Math.max(0, previous + delta);
+ changedDegrees.set(id, value);
+ set(KV.graphNodeDegree, id, value);
+ if (delta < 0 && next.stats.totalNodes > TOP_N) next.sampleIncomplete = true;
+ if (!candidates.has(id)) {
+ const node = await get<GraphNode>(KV.graphNodes, id);
+ if (node && !node.stale) candidates.set(id, node);
+ }
+ };
+ const updateIndex = async (scope: string, key: string, id: string, add: boolean) => {
+ const memberKey = membershipKey(scope, key);
+ const saved = await get<GraphIndexMembership>(KV.graphMembership, memberKey);
+ const canonical = await get<string>(scope, key);
+ const ids = new Set(saved?.ids ?? []);
+ if (canonical) ids.add(canonical);
+ if (add) ids.add(id); else ids.delete(id);
+ const members = [...ids];
+ set(KV.graphMembership, memberKey, members.length ? { ids: members } : null);
+ set(scope, key, members.at(-1) ?? null);
+ };
+ const updateAdjacency = async (edge: GraphEdge, add: boolean) => {
+ for (const id of new Set([edge.sourceNodeId, edge.targetNodeId])) {
+ const key = membershipKey("adjacency", id);
+ const saved = await get<GraphIndexMembership>(KV.graphMembership, key);
+ const ids = new Set(saved?.ids ?? []);
+ if (add) ids.add(edge.id); else ids.delete(edge.id);
+ set(KV.graphMembership, key, ids.size ? { ids: [...ids] } : null);
+ }
+ };
+ for (const item of records.slice(offset, offset + BATCH_SIZE)) {
+ const count = item.edge ? "edges" : "nodes";
+ const incoming = item.row;
+ const timestamp = item.edge ? incoming?.createdAt : (incoming as GraphNode)?.updatedAt || incoming?.createdAt;
+ if (!valid(incoming, item.edge) || (mode === "lww" && (typeof timestamp !== "string" || !Number.isFinite(Date.parse(timestamp))))) {
+ result[`${count}Skipped`] += 1;
+ continue;
+ }
+ const scope = item.edge ? KV.graphEdges : KV.graphNodes;
+ const indexScope = item.edge ? KV.graphEdgeKey : KV.graphNameIndex;
+ const keyFor = item.edge ? (r: GraphNode | GraphEdge) => edgeKey(r as GraphEdge) : (r: GraphNode | GraphEdge) => nodeKey(r as GraphNode);
+ const old = await get<GraphNode | GraphEdge>(scope, incoming.id);
+ const oldTs = item.edge ? old?.createdAt : (old as GraphNode)?.updatedAt || old?.createdAt;
+ if ((mode === "skip" && old) || (mode === "lww" && old && Date.parse(oldTs ?? "") >= Date.parse(timestamp))) {
+ result[`${count}Skipped`] += 1;
+ continue;
+ }
+ const row = bounded(incoming);
+ if (old && JSON.stringify(old) === JSON.stringify(row)) {
+ // Still reconcile old imports whose raw row predates the indexes.
+ const members = await get<GraphIndexMembership>(KV.graphMembership, membershipKey(indexScope, keyFor(row)));
+ if (members?.ids.includes(row.id)) { result[`${count}Written`] += 1; continue; }
+ }
+ const oldIndexed = old && (await get<string>(indexScope, keyFor(old)) === old.id ||
+ (await get<GraphIndexMembership>(KV.graphMembership, membershipKey(indexScope, keyFor(old))))?.ids.includes(old.id) ||
+ (item.edge ? topEdges.has(old.id) : candidates.has(old.id)));
+ const oldLive = old && !old.stale && oldIndexed;
+ const newLive = !row.stale;
+ const counts = item.edge ? next.stats.edgesByType : next.stats.nodesByType;
+ const total = item.edge ? "totalEdges" : "totalNodes";
+ if (oldLive) { next.stats[total] = Math.max(0, next.stats[total] - 1); changeCount(counts, old.type, -1); }
+ if (newLive) { next.stats[total] += 1; changeCount(counts, row.type, 1); }
+ if (old) await updateIndex(indexScope, keyFor(old), old.id, false);
+ if (newLive) await updateIndex(indexScope, keyFor(row), row.id, true);
+ set(scope, row.id, row);
+ if (item.edge) {
+ topEdges.delete(row.id);
+ if (old) await updateAdjacency(old as GraphEdge, false);
+ if (newLive) await updateAdjacency(row as GraphEdge, true);
+ if (oldLive) {
+ await adjustDegree((old as GraphEdge).sourceNodeId, -1);
+ await adjustDegree((old as GraphEdge).targetNodeId, -1);
+ }
+ if (newLive) {
+ const edge = row as GraphEdge;
+ await adjustDegree(edge.sourceNodeId, 1);
+ await adjustDegree(edge.targetNodeId, 1);
+ topEdges.set(edge.id, edge);
+ }
+ } else {
+ candidates.delete(row.id);
+ if (newLive) candidates.set(row.id, row as GraphNode);
+ else if (next.stats.totalNodes > TOP_N) next.sampleIncomplete = true;
+ const value = await degree(row.id);
+ set(KV.graphNodeDegree, row.id, value);
+ }
+ result[`${count}Written`] += 1;
+ }
+ if (!writes.size) return snapshot;
+ const degrees = new Map<string, number>();
+ for (const id of candidates.keys()) degrees.set(id, await degree(id));
+ next.topNodes = [...candidates.values()].sort((a, b) => degrees.get(b.id)! - degrees.get(a.id)!).slice(0, TOP_N);
+ const ids = new Set(next.topNodes.map((n) => n.id));
+ next.topDegrees = Object.fromEntries(next.topNodes.map((n) => [n.id, degrees.get(n.id)!]));
+ const previouslyCached = new Set(before.topNodes.map((n) => n.id));
+ let remainingEdgeReads = MAX_SNAPSHOT_EDGES;
+ for (const id of ids) {
+ if (previouslyCached.has(id)) continue;
+ const adjacent = await get<GraphIndexMembership>(KV.graphMembership, membershipKey("adjacency", id));
+ for (const edgeId of adjacent?.ids ?? []) {
+ if (topEdges.has(edgeId)) continue;
+ if (remainingEdgeReads-- <= 0) { next.sampleIncomplete = true; break; }
+ const edge = await get<GraphEdge>(KV.graphEdges, edgeId);
+ if (edge && !edge.stale) topEdges.set(edge.id, edge);
+ }
+ }
+ next.topEdges = [...topEdges.values()].filter((e) => ids.has(e.sourceNodeId) && ids.has(e.targetNodeId));
+ if (next.topEdges.length > MAX_SNAPSHOT_EDGES) {
+ next.topEdges = next.topEdges.slice(-MAX_SNAPSHOT_EDGES);
+ next.sampleIncomplete = true;
+ }
+ if (next.stats.totalNodes === 0) { next.topNodes = []; next.topEdges = []; next.topDegrees = {}; }
+ next.updatedAt = new Date().toISOString();
+ next.dirty = false;
+ const pending = { ...before, dirty: true, pendingMutation: { writes: [...writes.values()], snapshot: next } };
+ // Absolute writes make replay idempotent even if the engine committed a
+ // write whose response was lost. The final snapshot clears the journal.
+ if (Buffer.byteLength(JSON.stringify(pending), "utf8") > 8 * 1024 * 1024) {
+ throw new Error("Graph reconciliation batch exceeds the 8 MiB state payload budget; reduce graph record size");
+ }
+ await target.set(KV.graphSnapshot, "current", pending);
+ for (const write of writes.values()) {
+ if (write.value === null) await target.delete(write.scope, write.key);
+ else await target.set(write.scope, write.key, write.value);
+ }
+ await target.set(KV.graphSnapshot, "current", next);
+ return next;
+ });
+ }
+ return result;
+ };
+ return withKeyedLock("graph:persist", () => options.replace
+ ? replaceGraphGeneration(kv, (fresh) => run(fresh, true))
+ : run(kv));
+}
diff --git a/src/state/keyed-mutex.ts b/src/state/keyed-mutex.ts
index 28d9ceac..6ac2ac6a 100644
--- a/src/state/keyed-mutex.ts
+++ b/src/state/keyed-mutex.ts
@@ -1,3 +1,26 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+type LockContext = { active: boolean; after: Map<string | symbol, () => Promise<void>> };
+type LockFrame = { key: string; context: LockContext; parent?: LockFrame };
+const held = new AsyncLocalStorage<LockFrame>();
+
+function heldContext(key: string): LockContext | undefined {
+ for (let frame = held.getStore(); frame; frame = frame.parent) {
+ if (frame.key === key) return frame.context;
+ }
+}
+
+export function isKeyedLockHeld(key: string): boolean {
+ return heldContext(key)?.active ?? false;
+}
+
+export function afterKeyedLock(key: string, fn: () => Promise<void>, taskKey?: string): boolean {
+ const context = heldContext(key);
+ if (!context?.active) return false;
+ context.after.set(taskKey ?? Symbol(), fn);
+ return true;
+}
+
const locks = new Map<string, Promise<void>>();
export function withKeyedLock<T>(
@@ -5,16 +28,34 @@ export function withKeyedLock<T>(
fn: () => Promise<T>,
): Promise<T> {
const prev = locks.get(key) ?? Promise.resolve();
- const next = prev.then(fn, fn);
+ const context: LockContext = { active: true, after: new Map() };
+ const run = () => held.run({ key, context, parent: held.getStore() }, fn);
+ const next = prev.then(run, run);
const cleanup = next.then(
- () => {},
- () => {},
+ () => { context.active = false; },
+ () => { context.active = false; },
);
locks.set(key, cleanup);
cleanup.then(() => {
if (locks.get(key) === cleanup) locks.delete(key);
});
- return next;
+ const flush = async () => {
+ await cleanup;
+ const errors: unknown[] = [];
+ for (const notify of context.after.values()) {
+ try { await notify(); } catch (error) { errors.push(error); }
+ }
+ return errors;
+ };
+ return next.then(
+ async (value) => {
+ const errors = await flush();
+ if (errors.length === 1) throw errors[0];
+ if (errors.length > 1) throw new AggregateError(errors, "Deferred lock callbacks failed");
+ return value;
+ },
+ async (error) => { await flush(); throw error; },
+ );
}
export function withKeyedLocks<T>(keys: string[], fn: () => Promise<T>): Promise<T> {
diff --git a/src/state/kv.ts b/src/state/kv.ts
index a1b1ddc1..f31e591e 100644
--- a/src/state/kv.ts
+++ b/src/state/kv.ts
@@ -1,5 +1,7 @@
import type { IIIClient } from 'iii-sdk'
import { withKeyedLock } from './keyed-mutex.js'
+import { resolveGraphScope, notifyGraphGenerationChange } from './graph-generation.js'
+import { ensureGraphConsistency, noteGraphSnapshotWrite } from './graph-consistency.js'
export type StateBackend = 'file' | 'redis'
@@ -112,6 +114,8 @@ export class StateKV {
}
async get<T = unknown>(scope: string, key: string): Promise<T | null> {
+ scope = await resolveGraphScope(this, scope)
+ await ensureGraphConsistency(this, scope)
return this.sdk.trigger<{ scope: string; key: string }, T | null>({
function_id: 'state::get',
payload: { scope, key },
@@ -119,36 +123,75 @@ export class StateKV {
}
async set<T = unknown>(scope: string, key: string, value: T): Promise<T> {
- return this.sdk.trigger<{ scope: string; key: string; value: T }, T>({
- function_id: 'state::set',
- payload: { scope, key, value },
- })
+ 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 {
+ noteGraphSnapshotWrite(this, scope, key)
+ }
+ await notifyGraphGenerationChange(this, scope, key)
+ return result
}
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 () => {
- const oldValue = await this.get<unknown>(scope, key)
- const newValue = applyUpdateOps(oldValue, ops)
- await this.set(scope, key, newValue)
- const result: UpdateResult = { old_value: oldValue, new_value: newValue, errors: [] }
+ // 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 result as T
})
}
- return this.sdk.trigger<{ scope: string; key: string; ops: UpdateOp[] }, T>({
- function_id: 'state::update',
- payload: { scope, key, ops },
- })
+ let result: T
+ try {
+ result = await this.sdk.trigger<{ scope: string; key: string; ops: UpdateOp[] }, T>({
+ function_id: 'state::update',
+ payload: { scope, key, ops },
+ })
+ } finally {
+ noteGraphSnapshotWrite(this, scope, key)
+ }
+ await notifyGraphGenerationChange(this, scope, key)
+ return result
}
async delete(scope: string, key: string): Promise<void> {
- return this.sdk.trigger<{ scope: string; key: string }, void>({
- function_id: 'state::delete',
- payload: { scope, key },
- })
+ scope = await resolveGraphScope(this, scope)
+ await ensureGraphConsistency(this, scope)
+ noteGraphSnapshotWrite(this, scope, key)
+ try {
+ await this.sdk.trigger<{ scope: string; key: string }, void>({
+ function_id: 'state::delete',
+ payload: { scope, key },
+ })
+ } finally {
+ noteGraphSnapshotWrite(this, scope, key)
+ }
+ await notifyGraphGenerationChange(this, scope, key)
}
async list<T = unknown>(scope: string): Promise<T[]> {
+ scope = await resolveGraphScope(this, scope)
+ await ensureGraphConsistency(this, scope)
const values = await this.sdk.trigger<{ scope: string }, T[]>({
function_id: 'state::list',
payload: { scope },
diff --git a/src/state/schema.ts b/src/state/schema.ts
index eaecb6de..924cc9cf 100644
--- a/src/state/schema.ts
+++ b/src/state/schema.ts
@@ -16,11 +16,13 @@ export const KV = {
profiles: "mem:profiles",
claudeBridge: "mem:claude-bridge",
graphNodes: "mem:graph:nodes",
+ graphControl: "mem:graph:control",
graphEdges: "mem:graph:edges",
graphSnapshot: "mem:graph:snapshot",
graphNameIndex: "mem:graph:name-index",
graphEdgeKey: "mem:graph:edge-key",
graphNodeDegree: "mem:graph:node-degree",
+ graphMembership: "mem:graph:membership",
semantic: "mem:semantic",
procedural: "mem:procedural",
teamShared: (teamId: string) => `mem:team:${teamId}:shared`,
diff --git a/src/state/search-index.ts b/src/state/search-index.ts
index 895f66ef..902ef33b 100644
--- a/src/state/search-index.ts
+++ b/src/state/search-index.ts
@@ -11,17 +11,25 @@ interface IndexEntry {
layer: SearchResultLayer;
}
+export interface SearchIndexRevision {
+ isCurrent(): boolean;
+ release(): void;
+}
+
export class SearchIndex {
private entries: Map<string, IndexEntry> = new Map();
private invertedIndex: Map<string, Set<string>> = new Map();
private docTermCounts: Map<string, Map<string, number>> = new Map();
private totalDocLength = 0;
private sortedTerms: string[] | null = null;
+ private revisionGeneration: object = {};
+ private absentRevisions = new Map<string, { token: object; readers: number }>();
private readonly k1 = 1.2;
private readonly b = 0.75;
add(obs: CompressedObservation, layer: SearchResultLayer = "observation"): void {
+ this.invalidateAbsentRevision(obs.id);
if (this.entries.has(obs.id)) this.remove(obs.id);
const terms = this.extractTerms(obs);
const termFreq = new Map<string, number>();
@@ -51,6 +59,48 @@ export class SearchIndex {
this.sortedTerms = null;
}
+ watchRevision(id: string): SearchIndexRevision {
+ const generation = this.revisionGeneration;
+ const entry = this.entries.get(id);
+ if (entry) {
+ return {
+ isCurrent: () => this.revisionGeneration === generation && this.entries.get(id) === entry,
+ release: () => {},
+ };
+ }
+ // Only absent IDs need a lease: retaining deleted-ID tombstones would grow
+ // forever, while one shared absent epoch would cancel unrelated writes.
+ let slot = this.absentRevisions.get(id);
+ if (!slot) {
+ slot = { token: {}, readers: 0 };
+ this.absentRevisions.set(id, slot);
+ }
+ slot.readers++;
+ const token = slot.token;
+ let released = false;
+ return {
+ isCurrent: () => !released && this.revisionGeneration === generation &&
+ this.entries.get(id) === undefined && slot.token === token,
+ release: () => {
+ if (released) return;
+ released = true;
+ slot.readers--;
+ if (slot.readers === 0 && this.absentRevisions.get(id) === slot) this.absentRevisions.delete(id);
+ },
+ };
+ }
+
+ private invalidateAbsentRevision(id: string): void {
+ const slot = this.absentRevisions.get(id);
+ if (slot) slot.token = {};
+ }
+
+ invalidateRevision(id: string): void {
+ this.invalidateAbsentRevision(id);
+ const entry = this.entries.get(id);
+ if (entry) this.entries.set(id, { ...entry });
+ }
+
has(id: string): boolean {
return this.entries.has(id);
}
@@ -83,6 +133,7 @@ export class SearchIndex {
}
remove(id: string): void {
+ this.invalidateAbsentRevision(id);
const entry = this.entries.get(id);
if (!entry) return;
@@ -201,6 +252,8 @@ export class SearchIndex {
}
clear(): void {
+ this.revisionGeneration = {};
+ this.absentRevisions.clear();
this.entries.clear();
this.invertedIndex.clear();
this.docTermCounts.clear();
@@ -209,6 +262,8 @@ export class SearchIndex {
}
restoreFrom(other: SearchIndex): void {
+ this.revisionGeneration = {};
+ this.absentRevisions.clear();
this.entries = new Map(
Array.from(other.entries.entries()).map(([k, v]) => [k, { ...v }]),
);
diff --git a/src/state/viewer-counts.ts b/src/state/viewer-counts.ts
index 76a6b020..dbc66d33 100644
--- a/src/state/viewer-counts.ts
+++ b/src/state/viewer-counts.ts
@@ -40,6 +40,11 @@ export function setViewerCountsEmitter(fn: ((counts: ViewerCounts) => void) | nu
emitter = fn;
}
+export function invalidateViewerCounts(): void {
+ counts = null;
+ if (loading) changedWhileLoading = true;
+}
+
function inAgentScope(record: { agentId?: string } | null | undefined): boolean {
if (!record) return false;
return !isAgentScopeIsolated() || record.agentId === getAgentId();
@@ -94,8 +99,10 @@ export async function getViewerCounts(kv: StateKV): Promise<ViewerCounts> {
changedWhileLoading = false;
result = await readCounts(kv);
}
+ // A second concurrent change can exhaust the bounded refresh attempts.
+ // Return this read, but let the next request refresh instead of caching it.
+ counts = changedWhileLoading ? null : result;
changedWhileLoading = false;
- counts = result;
return result;
})().finally(() => {
loading = null;
diff --git a/src/triggers/api.ts b/src/triggers/api.ts
index c3278714..42750e5c 100644
--- a/src/triggers/api.ts
+++ b/src/triggers/api.ts
@@ -9,6 +9,7 @@ import { KV } from "../state/schema.js";
import { isSearchLayer, type SearchLayer } from "../state/search-layer.js";
import { checkPayloadFrameSize } from "../state/frame-guard.js";
import { StateKV } from "../state/kv.js";
+import { pinGraphState } from "../state/graph-generation.js";
import { addSessionToProjectIndex } from "../state/session-index.js";
import { getLatestHealth } from "../health/monitor.js";
import type { MetricsStore } from "../eval/metrics-store.js";
@@ -3574,11 +3575,12 @@ export function registerApiTriggers(
actions: df(actions, "updatedAt"),
};
if (!project) {
+ const graphState = await pinGraphState(kv);
const semantic = await kv.list<import("../types.js").SemanticMemory>(KV.semantic);
const procedural = await kv.list<import("../types.js").ProceduralMemory>(KV.procedural);
const relations = await kv.list<import("../types.js").MemoryRelation>(KV.relations);
- const graphNodes = await kv.list<import("../types.js").GraphNode>(KV.graphNodes);
- const graphEdges = await kv.list<import("../types.js").GraphEdge>(KV.graphEdges);
+ const graphNodes = await graphState.list<import("../types.js").GraphNode>(KV.graphNodes);
+ const graphEdges = await graphState.list<import("../types.js").GraphEdge>(KV.graphEdges);
body.semantic = df(semantic, "updatedAt");
body.procedural = df(procedural, "updatedAt");
body.relations = df(relations, "createdAt");
diff --git a/src/triggers/viewer-streams.ts b/src/triggers/viewer-streams.ts
index 2d07a84c..a75602bf 100644
--- a/src/triggers/viewer-streams.ts
+++ b/src/triggers/viewer-streams.ts
@@ -1,6 +1,8 @@
import type { IIIClient } from "iii-sdk";
import type { HttpRequest } from "@iii-dev/helpers/http";
import type { StateKV } from "../state/kv.js";
+import { isLegacyGraphState, setGraphGenerationListener } from "../state/graph-generation.js";
+import { withKeyedLock } from "../state/keyed-mutex.js";
import { KV } from "../state/schema.js";
import type {
Action,
@@ -26,6 +28,7 @@ import {
} from "../functions/search.js";
import {
getViewerCounts,
+ invalidateViewerCounts,
noteGraphStats,
noteRowChange,
setViewerCountsEmitter,
@@ -194,23 +197,43 @@ export function registerViewerStreamTriggers(
void sendViewerEvent(sdk, eventId("audit", entry.id), "audit.created", { id: entry.id, audit: entry }).catch(() => {});
});
- let lastGraphSnapshotEventAt = 0;
+ let lastGraphSnapshotEventAt = Number.NEGATIVE_INFINITY;
+ let lastGenerationSnapshot: { generation: string | null; snapshot: GraphSnapshot | null } | null = null;
+
+ async function readGenerationSnapshot() {
+ for (let attempt = 0; attempt < 2; attempt++) {
+ const generation = await kv.get<string>(KV.graphControl, "generation");
+ const snapshot = await kv.get<GraphSnapshot>(KV.graphSnapshot, GRAPH_SNAPSHOT_KEY);
+ if (generation === await kv.get<string>(KV.graphControl, "generation")) {
+ return { generation, snapshot };
+ }
+ }
+ throw new Error("Graph generation changed while reading snapshot");
+ }
sdk.registerFunction(
"event::viewer::graph-snapshot-changed",
- async (payload: StatePayload<GraphSnapshot>) => {
+ async (payload: StatePayload<GraphSnapshot>) => withKeyedLock("graph:viewer-events", async () => {
if (payload.key !== GRAPH_SNAPSHOT_KEY) return { emitted: false };
+ if (!await isLegacyGraphState(kv)) return { emitted: false };
const snapshot = isStateDelete(payload) ? null : payload.new_value ?? null;
+ if (snapshot?.pendingMutation) return { emitted: false };
noteGraphStats(snapshot?.stats ?? { totalNodes: 0, totalEdges: 0, nodesByType: {}, edgesByType: {} });
- lastGraphSnapshotEventAt = Date.now();
- await sendViewerEvent(sdk, eventId("graph", "snapshot"), "graph.changed", {
- source: "snapshot",
- stats: snapshot?.stats ?? null,
- updatedAt: snapshot?.updatedAt ?? new Date().toISOString(),
- resetAt: snapshot?.resetAt ?? null,
- delta: graphSnapshotDelta(payload.old_value ?? null, snapshot),
- });
+ try {
+ await sendViewerEvent(sdk, eventId("graph", "snapshot"), "graph.changed", {
+ source: "snapshot",
+ generation: null,
+ stats: snapshot?.stats ?? null,
+ updatedAt: snapshot?.updatedAt ?? new Date().toISOString(),
+ resetAt: snapshot?.resetAt ?? null,
+ delta: graphSnapshotDelta(payload.old_value ?? null, snapshot),
+ });
+ lastGraphSnapshotEventAt = Date.now();
+ } catch (error) {
+ lastGraphSnapshotEventAt = Number.NEGATIVE_INFINITY;
+ throw error;
+ }
return { emitted: true };
- },
+ }),
);
sdk.registerTrigger({
type: "state",
@@ -245,13 +268,62 @@ export function registerViewerStreamTriggers(
}
for (const [kind, scope] of [["nodes", KV.graphNodes], ["edges", KV.graphEdges]] as const) {
const functionId = `event::viewer::graph-${kind}-changed`;
- sdk.registerFunction(functionId, async () => {
+ sdk.registerFunction(functionId, async () => withKeyedLock("graph:viewer-events", async () => {
+ if (!await isLegacyGraphState(kv)) return { emitted: false };
noteGraphItem(kind);
return { emitted: true };
- });
+ }));
sdk.registerTrigger({ type: "state", function_id: functionId, config: { scope } });
}
+ setGraphGenerationListener(async (kind) => withKeyedLock("graph:viewer-events", async () => {
+ if (kind === "nodes" || kind === "edges") {
+ noteGraphItem(kind);
+ return;
+ }
+ if (kind === "reset") {
+ if (graphItemsTimer) clearTimeout(graphItemsTimer);
+ graphItemsTimer = null;
+ pendingGraphItems.nodes = 0;
+ pendingGraphItems.edges = 0;
+ }
+ let current: Awaited<ReturnType<typeof readGenerationSnapshot>>;
+ try {
+ current = await readGenerationSnapshot();
+ } catch (error) {
+ invalidateViewerCounts();
+ lastGraphSnapshotEventAt = Number.NEGATIVE_INFINITY;
+ await sendViewerEvent(sdk, eventId("graph", "invalidation"), "graph.changed", {
+ source: "items",
+ coveredBySnapshot: false,
+ ...(kind === "reset" ? { reset: true } : {}),
+ updatedAt: new Date().toISOString(),
+ }).catch(() => {});
+ throw error;
+ }
+ const { generation, snapshot } = current;
+ const reset = kind === "reset" || (lastGenerationSnapshot !== null && lastGenerationSnapshot.generation !== generation);
+ const before = !reset && lastGenerationSnapshot?.generation === generation ? lastGenerationSnapshot.snapshot : null;
+ const nextBaseline = { generation, snapshot: structuredClone(snapshot) };
+ noteGraphStats(snapshot?.stats ?? { totalNodes: 0, totalEdges: 0, nodesByType: {}, edgesByType: {} });
+ try {
+ await sendViewerEvent(sdk, eventId("graph", "snapshot"), "graph.changed", {
+ source: "snapshot",
+ generation,
+ reset,
+ stats: snapshot?.stats ?? null,
+ updatedAt: snapshot?.updatedAt ?? new Date().toISOString(),
+ resetAt: snapshot?.resetAt ?? null,
+ delta: graphSnapshotDelta(before, snapshot),
+ });
+ lastGraphSnapshotEventAt = Date.now();
+ lastGenerationSnapshot = nextBaseline;
+ } catch (error) {
+ lastGraphSnapshotEventAt = Number.NEGATIVE_INFINITY;
+ throw error;
+ }
+ }));
+
sdk.registerFunction(
"event::viewer::consolidation-changed",
async (payload: StatePayload<ConsolidationRunRecord>) => {
@@ -301,7 +373,7 @@ export function registerViewerStreamTriggers(
if (authErr) return authErr;
const [health, graph, lastRun] = await Promise.all([
getLatestHealth(kv).catch(() => null),
- kv.get<GraphSnapshot>(KV.graphSnapshot, GRAPH_SNAPSHOT_KEY).catch(() => null),
+ readGenerationSnapshot().catch(() => null),
kv.get<ConsolidationRunRecord>(KV.config, CONSOLIDATION_LAST_RUN_KEY).catch(() => null),
]);
return {
@@ -316,8 +388,8 @@ export function registerViewerStreamTriggers(
provider: detectLlmProviderKind(),
embeddingProvider: getEmbeddingProvider()?.name ?? "none",
flags: buildConfigFlags(),
- graph: graph
- ? { stats: graph.stats, updatedAt: graph.updatedAt, resetAt: graph.resetAt ?? null }
+ graph: graph?.snapshot
+ ? { stats: graph.snapshot.stats, updatedAt: graph.snapshot.updatedAt, resetAt: graph.snapshot.resetAt ?? null, generation: graph.generation }
: null,
consolidation: {
lastRun: lastRun ?? null,
diff --git a/src/types.ts b/src/types.ts
index b847f1e8..45f8698f 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -504,6 +504,21 @@ export interface GraphQueryResult {
warning?: string;
}
+export interface GraphIndexMembership {
+ ids: string[];
+}
+
+export interface GraphMutationWrite {
+ scope: string;
+ key: string;
+ value: unknown;
+}
+
+export interface GraphMutationJournal {
+ writes: GraphMutationWrite[];
+ snapshot: GraphSnapshot;
+}
+
export interface GraphSnapshot {
version: 1;
topNodes: GraphNode[];
@@ -523,6 +538,8 @@ export interface GraphSnapshot {
updatedAt: string;
dirty: boolean;
resetAt?: string;
+ sampleIncomplete?: boolean;
+ pendingMutation?: GraphMutationJournal;
}
export type ConsolidationTier =
diff --git a/src/viewer/index.html b/src/viewer/index.html
index 21a28844..346be2bd 100644
--- a/src/viewer/index.html
+++ b/src/viewer/index.html
@@ -1670,7 +1670,7 @@
var state = {
activeTab: 'dashboard',
dashboard: { loaded: false },
- graph: { loaded: false, loading: false, dirty: false, nodeMap: {}, edgeMap: {}, degrees: {}, rev: 0, localDegree: null, localDegreeRev: -1, stats: null, hidden: {}, search: '', searchOpen: false, searchIndex: 0, selectedId: null, detail: null, queryError: null, disabledInfo: null, warning: '', truncated: false, totalNodes: 0, totalEdges: 0, requestSeq: 0, fetches: 0, patches: 0, lastPatchAt: 0, fresh: {}, simStale: false, rebuildResult: '' },
+ graph: { loaded: false, loading: false, dirty: false, nodeMap: {}, edgeMap: {}, degrees: {}, rev: 0, localDegree: null, localDegreeRev: -1, stats: null, hidden: {}, search: '', searchOpen: false, searchIndex: 0, selectedId: null, detail: null, queryError: null, disabledInfo: null, warning: '', truncated: false, totalNodes: 0, totalEdges: 0, requestSeq: 0, searchRequestSeq: 0, resetSeq: 0, generation: undefined, fetches: 0, patches: 0, lastPatchAt: 0, fresh: {}, simStale: false, rebuildResult: '' },
memories: { search: '', typeFilter: '', projectFilter: '', agentFilter: '', selectedId: null, nextCursor: null, loadingMore: false, searchIds: null, searchMode: '', searching: false, query: null, facets: null, checked: {}, editing: null, saving: false, pendingId: null, fetches: {}, diffId: null, error: '' },
sessions: { selectedId: null, autoSelected: false, closed: false, nextCursor: null, loadingMore: false, filters: { q: '', project: '', agent: '', status: '' }, query: null, facets: null, detail: null, pendingObs: null, notice: null, summarizing: '' },
audit: { opFilter: '', selectedIdx: null, from: '', to: '', q: '', query: null, loadingMore: false, exhausted: {}, fresh: {} },
@@ -2358,11 +2358,14 @@
});
}
- async function loadSnapshot() {
+ async function loadSnapshot(retried) {
+ var resetSeq = state.graph.resetSeq;
var snap = await apiGet('viewer/snapshot');
+ if (resetSeq !== state.graph.resetSeq) return retried ? false : loadSnapshot(true);
if (!snap) return false;
var graphBefore = store.graph && store.graph.updatedAt;
var reconnect = !!store.snapshotAt;
+ noteGraphGeneration(snap.graph);
applySnapshot(store, snap);
renderFlagsChip();
renderFlagsPanel();
@@ -2806,8 +2809,54 @@
return graphNodeList().filter(function(n) { return !deg[n.id]; }).length;
}
+ function clearGraphView() {
+ var g = state.graph;
+ g.resetSeq++;
+ g.requestSeq++;
+ g.searchRequestSeq++;
+ g.selectedId = null;
+ g.detail = null;
+ g.nodeMap = {};
+ g.edgeMap = {};
+ g.degrees = {};
+ g.fresh = {};
+ g.stats = null;
+ g.totalNodes = 0;
+ g.totalEdges = 0;
+ g.truncated = false;
+ g.loading = false;
+ g.loaded = false;
+ g.dirty = false;
+ g.queryError = null;
+ g.disabledInfo = null;
+ g.warning = '';
+ g.searchOpen = false;
+ g.rev++;
+ g.simStale = true;
+ if (graphReloadTimer) clearTimeout(graphReloadTimer);
+ graphReloadTimer = null;
+ graphSim.hoverId = null;
+ graphSim.drag = null;
+ graphSim.nodes = [];
+ graphSim.byId = {};
+ graphSim.edges = [];
+ graphSim.isolatedBox = null;
+ setRouteEntity('graph', '');
+ renderGraphDetail();
+ requestGraphDraw();
+ }
+
+ function noteGraphGeneration(data) {
+ if (!data) return;
+ var g = state.graph;
+ if (data.reset === true && data.source === 'items') store.graph = null;
+ if (data.reset === true || ('generation' in data && g.generation !== undefined && g.generation !== data.generation)) clearGraphView();
+ if ('generation' in data) g.generation = data.generation;
+ }
+
function setGraphData(result) {
var g = state.graph;
+ if (!(result.nodes || []).length && !result.truncated && !result.totalNodes && (g.selectedId || g.detail || Object.keys(g.nodeMap).length)) clearGraphView();
var nodeMap = {};
var edgeMap = {};
(result.nodes || []).forEach(function(n) { if (n && n.id) nodeMap[n.id] = n; });
@@ -2841,6 +2890,7 @@
g.loading = false;
if (result === null) {
var stats = await api('graph/stats', { readErrorBody: true });
+ if (seq !== g.requestSeq) return;
if (stats && stats.error && stats.flag) {
g.disabledInfo = stats;
g.queryError = null;
@@ -2865,8 +2915,9 @@
function applyGraphDelta(delta) {
var g = state.graph;
- if (!g.loaded || !delta) return false;
+ if (!delta || (!g.loaded && !delta.full)) return false;
if (delta.full) {
+ if (!(delta.nodes || []).length && (g.selectedId || g.detail || Object.keys(g.nodeMap).length)) clearGraphView();
var keepNodes = {};
(delta.nodes || []).forEach(function(n) { keepNodes[n.id] = true; });
Object.keys(g.nodeMap).forEach(function(id) { if (!keepNodes[id] && id !== g.selectedId) delete g.nodeMap[id]; });
@@ -2893,13 +2944,14 @@
g.lastPatchAt = Date.now();
Object.keys(touched).forEach(function(id) { g.fresh[id] = Date.now(); });
if (g.selectedId && touched[g.selectedId] && g.detail && g.detail.id === g.selectedId) g.detail.stale = true;
+ g.loaded = true;
return true;
}
function handleGraphChange(data) {
var g = state.graph;
if (!data) return;
- if (!g.loaded) { g.dirty = true; return; }
+ noteGraphGeneration(data);
if (data.source === 'snapshot') {
if (data.delta && applyGraphDelta(data.delta)) {
if (graphSim.canvas && state.activeTab === 'graph') { syncGraphSim(false); requestGraphDraw(); setTimeout(requestGraphDraw, 4200); }
@@ -2925,10 +2977,10 @@
async function fetchGraphDetail(id) {
var g = state.graph;
- g.detail = { id: id, loading: true, data: null, error: '', stale: false };
+ var detail = g.detail = { id: id, loading: true, data: null, error: '', stale: false };
renderGraphDetail();
var res = await api('graph/node?id=' + encodeURIComponent(id), { readErrorBody: true });
- if (!g.detail || g.detail.id !== id) return;
+ if (g.detail !== detail) return;
if (!res || res.error) {
g.detail = { id: id, loading: false, data: null, error: res && res.error ? res.error : 'request failed', stale: false };
} else {
@@ -4021,9 +4073,11 @@
async function searchGraphRemote(q) {
var g = state.graph;
+ var seq = ++g.searchRequestSeq;
var box = document.getElementById('graph-search-results');
if (box) { box.hidden = false; box.innerHTML = '<div class="gs-empty">Searching all nodes…</div>'; }
var res = await apiPost('graph/query', { query: q, limit: 50 });
+ if (seq !== g.searchRequestSeq) return;
if (!res) {
if (box) box.innerHTML = '<div class="gs-empty">The server search failed.</div>';
return;
diff --git a/test/claude-bridge.test.ts b/test/claude-bridge.test.ts
index 42f2b027..ef0e33ea 100644
--- a/test/claude-bridge.test.ts
+++ b/test/claude-bridge.test.ts
@@ -1,31 +1,26 @@
-import { describe, it, expect, beforeEach, vi } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+ existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync,
+ rmSync, symlinkSync, writeFileSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
vi.mock("../src/logger.js", () => ({
logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
}));
-vi.mock("node:fs", () => ({
- existsSync: vi.fn(),
- readFileSync: vi.fn(),
- writeFileSync: vi.fn(),
- mkdirSync: vi.fn(),
-}));
-
-vi.mock("node:path", async () => ({
- ...(await vi.importActual("node:path")),
- dirname: vi.fn().mockReturnValue("/tmp"),
-}));
-
import { registerClaudeBridgeFunction } from "../src/functions/claude-bridge.js";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
import type { ClaudeBridgeConfig, Memory } from "../src/types.js";
+import { KV } from "../src/state/schema.js";
function mockKV() {
const store = new Map<string, Map<string, unknown>>();
return {
- get: async <T>(scope: string, key: string): Promise<T | null> => {
+ get: vi.fn(async <T>(scope: string, key: string): Promise<T | null> => {
return (store.get(scope)?.get(key) as T) ?? null;
- },
+ }),
set: async <T>(scope: string, key: string, data: T): Promise<T> => {
if (!store.has(scope)) store.set(scope, new Map());
store.get(scope)!.set(key, data);
@@ -34,146 +29,258 @@ function mockKV() {
delete: async (scope: string, key: string): Promise<void> => {
store.get(scope)?.delete(key);
},
- list: async <T>(scope: string): Promise<T[]> => {
+ list: vi.fn(async <T>(scope: string): Promise<T[]> => {
const entries = store.get(scope);
return entries ? (Array.from(entries.values()) as T[]) : [];
- },
+ }),
};
}
function mockSdk() {
const functions = new Map<string, Function>();
return {
- registerFunction: (idOrOpts: string | { id: string }, handler: Function) => {
- const id = typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id;
- functions.set(id, handler);
- },
- registerTrigger: () => {},
- trigger: async (idOrInput: string | { function_id: string; payload: unknown }, data?: unknown) => {
- const id = typeof idOrInput === "string" ? idOrInput : idOrInput.function_id;
- const payload = typeof idOrInput === "string" ? data : idOrInput.payload;
+ registerFunction: (id: string, handler: Function) => functions.set(id, handler),
+ trigger: async (id: string) => {
const fn = functions.get(id);
if (!fn) throw new Error(`No function: ${id}`);
- return fn(payload);
+ return fn();
},
};
}
-const enabledConfig: ClaudeBridgeConfig = {
- enabled: true,
- projectPath: "/tmp/my-project",
- memoryFilePath: "/tmp/.claude/MEMORY.md",
- lineBudget: 200,
-};
-
-const disabledConfig: ClaudeBridgeConfig = {
- enabled: false,
- projectPath: "",
- memoryFilePath: "",
- lineBudget: 200,
-};
+function memory(overrides: Partial<Memory> = {}): Memory {
+ return {
+ id: "mem_1",
+ createdAt: "2026-02-01T00:00:00Z",
+ updatedAt: "2026-02-01T00:00:00Z",
+ type: "pattern",
+ title: "Auth pattern",
+ content: "Always validate tokens",
+ concepts: ["auth"],
+ files: [],
+ sessionIds: ["ses_1"],
+ strength: 5,
+ version: 1,
+ isLatest: true,
+ project: "my-project",
+ ...overrides,
+ };
+}
describe("Claude Bridge Functions", () => {
let sdk: ReturnType<typeof mockSdk>;
let kv: ReturnType<typeof mockKV>;
+ let root: string;
+ let config: ClaudeBridgeConfig;
beforeEach(() => {
+ vi.clearAllMocks();
+ vi.stubEnv("AGENTMEMORY_PROJECT_NAME", "");
+ root = mkdtempSync(join(tmpdir(), "agentmemory-bridge-"));
+ config = {
+ enabled: true,
+ projectPath: join(root, "my-project"),
+ memoryFilePath: join(root, "claude", "memory", "MEMORY.md"),
+ lineBudget: 200,
+ };
+ mkdirSync(config.projectPath);
sdk = mockSdk();
kv = mockKV();
- vi.clearAllMocks();
+ registerClaudeBridgeFunction(sdk as never, kv as never, config);
+ });
+
+ afterEach(() => {
+ rmSync(root, { recursive: true, force: true });
+ vi.unstubAllEnvs();
});
- it("claude-bridge-read returns content when file exists", async () => {
- registerClaudeBridgeFunction(sdk as never, kv as never, enabledConfig);
+ function putFile(content: string) {
+ mkdirSync(dirname(config.memoryFilePath), { recursive: true });
+ writeFileSync(config.memoryFilePath, content);
+ }
- vi.mocked(existsSync).mockReturnValue(true);
- vi.mocked(readFileSync).mockReturnValue(
- "# Memory\n\n## Project Summary\nA test project\n\n## Key Memories\nSome memories",
- );
+ function sync() {
+ return sdk.trigger("mem::claude-bridge-sync");
+ }
- const result = (await sdk.trigger("mem::claude-bridge-read", {})) as {
- success: boolean;
- content: string;
- sections: Record<string, string>;
- };
+ function expectRefusal(result: { success: boolean; error: string }) {
+ expect(result.success).toBe(false);
+ expect(result.error).toContain(config.memoryFilePath);
+ expect(result.error).toContain("Refusing to replace");
+ expect(readdirSync(dirname(config.memoryFilePath))).toEqual(["MEMORY.md"]);
+ }
+ it("reads existing handwritten content without changing it", async () => {
+ const content = "# Memory\n\n## Project Summary\nA test project\n\n## Key Memories\nSome memories";
+ putFile(content);
+ const result = await sdk.trigger("mem::claude-bridge-read");
expect(result.success).toBe(true);
- expect(result.content).toContain("# Memory");
- expect(result.sections).toBeDefined();
+ expect(result.content).toBe(content);
expect(result.sections["Project Summary"]).toBe("A test project");
+ expect(readFileSync(config.memoryFilePath, "utf8")).toBe(content);
});
- it("claude-bridge-read returns empty when file does not exist", async () => {
- registerClaudeBridgeFunction(sdk as never, kv as never, enabledConfig);
+ it("returns empty content when the read target does not exist", async () => {
+ expect(await sdk.trigger("mem::claude-bridge-read")).toEqual({
+ success: true, content: "", parsed: false,
+ });
+ });
- vi.mocked(existsSync).mockReturnValue(false);
+ it("creates a missing file and its parent directories", async () => {
+ await kv.set(KV.memories, "mem_1", memory());
+ const result = await sync();
+ expect(result).toMatchObject({ success: true, changed: true, path: config.memoryFilePath });
+ expect(readFileSync(config.memoryFilePath, "utf8")).toContain("Always validate tokens");
+ expect(readdirSync(dirname(config.memoryFilePath))).toEqual(["MEMORY.md"]);
+ });
- const result = (await sdk.trigger("mem::claude-bridge-read", {})) as {
- success: boolean;
- content: string;
- parsed: boolean;
- };
+ it.each(["My handwritten notes\n", "", "# Agent Memory (auto-synced by agentmemory)\nUser addition\n"])(
+ "preserves existing content even if empty or bearing a generated header: %j",
+ async (content) => {
+ putFile(content);
+ expectRefusal(await sync());
+ expect(readFileSync(config.memoryFilePath, "utf8")).toBe(content);
+ },
+ );
- expect(result.success).toBe(true);
- expect(result.content).toBe("");
- expect(result.parsed).toBe(false);
- });
-
- it("claude-bridge-sync writes MEMORY.md with memories", async () => {
- registerClaudeBridgeFunction(sdk as never, kv as never, enabledConfig);
-
- const mem: Memory = {
- id: "mem_1",
- createdAt: "2026-02-01T00:00:00Z",
- updatedAt: "2026-02-01T00:00:00Z",
- type: "pattern",
- title: "Auth pattern",
- content: "Always validate tokens",
- concepts: ["auth"],
- files: [],
- sessionIds: ["ses_1"],
- strength: 5,
- version: 1,
- isLatest: true,
- };
- await kv.set("mem:memories", "mem_1", mem);
+ it("reports an identical existing export as an unchanged no-op", async () => {
+ await kv.set(KV.memories, "mem_1", memory());
+ await sync();
+ const original = lstatSync(config.memoryFilePath);
+ expect(await sync()).toMatchObject({ success: true, changed: false });
+ const after = lstatSync(config.memoryFilePath);
+ expect(after.ino).toBe(original.ino);
+ expect(after.mtimeMs).toBe(original.mtimeMs);
+ });
- vi.mocked(existsSync).mockReturnValue(true);
+ it("does not replace its own previous export when the source memories change", async () => {
+ await kv.set(KV.memories, "mem_1", memory());
+ await sync();
+ const original = readFileSync(config.memoryFilePath, "utf8");
+ await kv.set(KV.memories, "mem_1", memory({ content: "A new version" }));
+ expectRefusal(await sync());
+ expect(readFileSync(config.memoryFilePath, "utf8")).toBe(original);
+ });
- const result = (await sdk.trigger("mem::claude-bridge-sync", {})) as {
- success: boolean;
- path: string;
- lines: number;
- };
+ it("preserves a file created while the memory list is loading", async () => {
+ kv.list.mockImplementationOnce(async () => {
+ await Promise.resolve();
+ putFile("Created during state read");
+ return [memory()];
+ });
+ expectRefusal(await sync());
+ expect(readFileSync(config.memoryFilePath, "utf8")).toBe("Created during state read");
+ });
- expect(result.success).toBe(true);
- expect(result.path).toBe("/tmp/.claude/MEMORY.md");
- expect(writeFileSync).toHaveBeenCalled();
- const writtenContent = vi.mocked(writeFileSync).mock.calls[0][1] as string;
- expect(writtenContent).toContain("Auth pattern");
+ it("preserves edits to a generated file made during the profile lookup", async () => {
+ await kv.set(KV.memories, "mem_1", memory());
+ await sync();
+ const edited = readFileSync(config.memoryFilePath, "utf8") + "\nUser added this";
+ kv.get.mockImplementationOnce(async () => {
+ await Promise.resolve();
+ putFile(edited);
+ return null;
+ });
+ expectRefusal(await sync());
+ expect(readFileSync(config.memoryFilePath, "utf8")).toBe(edited);
});
- it("claude-bridge-sync returns error when not configured", async () => {
- registerClaudeBridgeFunction(sdk as never, kv as never, disabledConfig);
+ it("preserves a file created during the canonical profile lookup", async () => {
+ kv.get.mockImplementationOnce(async () => null);
+ kv.get.mockImplementationOnce(async () => {
+ await Promise.resolve();
+ putFile("Created during canonical profile read");
+ return null;
+ });
+ expectRefusal(await sync());
+ expect(readFileSync(config.memoryFilePath, "utf8")).toBe("Created during canonical profile read");
+ });
- const result = (await sdk.trigger("mem::claude-bridge-sync", {})) as {
- success: boolean;
- error: string;
- };
+ it("allows only one of two different concurrent exports to create the destination", async () => {
+ kv.list.mockImplementationOnce(async () => [memory({ content: "First export" })]);
+ kv.list.mockImplementationOnce(async () => [memory({ content: "Second export" })]);
+ const results = await Promise.all([sync(), sync()]);
+ expect(results.filter((r) => r.success)).toHaveLength(1);
+ expect(results.filter((r) => !r.success)).toHaveLength(1);
+ expect(readFileSync(config.memoryFilePath, "utf8")).toContain("First export");
+ expect(readdirSync(dirname(config.memoryFilePath))).toEqual(["MEMORY.md"]);
+ });
- expect(result.success).toBe(false);
- expect(result.error).toContain("not configured");
+ it.each([false, true])("refuses a symlink (dangling: %s) without touching its target", async (dangling) => {
+ mkdirSync(dirname(config.memoryFilePath), { recursive: true });
+ const target = join(root, "user-notes.md");
+ if (!dangling) writeFileSync(target, "User notes");
+ symlinkSync(target, config.memoryFilePath);
+ expectRefusal(await sync());
+ expect(lstatSync(config.memoryFilePath).isSymbolicLink()).toBe(true);
+ if (dangling) expect(existsSync(target)).toBe(false);
+ else expect(readFileSync(target, "utf8")).toBe("User notes");
+ });
+
+ it("refuses a symlink even when its target equals the generated content", async () => {
+ await sync();
+ const content = readFileSync(config.memoryFilePath, "utf8");
+ rmSync(config.memoryFilePath);
+ const target = join(root, "same.md");
+ writeFileSync(target, content);
+ symlinkSync(target, config.memoryFilePath);
+ expectRefusal(await sync());
+ expect(readFileSync(target, "utf8")).toBe(content);
});
- it("claude-bridge-read returns error when not configured", async () => {
- registerClaudeBridgeFunction(sdk as never, kv as never, disabledConfig);
+ it("preserves an existing directory at the destination", async () => {
+ mkdirSync(config.memoryFilePath, { recursive: true });
+ writeFileSync(join(config.memoryFilePath, "notes"), "User data");
+ expectRefusal(await sync());
+ expect(readFileSync(join(config.memoryFilePath, "notes"), "utf8")).toBe("User data");
+ });
- const result = (await sdk.trigger("mem::claude-bridge-read", {})) as {
- success: boolean;
- error: string;
- };
+ it.skipIf(process.platform === "win32")("refuses a FIFO without opening or blocking on it", async () => {
+ mkdirSync(dirname(config.memoryFilePath), { recursive: true });
+ execFileSync("mkfifo", [config.memoryFilePath]);
+ expectRefusal(await sync());
+ expect(lstatSync(config.memoryFilePath).isFIFO()).toBe(true);
+ });
- expect(result.success).toBe(false);
- expect(result.error).toContain("not configured");
+ it("exports only latest memories from the canonical project or exact legacy project path", async () => {
+ const records = [
+ memory(),
+ memory({ id: "legacy", project: config.projectPath, title: "Legacy scoped title" }),
+ memory({ id: "other", project: "different-project", title: "Other project secret" }),
+ memory({ id: "unscoped", project: undefined, title: "Unscoped secret" }),
+ memory({ id: "old", isLatest: false, title: "Superseded title" }),
+ ];
+ for (const record of records) await kv.set(KV.memories, record.id, record);
+ await kv.set(KV.profiles, "my-project", { summary: "Canonical project summary" });
+ await kv.set(KV.profiles, "different-project", { summary: "Other project summary" });
+ expect((await sync()).success).toBe(true);
+ const content = readFileSync(config.memoryFilePath, "utf8");
+ expect(content).toContain("Auth pattern");
+ expect(content).toContain("Legacy scoped title");
+ expect(content).toContain("Canonical project summary");
+ expect(content).not.toMatch(/Other project|Unscoped secret|Superseded title/);
+ });
+
+ it("honors the shared explicit project-name override", async () => {
+ vi.stubEnv("AGENTMEMORY_PROJECT_NAME", "custom-project");
+ await kv.set(KV.memories, "custom", memory({ project: "custom-project", title: "Custom project title" }));
+ await kv.set(KV.memories, "other", memory());
+ expect((await sync()).success).toBe(true);
+ const content = readFileSync(config.memoryFilePath, "utf8");
+ expect(content).toContain("Custom project title");
+ expect(content).not.toContain("Auth pattern");
+ });
+
+ it("refuses to export without a configured project", async () => {
+ config.projectPath = "";
+ expect(await sync()).toMatchObject({ success: false, error: "Claude bridge not configured" });
+ expect(existsSync(config.memoryFilePath)).toBe(false);
+ });
+
+ it.each(["read", "sync"])("returns an error when the bridge is disabled (%s)", async (direction) => {
+ config.enabled = false;
+ expect(await sdk.trigger(`mem::claude-bridge-${direction}`)).toMatchObject({
+ success: false, error: "Claude bridge not configured",
+ });
});
});
diff --git a/test/compress-viewer-stream.test.ts b/test/compress-viewer-stream.test.ts
index bc20e467..6d7c4755 100644
--- a/test/compress-viewer-stream.test.ts
+++ b/test/compress-viewer-stream.test.ts
@@ -14,13 +14,13 @@ import { registerCompressFunction } from "../src/functions/compress.js";
import { STREAM } from "../src/state/schema.js";
import type { MemoryProvider, RawObservation } from "../src/types.js";
-const VALID_COMPRESS_XML = `<type>command_run</type>
+const VALID_COMPRESS_XML = `<observation><type>command_run</type>
<title>Ran a probe command</title>
<facts><fact>Ran echo probe</fact></facts>
<narrative>The agent ran a probe command</narrative>
<concepts><concept>testing</concept></concepts>
<files></files>
-<importance>5</importance>`;
+<importance>5</importance></observation>`;
function mockKV() {
const store = new Map<string, Map<string, unknown>>();
diff --git a/test/compression-validation.test.ts b/test/compression-validation.test.ts
new file mode 100644
index 00000000..42f30dee
--- /dev/null
+++ b/test/compression-validation.test.ts
@@ -0,0 +1,185 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { parseCompressionXml } from "../src/prompts/compression-output.js";
+import { compressWithRetry } from "../src/eval/self-correct.js";
+import { CompressOutputSchema } from "../src/eval/schemas.js";
+import { registerCompressFunction } from "../src/functions/compress.js";
+import { buildSyntheticCompression } from "../src/functions/compress-synthetic.js";
+import { NoopProvider } from "../src/providers/noop.js";
+import type { CompressedObservation, MemoryProvider, RawObservation } from "../src/types.js";
+
+const search = vi.hoisted(() => ({ add: vi.fn(), save: vi.fn(), vector: vi.fn() }));
+vi.mock("../src/functions/search.js", () => ({
+ getSearchIndex: () => ({ add: search.add }),
+ scheduleIndexSave: search.save,
+ vectorIndexAddGuarded: search.vector,
+}));
+vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }));
+
+const xml = `<observation>
+<type>file_edit</type><title>Updated configuration</title>
+<facts><fact>The server port is now 3111.</fact></facts>
+<narrative>Updated the server configuration to use the documented port.</narrative>
+<concepts><concept>configuration</concept></concepts><files><file>config.ts</file></files>
+<importance>7</importance></observation>`;
+
+const raw: RawObservation = {
+ id: "obs-validation", sessionId: "session-validation", hookType: "post_tool_use",
+ timestamp: "2026-10-12T00:00:00Z", toolName: "Edit",
+ toolInput: { file_path: "config.ts" }, toolOutput: "Saved the original evidence", raw: {},
+};
+
+function rig(provider: MemoryProvider, previous: RawObservation | CompressedObservation = raw) {
+ let stored = structuredClone(previous);
+ const kv = {
+ list: vi.fn(async () => [structuredClone(stored)]),
+ set: vi.fn(async (_scope: string, _id: string, value: CompressedObservation) => {
+ stored = structuredClone(value);
+ return value;
+ }),
+ };
+ const trigger = vi.fn(async () => undefined);
+ const record = vi.fn(async () => undefined);
+ let handler!: (data: { observationId: string; sessionId: string; raw: RawObservation }) => Promise<unknown>;
+ registerCompressFunction({ trigger, registerFunction: (_id: string, fn: typeof handler) => { handler = fn; } } as never,
+ kv as never, provider, { record } as never);
+ return {
+ call: () => handler({ observationId: raw.id, sessionId: raw.sessionId, raw }),
+ stored: () => stored, kv, trigger, record,
+ };
+}
+
+function providerReturning(...responses: string[]): MemoryProvider {
+ let index = 0;
+ return { name: "test", summarize: vi.fn(), compress: vi.fn(async () => responses[Math.min(index++, responses.length - 1)]) };
+}
+
+beforeEach(() => vi.clearAllMocks());
+
+describe("compression output boundaries", () => {
+ it.each([
+ ["observation", xml],
+ ["XML fence", `\`\`\`xml\n${xml}\n\`\`\``],
+ ["plain fence", `\`\`\`\n${xml}\n\`\`\``],
+ ["thought preamble", `<thought><title>${"wrong ".repeat(150)}</title><type>other</type></thought>\n${xml}`],
+ ["think then fence", `<think>Use <title>a title</title>.</think>\n\`\`\`xml\n${xml}\n\`\`\``],
+ ])("reads only the observation in %s", (_name, response) => {
+ const parsed = parseCompressionXml(response);
+ expect(CompressOutputSchema.safeParse(parsed).success).toBe(true);
+ expect(parsed?.title).toBe("Updated configuration");
+ expect(parsed?.type).toBe("file_edit");
+ });
+
+ it("decodes XML text without interpreting encoded tags as structure", () => {
+ const parsed = parseCompressionXml(xml.replace("Updated configuration", "Use &lt;title&gt; &amp; &#x1F600;")
+ .replace("<concepts><concept>configuration</concept></concepts>", "<concepts />"));
+ expect(parsed?.title).toBe("Use <title> & 😀");
+ expect(parsed?.concepts).toEqual([]);
+ });
+
+ it.each([
+ ["missing envelope", xml.replace(/<\/?observation>/g, "")],
+ ["missing closing envelope", xml.replace("</observation>", "")],
+ ["multiple observations", xml + xml],
+ ["outer wrapper", `<result>${xml}</result>`],
+ ["nested observations", `<observation>${xml}</observation>`],
+ ["duplicate title", xml.replace("</title>", "</title><title>Other</title>")],
+ ["nested title", xml.replace("Updated configuration", "<title>Other</title>")],
+ ["nested field wrapper", xml.replace("<title>", "<result><title>").replace("</title>", "</title></result>")],
+ ["mismatched closing field", xml.replace("</title>", "</subtitle>")],
+ ["duplicate list", xml.replace("</facts>", "</facts><facts><fact>other</fact></facts>")],
+ ["nested list item", xml.replace("The server port is now 3111.", "<fact>Other</fact>")],
+ ["wrong list child", xml.replace(/<\/?fact>/g, (tag) => tag.replace("fact", "title"))],
+ ["empty fact", xml.replace("The server port is now 3111.", " ")],
+ ["unknown field", xml.replace("</observation>", "<surprise>data</surprise></observation>")],
+ ["unclosed reasoning", `<think>Reasoning ${xml}`],
+ ["content after envelope", `${xml}<title>Other</title>`],
+ ["unescaped text", xml.replace("Updated configuration", "Config & settings")],
+ ["unknown entity", xml.replace("Updated configuration", "&secret;")],
+ ["invalid numeric entity", xml.replace("Updated configuration", "&#x110000;")],
+ ["doctype", `<!DOCTYPE observation [<!ENTITY secret SYSTEM 'file:///fixture'>]>${xml}`],
+ ])("rejects %s before persistence", async (_name, response) => {
+ const provider = providerReturning(response);
+ const r = rig(provider);
+ expect(await r.call()).toEqual({ success: false, error: "parse_failed" });
+ expect(provider.compress).toHaveBeenCalledTimes(2);
+ expect(r.stored()).toEqual(raw);
+ expect(r.kv.set).not.toHaveBeenCalled();
+ expect(search.add).not.toHaveBeenCalled();
+ expect(search.vector).not.toHaveBeenCalled();
+ expect(r.trigger).not.toHaveBeenCalled();
+ expect(r.record).toHaveBeenCalledExactlyOnceWith("mem::compress", expect.any(Number), false);
+ });
+});
+
+describe("compression validation and retry", () => {
+ it.each([
+ ["long title", xml.replace("Updated configuration", "x".repeat(121))],
+ ["missing facts", xml.replace(/<facts>[\s\S]*?<\/facts>/, "")],
+ ["short narrative", xml.replace(/<narrative>[\s\S]*?<\/narrative>/, "<narrative>short</narrative>")],
+ ["unknown type", xml.replace("file_edit", "invalid_type")],
+ ["out-of-range importance", xml.replace("<importance>7", "<importance>11")],
+ ["partial numeric importance", xml.replace("<importance>7", "<importance>7bad")],
+ ["missing importance", xml.replace(/<importance>.*?<\/importance>/, "")],
+ ])("retains an existing valid summary and source after %s exhausts retries", async (_name, response) => {
+ const previous = { ...buildSyntheticCompression(raw), ...CompressOutputSchema.parse(parseCompressionXml(xml)), confidence: 0.9 };
+ const r = rig(providerReturning(response), previous);
+ expect(await r.call()).toEqual({ success: false, error: "validation_failed" });
+ expect(r.stored()).toEqual(previous);
+ expect(r.kv.set).not.toHaveBeenCalled();
+ expect(r.trigger).not.toHaveBeenCalled();
+ expect(search.add).not.toHaveBeenCalled();
+ expect(r.record).toHaveBeenCalledExactlyOnceWith("mem::compress", expect.any(Number), false);
+ });
+
+ it("persists only a successful retry and preserves the original evidence", async () => {
+ const provider = providerReturning(xml.replace("Updated configuration", "x".repeat(900)), xml);
+ const r = rig(provider, buildSyntheticCompression(raw));
+ expect(await r.call()).toMatchObject({ success: true, compressed: { title: "Updated configuration" } });
+ expect(provider.compress).toHaveBeenCalledTimes(2);
+ expect(r.kv.set).toHaveBeenCalledTimes(1);
+ expect((r.stored() as CompressedObservation).source?.toolOutput).toBe(raw.toolOutput);
+ expect(search.add).toHaveBeenCalledTimes(1);
+ expect(r.trigger).toHaveBeenCalledTimes(1);
+ expect(r.record).toHaveBeenCalledExactlyOnceWith("mem::compress", expect.any(Number), true, expect.any(Number));
+ });
+
+ it("validates decoded and scrubbed output and never broadcasts retained source", async () => {
+ const response = xml.replace("Updated configuration", "Updated &lt;private&gt;private-canary&lt;/private&gt;");
+ const r = rig(providerReturning(response));
+ const result = await r.call();
+ expect(result).toMatchObject({ success: true, compressed: { title: "Updated [REDACTED]" } });
+ expect(CompressOutputSchema.safeParse(r.stored()).success).toBe(true);
+ expect(JSON.stringify(r.stored())).not.toContain("private-canary");
+ expect(JSON.stringify(result)).not.toContain('"source"');
+ expect(JSON.stringify(r.trigger.mock.calls)).not.toContain(raw.toolOutput);
+ });
+
+ it("leaves synthetic data intact when a noop provider has no model output", async () => {
+ const previous = buildSyntheticCompression(raw);
+ expect(previous.facts).toEqual([]);
+ const r = rig(new NoopProvider(), previous);
+ expect(await r.call()).toEqual({ success: false, error: "parse_failed" });
+ expect(r.stored()).toEqual(previous);
+ expect(r.kv.set).not.toHaveBeenCalled();
+ });
+
+ it("leaves stored evidence intact if the retry provider call throws", async () => {
+ const provider = providerReturning("invalid");
+ vi.mocked(provider.compress)
+ .mockResolvedValueOnce("invalid")
+ .mockRejectedValueOnce(new Error("provider unavailable"));
+ const r = rig(provider);
+ expect(await r.call()).toEqual({ success: false, error: "compression_failed" });
+ expect(r.stored()).toEqual(raw);
+ expect(r.kv.set).not.toHaveBeenCalled();
+ expect(provider.compress).toHaveBeenCalledTimes(2);
+ expect(r.record).toHaveBeenCalledExactlyOnceWith("mem::compress", expect.any(Number), false);
+ });
+
+ it("returns a validation failure without exposing rejected output when retries are disabled", async () => {
+ const provider = providerReturning("invalid content");
+ const result = await compressWithRetry(provider, "system", "prompt", () => ({ valid: false, errors: ["invalid"] }), 0);
+ expect(result).toEqual({ valid: false, errors: ["invalid"], retried: false });
+ expect(provider.compress).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/test/fetch-body-deadline.test.ts b/test/fetch-body-deadline.test.ts
new file mode 100644
index 00000000..0726e642
--- /dev/null
+++ b/test/fetch-body-deadline.test.ts
@@ -0,0 +1,127 @@
+import { createServer, type RequestListener, type Server } from "node:http";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { fetchWithTimeout } from "../src/providers/_fetch.js";
+import { OpenAIProvider } from "../src/providers/openai.js";
+
+const servers: Server[] = [];
+
+async function serve(handler: RequestListener): Promise<string> {
+ const server = createServer(handler);
+ servers.push(server);
+ await new Promise<void>((resolve, reject) => {
+ server.once("error", reject);
+ server.listen(0, "127.0.0.1", resolve);
+ });
+ const address = server.address();
+ if (!address || typeof address === "string") throw new Error("Missing server port");
+ return `http://127.0.0.1:${address.port}`;
+}
+
+afterEach(async () => {
+ vi.restoreAllMocks();
+ vi.unstubAllEnvs();
+ await Promise.all(servers.splice(0).map(server => new Promise<void>(resolve => {
+ server.closeAllConnections();
+ server.close(() => resolve());
+ })));
+});
+
+describe("provider response body deadlines", () => {
+ it("does not dispatch a request for an already cancelled caller", async () => {
+ const controller = new AbortController();
+ controller.abort(new Error("cancelled before dispatch"));
+ const fetch = vi.spyOn(globalThis, "fetch");
+ await expect(fetchWithTimeout("http://127.0.0.1:1", {
+ signal: controller.signal,
+ }, 1000)).rejects.toThrow("cancelled before dispatch");
+ expect(fetch).not.toHaveBeenCalled();
+ });
+
+ it("keeps successful response metadata and JSON readable", async () => {
+ const url = await serve((_req, res) => {
+ res.writeHead(200, { "content-type": "application/json", "x-provider": "fixture" });
+ res.end(JSON.stringify({ ok: true }));
+ });
+ const response = await fetchWithTimeout(url, {}, 1000);
+ expect(response.status).toBe(200);
+ expect(response.url).toBe(`${url}/`);
+ expect(response.headers.get("x-provider")).toBe("fixture");
+ expect(await response.json()).toEqual({ ok: true });
+ });
+
+ it.each([200, 400, 429, 503])("aborts a stalled %i body after headers", async status => {
+ const url = await serve((_req, res) => {
+ res.writeHead(status, { "content-type": "application/json", "retry-after": "60" });
+ res.flushHeaders();
+ res.write('{"ok":');
+ const timer = setTimeout(() => res.end("true}"), 800);
+ res.on("close", () => clearTimeout(timer));
+ });
+ const response = await fetchWithTimeout(url, {}, 150);
+ expect(response.status).toBe(status);
+ await expect(response.text()).rejects.toThrow();
+ });
+
+ it("keeps one deadline through a retry and the final body", async () => {
+ let attempts = 0;
+ const url = await serve((_req, res) => {
+ attempts++;
+ if (attempts === 1) {
+ res.writeHead(429, { "retry-after": "0.4" });
+ res.end();
+ } else {
+ res.writeHead(200, { "content-type": "application/json" });
+ res.flushHeaders();
+ const timer = setTimeout(() => res.end('{"ok":true}'), 800);
+ res.on("close", () => clearTimeout(timer));
+ }
+ });
+ const response = await fetchWithTimeout(url, {}, 1000);
+ await expect(response.json()).rejects.toThrow();
+ expect(attempts).toBe(2);
+ });
+
+ it("cancels retry backoff promptly without another request", async () => {
+ const controller = new AbortController();
+ let attempts = 0;
+ let arrived!: () => void;
+ const firstRequest = new Promise<void>(resolve => { arrived = resolve; });
+ const url = await serve((_req, res) => {
+ attempts++;
+ res.writeHead(503, { "retry-after": "5" });
+ res.end();
+ arrived();
+ });
+ const pending = fetchWithTimeout(url, { signal: controller.signal }, 10000);
+ const rejected = expect(pending).rejects.toThrow("cancelled by caller");
+ await firstRequest;
+ await new Promise(resolve => setTimeout(resolve, 50));
+ controller.abort(new Error("cancelled by caller"));
+ await rejected;
+ expect(attempts).toBe(1);
+ }, 1500);
+
+ it("preserves caller cancellation while reading a body", async () => {
+ const controller = new AbortController();
+ const url = await serve((_req, res) => {
+ res.writeHead(200);
+ res.flushHeaders();
+ });
+ const response = await fetchWithTimeout(url, { signal: controller.signal }, 10000);
+ const pending = response.text();
+ controller.abort();
+ await expect(pending).rejects.toThrow();
+ });
+
+ it("reports the OpenAI timeout when its body stalls", async () => {
+ vi.stubEnv("OPENAI_TIMEOUT_MS", "150");
+ const url = await serve((_req, res) => {
+ res.writeHead(200, { "content-type": "application/json" });
+ res.flushHeaders();
+ const timer = setTimeout(() => res.end('{"choices":[{"message":{"content":"late"}}]}'), 800);
+ res.on("close", () => clearTimeout(timer));
+ });
+ const provider = new OpenAIProvider("fixture", "fixture", 100, url);
+ await expect(provider.compress("system", "user")).rejects.toThrow(/timed out after 150ms/);
+ });
+});
diff --git a/test/fetch-timeout.test.ts b/test/fetch-timeout.test.ts
index 1240e760..0019a770 100644
--- a/test/fetch-timeout.test.ts
+++ b/test/fetch-timeout.test.ts
@@ -112,6 +112,11 @@ describe("fetchWithTimeout bounded retry (total deadline)", () => {
// initial request past HARD_BUDGET_CAP_MS (170s) and the iii 180s
// invocation timeout before any retry logic ran.
it("caps the first attempt at the hard budget, not the raw caller timeout", async () => {
+ vi.spyOn(AbortSignal, "timeout").mockImplementation(ms => {
+ const controller = new AbortController();
+ setTimeout(() => controller.abort(new DOMException("Timed out", "TimeoutError")), ms);
+ return controller.signal;
+ });
const signals: AbortSignal[] = [];
const capturing = ((_url: string, init?: RequestInit) => {
const signal = init!.signal as AbortSignal;
diff --git a/test/graph-generation-surfaces.test.ts b/test/graph-generation-surfaces.test.ts
new file mode 100644
index 00000000..fdba19e5
--- /dev/null
+++ b/test/graph-generation-surfaces.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it, vi } from "vitest";
+import { StateKV } from "../src/state/kv.js";
+import { KV } from "../src/state/schema.js";
+import { resetGraphGeneration } from "../src/state/graph-generation.js";
+import { registerApiTriggers } from "../src/triggers/api.js";
+import { registerMcpEndpoints } from "../src/mcp/server.js";
+
+vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }));
+
+const secret = "graph-surface-test";
+const emptySnapshot = { nodes: [], edges: [], stats: { totalNodes: 0, totalEdges: 0, nodesByType: {}, edgesByType: {} } };
+
+function rig() {
+ const store = new Map<string, Map<string, unknown>>();
+ const handlers = new Map<string, (req: unknown) => Promise<any>>();
+ let resetOnNodeRead = false;
+ const sdk = {
+ registerFunction: (id: string, handler: (req: unknown) => Promise<any>) => handlers.set(id, handler),
+ registerTrigger: () => {},
+ trigger: async ({ function_id, payload }: { function_id: string; payload: { scope: string; key: string; value?: unknown } }) => {
+ const { scope, key, value } = payload;
+ if (function_id === "state::get") return store.get(scope)?.get(key) ?? null;
+ if (function_id === "state::set") {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, value);
+ return value;
+ }
+ if (function_id === "state::list") {
+ const rows = [...(store.get(scope)?.values() ?? [])];
+ if (resetOnNodeRead && (scope === KV.graphNodes || scope.startsWith(`${KV.graphNodes}:generation:`))) {
+ resetOnNodeRead = false;
+ await resetGraphGeneration(kv, emptySnapshot);
+ }
+ return rows;
+ }
+ throw new Error(`Unexpected state operation: ${function_id}`);
+ },
+ };
+ const kv = new StateKV(sdk as never);
+ registerApiTriggers(sdk as never, kv, secret);
+ registerMcpEndpoints(sdk as never, kv, secret);
+ return {
+ kv,
+ resetDuringNextRead: () => { resetOnNodeRead = true; },
+ exportMesh: () => handlers.get("api::mesh-export")!({ headers: { authorization: `Bearer ${secret}` }, query_params: {} }),
+ readStats: async () => {
+ const result = await handlers.get("mcp::resources::read")!({ headers: { authorization: `Bearer ${secret}` }, body: { uri: "agentmemory://graph/stats" } });
+ expect(result.status_code).toBe(200);
+ return JSON.parse(result.body.contents[0].text);
+ },
+ };
+}
+
+describe.each(["legacy", "rotated"])("%s graph reads across a concurrent reset", (generation) => {
+ async function seeded() {
+ const r = rig();
+ if (generation === "rotated") await resetGraphGeneration(r.kv, emptySnapshot);
+ for (const id of ["node-a", "node-b"]) {
+ await r.kv.set(KV.graphNodes, id, { id, type: "file", name: `${id}.ts`, sourceObservationIds: [], createdAt: "2026-10-12T00:00:00Z" });
+ }
+ await r.kv.set(KV.graphEdges, "edge-a", { id: "edge-a", type: "imports", sourceNodeId: "node-a", targetNodeId: "node-b", createdAt: "2026-10-12T00:00:00Z" });
+ r.resetDuringNextRead();
+ return r;
+ }
+
+ it("exports nodes and edges from one generation, then observes the reset on a new request", async () => {
+ const r = await seeded();
+ const before = await r.exportMesh();
+ expect(before.status_code).toBe(200);
+ expect(before.body.graphNodes.map((n: { id: string }) => n.id)).toEqual(["node-a", "node-b"]);
+ expect(before.body.graphEdges.map((e: { id: string }) => e.id)).toEqual(["edge-a"]);
+ const after = await r.exportMesh();
+ expect(after.body.graphNodes).toEqual([]);
+ expect(after.body.graphEdges).toEqual([]);
+ });
+
+ it("reports consistent MCP counts, then observes the reset on a new resource read", async () => {
+ const r = await seeded();
+ expect(await r.readStats()).toMatchObject({ totalNodes: 2, totalEdges: 1, nodesByType: { file: 2 }, edgesByType: { imports: 1 } });
+ expect(await r.readStats()).toMatchObject({ totalNodes: 0, totalEdges: 0 });
+ });
+});
diff --git a/test/graph-generation.test.ts b/test/graph-generation.test.ts
new file mode 100644
index 00000000..77ceb53c
--- /dev/null
+++ b/test/graph-generation.test.ts
@@ -0,0 +1,333 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { StateKV } from "../src/state/kv.js";
+import { KV } from "../src/state/schema.js";
+import { pinGraphState, setGraphGenerationListener } from "../src/state/graph-generation.js";
+import { persistGraphDelta, registerGraphFunction } from "../src/functions/graph.js";
+import { GraphRetrieval } from "../src/functions/graph-retrieval.js";
+import { describeGraphNode } from "../src/functions/graph-node.js";
+import { registerTemporalGraphFunctions } from "../src/functions/temporal-graph.js";
+import { registerExportImportFunction } from "../src/functions/export-import.js";
+import { registerMeshFunction } from "../src/functions/mesh.js";
+import { registerSnapshotFunction } from "../src/functions/snapshot.js";
+import { registerReflectFunctions } from "../src/functions/reflect.js";
+import { registerViewerStreamTriggers } from "../src/triggers/viewer-streams.js";
+import { getViewerCounts, resetViewerCounts } from "../src/state/viewer-counts.js";
+import { setAuditRecordedListener } from "../src/functions/audit.js";
+import type { GraphEdge, GraphNode, GraphSnapshot } from "../src/types.js";
+
+vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }));
+
+const timestamp = "2026-10-12T12:00:00.000Z";
+const node = (id: string, name = id, obs = id): GraphNode => ({
+ id, name, type: "concept", properties: {}, sourceObservationIds: [obs], createdAt: timestamp,
+});
+const edge = (id: string, sourceNodeId: string, targetNodeId: string): GraphEdge => ({
+ id, sourceNodeId, targetNodeId, type: "related_to", weight: 0.8,
+ sourceObservationIds: ["old-edge-observation"], createdAt: timestamp,
+});
+const observation = { id: "old-observation", sessionId: "s", timestamp, type: "discovery", title: "old", narrative: "old", concepts: [], files: [], facts: [], importance: 5 };
+const memory = { id: "mem_test", type: "fact", title: "test", content: "test", concepts: [], files: [], sessionIds: [], sourceObservationIds: [], strength: 5, version: 1, isLatest: true, createdAt: timestamp, updatedAt: timestamp };
+const xml = '<entities><entity type="concept" name="alpha"></entity><entity type="concept" name="beta"></entity></entities><relationships><relationship type="related_to" source="alpha" target="beta" weight="0.8"></relationship></relationships>';
+
+function deferred<T = void>() {
+ let resolve!: (value: T) => void;
+ const promise = new Promise<T>((r) => { resolve = r; });
+ return { promise, resolve };
+}
+
+function setup(provider = { name: "noop", compress: vi.fn(async () => xml), summarize: vi.fn(async () => "") }) {
+ const store = new Map<string, Map<string, unknown>>();
+ const handlers = new Map<string, (data?: any) => Promise<any>>();
+ const sent: any[] = [];
+ let intercept: ((id: string, payload: any) => Promise<void>) | undefined;
+ const sdk = {
+ registerFunction: (id: string, fn: (data?: any) => Promise<any>) => handlers.set(id, fn),
+ registerTrigger: vi.fn(),
+ trigger: async ({ function_id: id, payload }: { function_id: string; payload: any }): Promise<any> => {
+ if (id === "stream::send") { sent.push(structuredClone(payload)); return {}; }
+ if (!id.startsWith("state::")) return handlers.get(id)!(payload);
+ await intercept?.(id, payload);
+ const rows = store.get(payload.scope) ?? new Map<string, unknown>();
+ if (id === "state::get") return structuredClone(rows.get(payload.key) ?? null);
+ if (id === "state::list") return structuredClone([...rows.values()]);
+ if (id === "state::delete") { rows.delete(payload.key); return; }
+ if (id === "state::set") {
+ rows.set(payload.key, structuredClone(payload.value));
+ store.set(payload.scope, rows);
+ return structuredClone(payload.value);
+ }
+ throw new Error(`unexpected state call ${id}`);
+ },
+ };
+ const kv = new StateKV(sdk as never);
+ registerGraphFunction(sdk as never, kv, provider as never);
+ registerTemporalGraphFunctions(sdk as never, kv, provider as never);
+ registerExportImportFunction(sdk as never, kv);
+ registerMeshFunction(sdk as never, kv);
+ registerReflectFunctions(sdk as never, kv, provider as never);
+ const call = (id: string, payload: any = {}) => sdk.trigger({ function_id: id, payload });
+ return { kv, sdk, call, store, sent, provider, intercept: (fn?: typeof intercept) => { intercept = fn; } };
+}
+
+async function seed(kv: StateKV) {
+ await persistGraphDelta(kv, [node("old-a", "alpha"), node("old-b", "beta")], [edge("old-edge", "old-a", "old-b")]);
+ await kv.set(KV.graphEdgeHistory, "old-history", edge("old-history", "old-a", "old-b"));
+}
+
+afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllEnvs();
+ setGraphGenerationListener(null);
+ setAuditRecordedListener(null);
+ resetViewerCounts();
+});
+
+describe("graph generation reset", () => {
+ it("hides legacy nodes, edges, history and indexes from every graph read path, rebuild and export", async () => {
+ const { kv, call, store, provider } = setup();
+ await seed(kv);
+ await kv.set(KV.graphNodes, "undated", { ...node("undated"), createdAt: undefined });
+ const retrieval = new GraphRetrieval(kv);
+ expect(await retrieval.searchByEntities(["alpha"])).not.toEqual([]);
+ expect(await call("mem::graph-reset")).toMatchObject({
+ success: true,
+ resetMode: "generation",
+ physicalStorageRetained: true,
+ message: expect.stringContaining("does not reclaim disk space"),
+ });
+ // Physical legacy rows remain, but no logical read can fall back to them.
+ expect(store.get(KV.graphNodes)?.size).toBe(3);
+ for (const scope of [KV.graphNodes, KV.graphEdges, KV.graphEdgeHistory, KV.graphNameIndex, KV.graphEdgeKey, KV.graphNodeDegree]) {
+ expect(await kv.list(scope)).toEqual([]);
+ }
+ expect(await kv.get(KV.graphNodes, "old-a")).toBeNull();
+ expect(await retrieval.searchByEntities(["alpha"])).toEqual([]);
+ expect(await retrieval.expandFromChunks(["old-a"])).toEqual([]);
+ expect((await retrieval.temporalQuery("alpha")).entity).toBeNull();
+ expect(await describeGraphNode(kv, "old-a")).toBeNull();
+ for (const args of [{}, { query: "alpha" }, { startNodeId: "old-a" }]) {
+ expect((await call("mem::graph-query", args)).nodes).toEqual([]);
+ }
+ expect(await call("mem::graph-stats")).toMatchObject({ totalNodes: 0, totalEdges: 0 });
+ expect(await call("mem::temporal-query", { entityName: "alpha", includeHistory: true })).toHaveProperty("error");
+ expect(await call("mem::differential-state", { entityName: "alpha" })).toHaveProperty("error");
+ const exported = await call("mem::export");
+ expect(exported.graphNodes).toBeUndefined();
+ expect(exported.graphEdges).toBeUndefined();
+ expect((await call("mem::reflect")).clustersProcessed).toBe(0);
+ expect(provider.summarize).not.toHaveBeenCalled();
+ expect((await call("mem::graph-snapshot-rebuild", { force: true })).success).toBe(true);
+ expect((await call("mem::graph-stats")).totalNodes).toBe(0);
+ expect((await call("mem::graph-compact")).nodesTrimmed).toBe(0);
+ });
+
+ it("uses unique generations for same-millisecond resets and never merges old provenance on re-extraction", async () => {
+ vi.useFakeTimers(); vi.setSystemTime(timestamp);
+ const { kv, call } = setup();
+ await seed(kv);
+ await call("mem::graph-reset");
+ const first = await kv.get(KV.graphControl, "generation");
+ await persistGraphDelta(kv, [node("new-a", "alpha", "new-observation")], []);
+ expect((await kv.list<GraphNode>(KV.graphNodes))[0]).toMatchObject({ id: "new-a", sourceObservationIds: ["new-observation"] });
+ const oldView = await pinGraphState(kv);
+ await call("mem::graph-reset");
+ expect(await kv.get(KV.graphControl, "generation")).not.toBe(first);
+ await oldView.set(KV.graphNodes, "late", node("late"));
+ expect(await kv.list(KV.graphNodes)).toEqual([]);
+ expect((await call("mem::graph-stats")).totalNodes).toBe(0);
+ });
+
+ it.each(["mem::graph-extract", "mem::temporal-graph-extract"])("does not publish %s which was awaiting its provider at reset", async (id) => {
+ vi.stubEnv("GRAPH_EXTRACTION_ENABLED", "true");
+ const entered = deferred(); const response = deferred<string>();
+ const provider = { name: "test", compress: vi.fn(() => { entered.resolve(); return response.promise; }), summarize: vi.fn(async () => "") };
+ const { kv, call } = setup(provider);
+ const extraction = call(id, { observations: [observation] });
+ await entered.promise;
+ await call("mem::graph-reset");
+ response.resolve(xml);
+ expect((await extraction).success).toBe(true);
+ expect(await kv.list(KV.graphNodes)).toEqual([]);
+ expect(await kv.list(KV.graphEdges)).toEqual([]);
+ expect((await call("mem::graph-stats")).totalNodes).toBe(0);
+ provider.compress.mockResolvedValue(xml);
+ await call(id, { observations: [{ ...observation, id: "fresh-observation" }] });
+ const rows = await kv.list<GraphNode>(KV.graphNodes);
+ expect(rows.length).toBe(2);
+ expect(rows.every((n) => n.sourceObservationIds.includes("fresh-observation") && !n.sourceObservationIds.includes("old-observation"))).toBe(true);
+ });
+
+ it("keeps a persist queued behind reset in its starting generation", async () => {
+ const { kv, call, intercept } = setup();
+ const entered = deferred(); const release = deferred();
+ intercept(async (id, p) => {
+ if (id === "state::get" && p.scope === KV.graphNameIndex) {
+ intercept(); entered.resolve(); await release.promise;
+ }
+ });
+ const first = persistGraphDelta(kv, [node("first")], []);
+ await entered.promise;
+ const reset = call("mem::graph-reset");
+ const queued = persistGraphDelta(kv, [node("queued")], []);
+ release.resolve();
+ await Promise.all([first, reset, queued]);
+ expect(await kv.list(KV.graphNodes)).toEqual([]);
+ expect((await call("mem::graph-stats")).totalNodes).toBe(0);
+ });
+
+ it("preserves the old active graph if snapshot initialization or pointer publication fails", async () => {
+ const { kv, call, intercept } = setup();
+ await seed(kv);
+ for (const failPointer of [false, true]) {
+ intercept(async (id, p) => {
+ if (id === "state::set" && (failPointer ? p.scope === KV.graphControl : p.scope.startsWith(`${KV.graphSnapshot}:generation:`))) throw new Error("write failed");
+ });
+ await expect(call("mem::graph-reset")).rejects.toThrow("write failed");
+ intercept();
+ expect((await kv.list(KV.graphNodes)).length).toBe(2);
+ expect((await call("mem::graph-stats")).totalNodes).toBe(2);
+ }
+ expect((await call("mem::graph-reset")).success).toBe(true);
+ expect(await kv.list(KV.graphNodes)).toEqual([]);
+ });
+
+ it("retains the boundary across StateKV restart and fails closed on an unreadable or corrupt pointer", async () => {
+ const { kv, sdk, call, intercept } = setup();
+ await seed(kv); await call("mem::graph-reset");
+ const restarted = new StateKV(sdk as never);
+ expect(await restarted.list(KV.graphNodes)).toEqual([]);
+ expect(await new GraphRetrieval(restarted).searchByEntities(["alpha"])).toEqual([]);
+ intercept(async (id, p) => { if (id === "state::get" && p.scope === KV.graphControl) throw new Error("offline"); });
+ await expect(restarted.list(KV.graphNodes)).rejects.toThrow("offline");
+ intercept();
+ await kv.set(KV.graphControl, "generation", "invalid");
+ await expect(restarted.list(KV.graphNodes)).rejects.toThrow("Invalid graph generation");
+ await call("mem::graph-reset");
+ expect(await restarted.list(KV.graphNodes)).toEqual([]);
+ });
+
+ it("accepts intentional imports into the active generation without timestamp-based duplication", async () => {
+ const { kv, call } = setup();
+ await seed(kv); await call("mem::graph-reset");
+ const imported = { ...node("imported", "alpha", "import-observation"), createdAt: "2020-01-01T00:00:00.000Z" };
+ await call("mem::import", { exportData: { version: "0.9.30", exportedAt: timestamp, sessions: [], observations: {}, memories: [], summaries: [], graphNodes: [imported] } });
+ await call("mem::graph-snapshot-rebuild", { force: true });
+ await persistGraphDelta(kv, [node("new", "alpha", "new-observation")], []);
+ const nodes = await kv.list<GraphNode>(KV.graphNodes);
+ expect(nodes).toHaveLength(1);
+ expect(nodes[0].sourceObservationIds).toEqual(["import-observation", "new-observation"]);
+ expect((await call("mem::graph-stats")).totalNodes).toBe(1);
+ await call("mem::mesh-receive", { graphNodes: [node("from-mesh")] });
+ expect(await kv.get(KV.graphNodes, "from-mesh")).not.toBeNull();
+ expect(await kv.get(KV.graphNodes, "old-a")).toBeNull();
+ });
+
+ it.each(["mem::import", "mem::mesh-receive"])("keeps delayed %s graph writes out of a concurrent reset", async (id) => {
+ const { kv, call, intercept } = setup();
+ const entered = deferred(); const release = deferred();
+ intercept(async (fn, p) => {
+ if (fn === "state::set" && p.scope === KV.memories) {
+ intercept(); entered.resolve(); await release.promise;
+ }
+ });
+ const data = { version: "0.9.30", exportedAt: timestamp, sessions: [], observations: {}, memories: [memory], summaries: [], graphNodes: [node("imported")], graphEdges: [] };
+ const pending = call(id, id === "mem::import" ? { exportData: data } : data);
+ await entered.promise;
+ await call("mem::graph-reset");
+ release.resolve();
+ expect((await pending).success).toBe(true);
+ expect(await kv.list(KV.graphNodes)).toEqual([]);
+ });
+
+ it("pins snapshot restore before filesystem and non-graph work, while allowing a later deliberate restore", async () => {
+ const { kv, sdk, call, intercept } = setup();
+ const dir = mkdtempSync(join(process.cwd(), ".graph-generation-test-"));
+ try {
+ registerSnapshotFunction(sdk as never, kv, dir);
+ await seed(kv); await kv.set(KV.memories, memory.id, memory);
+ const saved = await call("mem::snapshot-create");
+ expect(saved.success).toBe(true);
+ const commitHash = saved.snapshot.commitHash;
+ await call("mem::graph-reset");
+ const entered = deferred(); const release = deferred();
+ intercept(async (fn, p) => {
+ if (fn === "state::set" && p.scope === KV.memories) {
+ intercept(); entered.resolve(); await release.promise;
+ }
+ });
+ const restoring = call("mem::snapshot-restore", { commitHash });
+ await entered.promise;
+ await call("mem::graph-reset");
+ release.resolve();
+ expect((await restoring).success).toBe(true);
+ expect(await kv.list(KV.graphNodes)).toEqual([]);
+ expect((await call("mem::snapshot-restore", { commitHash })).success).toBe(true);
+ expect((await kv.list(KV.graphNodes)).length).toBe(2);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ it("never re-resolves the namespace halfway through a Redis read-modify-write", async () => {
+ const { kv, sdk, call, intercept, store } = setup();
+ await seed(kv);
+ const redis = new StateKV(sdk as never, { backend: "redis" });
+ const entered = deferred(); const release = deferred();
+ intercept(async (fn, p) => {
+ if (fn === "state::get" && p.scope === KV.graphNodes) {
+ intercept(); entered.resolve(); await release.promise;
+ }
+ });
+ const update = redis.update(KV.graphNodes, "old-a", [{ type: "set", path: "name", value: "late-update" }]);
+ await entered.promise;
+ await call("mem::graph-reset");
+ release.resolve(); await update;
+ expect(store.get(KV.graphNodes)?.get("old-a")).toMatchObject({ name: "late-update" });
+ expect(await redis.get(KV.graphNodes, "old-a")).toBeNull();
+ });
+
+ it("updates cached viewer counts and refuses late legacy snapshot events after reset", async () => {
+ const { kv, sdk, call, sent } = setup();
+ await seed(kv);
+ const legacy = await kv.get<GraphSnapshot>(KV.graphSnapshot, "current");
+ registerViewerStreamTriggers(sdk as never, kv);
+ expect((await getViewerCounts(kv)).graphNodes).toBe(2);
+ await call("mem::graph-reset");
+ expect((await getViewerCounts(kv)).graphNodes).toBe(0);
+ const count = sent.length;
+ expect(await call("event::viewer::graph-snapshot-changed", { key: "current", event_type: "state:updated", new_value: legacy })).toEqual({ emitted: false });
+ expect(await call("event::viewer::graph-nodes-changed")).toEqual({ emitted: false });
+ expect(await call("event::viewer::graph-edges-changed")).toEqual({ emitted: false });
+ expect(sent.length).toBe(count);
+ await persistGraphDelta(kv, [node("fresh")], []);
+ expect((await getViewerCounts(kv)).graphNodes).toBe(1);
+ expect(sent.filter((e) => e.type === "graph.changed").at(-1).data.stats.totalNodes).toBe(1);
+ });
+
+ it("orders a delayed legacy viewer callback before reset completion", async () => {
+ const { kv, sdk, call, sent } = setup();
+ await seed(kv);
+ const legacy = await kv.get<GraphSnapshot>(KV.graphSnapshot, "current");
+ registerViewerStreamTriggers(sdk as never, kv);
+ await getViewerCounts(kv);
+ const entered = deferred(); const release = deferred();
+ const originalGet = kv.get.bind(kv);
+ let pause = true;
+ vi.spyOn(kv, "get").mockImplementation(async (scope, key) => {
+ const result = await originalGet(scope, key);
+ if (pause && scope === KV.graphControl) {
+ pause = false; entered.resolve(); await release.promise;
+ }
+ return result;
+ });
+ const legacyEvent = call("event::viewer::graph-snapshot-changed", { key: "current", event_type: "state:updated", new_value: legacy });
+ await entered.promise;
+ const reset = call("mem::graph-reset");
+ release.resolve();
+ await Promise.all([legacyEvent, reset]);
+ expect((await getViewerCounts(kv)).graphNodes).toBe(0);
+ expect(sent.filter((e) => e.type === "graph.changed").at(-1).data.stats.totalNodes).toBe(0);
+ });
+});
diff --git a/test/graph-ingestion-import-mesh.test.ts b/test/graph-ingestion-import-mesh.test.ts
new file mode 100644
index 00000000..332bfa90
--- /dev/null
+++ b/test/graph-ingestion-import-mesh.test.ts
@@ -0,0 +1,281 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { StateKV, applyUpdateOps } from "../src/state/kv.js";
+import { KV } from "../src/state/schema.js";
+import { setGraphGenerationListener } from "../src/state/graph-generation.js";
+import { registerGraphFunction } from "../src/functions/graph.js";
+import { registerExportImportFunction } from "../src/functions/export-import.js";
+import { registerMeshFunction } from "../src/functions/mesh.js";
+import { registerViewerStreamTriggers } from "../src/triggers/viewer-streams.js";
+import { getViewerCounts, resetViewerCounts } from "../src/state/viewer-counts.js";
+import { setAuditRecordedListener } from "../src/functions/audit.js";
+import type { ExportData, GraphEdge, GraphNode } from "../src/types.js";
+
+vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }));
+vi.mock("node:dns/promises", () => ({ lookup: vi.fn(async () => [{ address: "203.0.113.10", family: 4 }]) }));
+
+const timestamp = "2026-10-12T12:00:00.000Z";
+const node = (id: string, name = id, extra: Partial<GraphNode> = {}): GraphNode => ({
+ id, name, type: "concept", properties: {}, sourceObservationIds: [], createdAt: timestamp, ...extra,
+});
+const edge = (id: string, sourceNodeId: string, targetNodeId: string, extra: Partial<GraphEdge> = {}): GraphEdge => ({
+ id, sourceNodeId, targetNodeId, type: "related_to", weight: 0.8, sourceObservationIds: [], createdAt: timestamp, ...extra,
+});
+const exported = (graphNodes?: GraphNode[], graphEdges?: GraphEdge[]): ExportData => ({
+ version: "0.9.30", exportedAt: timestamp, sessions: [], observations: {}, memories: [], summaries: [], graphNodes, graphEdges,
+});
+
+function deferred() {
+ let resolve!: () => void;
+ const promise = new Promise<void>((r) => { resolve = r; });
+ return { promise, resolve };
+}
+
+async function rig(rotated = true) {
+ const store = new Map<string, Map<string, unknown>>();
+ const handlers = new Map<string, (data: any) => Promise<any>>();
+ const triggers: Array<{ type: string; function_id: string; config: { scope?: string } }> = [];
+ let intercept: ((id: string, payload: any) => Promise<void>) | undefined;
+ const sdk = {
+ registerFunction: (id: string, fn: (data: any) => Promise<any>) => handlers.set(id, fn),
+ registerTrigger: (trigger: typeof triggers[number]) => triggers.push(trigger),
+ trigger: async ({ function_id: id, payload }: { function_id: string; payload: any }): Promise<any> => {
+ if (id === "stream::send") return {};
+ if (!id.startsWith("state::")) return handlers.get(id)!(payload);
+ await intercept?.(id, payload);
+ const rows = store.get(payload.scope) ?? new Map<string, unknown>();
+ if (id === "state::get") return structuredClone(rows.get(payload.key) ?? null);
+ if (id === "state::list") return structuredClone([...rows.values()]);
+ const before = structuredClone(rows.get(payload.key) ?? null);
+ if (id === "state::delete") rows.delete(payload.key);
+ else if (id === "state::set") rows.set(payload.key, structuredClone(payload.value));
+ else if (id === "state::update") rows.set(payload.key, applyUpdateOps(before, payload.ops));
+ else throw new Error(`Unexpected state operation: ${id}`);
+ store.set(payload.scope, rows);
+ const after = structuredClone(rows.get(payload.key) ?? null);
+ for (const trigger of triggers) {
+ if (trigger.type === "state" && trigger.config.scope === payload.scope) {
+ await handlers.get(trigger.function_id)!({ key: payload.key, event_type: after === null ? "state:deleted" : "state:updated", old_value: before, new_value: after });
+ }
+ }
+ return id === "state::update" ? { old_value: before, new_value: after, errors: [] } : after;
+ },
+ };
+ const kv = new StateKV(sdk as never);
+ registerGraphFunction(sdk as never, kv, { name: "noop" } as never);
+ registerExportImportFunction(sdk as never, kv);
+ registerMeshFunction(sdk as never, kv, "fixture-secret");
+ registerViewerStreamTriggers(sdk as never, kv);
+ const call = (id: string, payload: any = {}) => sdk.trigger({ function_id: id, payload });
+ if (rotated) await call("mem::graph-reset");
+ await getViewerCounts(kv);
+ return { kv, call, store, intercept: (fn?: typeof intercept) => { intercept = fn; } };
+}
+
+async function expectGraph(r: Awaited<ReturnType<typeof rig>>, ids: string[], edgeCount: number) {
+ const query = await r.call("mem::graph-query");
+ expect(query.nodes.map((n: GraphNode) => n.id).sort()).toEqual([...ids].sort());
+ expect(await r.call("mem::graph-stats")).toMatchObject({ totalNodes: ids.length, totalEdges: edgeCount });
+ expect(await getViewerCounts(r.kv)).toMatchObject({ graphNodes: ids.length, graphEdges: edgeCount });
+}
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ setGraphGenerationListener(null);
+ setAuditRecordedListener(null);
+ resetViewerCounts();
+});
+
+describe("raw graph import reconciliation", () => {
+ it.each([false, true])("publishes imported raw IDs in queries, stats, indexes and viewer counts (rotated: %s)", async (rotated) => {
+ const r = await rig(rotated);
+ const nodes = [node("raw-a", "Alpha"), node("raw-b", "Beta")];
+ const result = await r.call("mem::import", { exportData: exported(nodes, [edge("raw-edge", "raw-a", "raw-b")]) });
+ expect(result.success).toBe(true);
+ await expectGraph(r, ["raw-a", "raw-b"], 1);
+ expect(await r.kv.get(KV.graphNameIndex, "concept|Alpha")).toBe("raw-a");
+ expect(await r.kv.get(KV.graphEdgeKey, "raw-a|raw-b|related_to")).toBe("raw-edge");
+ expect(await r.kv.get(KV.graphNodeDegree, "raw-a")).toBe(1);
+ });
+
+ it("preserves overwrite-by-ID semantics while removing obsolete names and edge keys", async () => {
+ const r = await rig();
+ await r.call("mem::import", { exportData: exported([node("a", "Old"), node("b"), node("c")], [edge("e", "a", "b")]) });
+ const renamed = node("a", "src/new.ts", { type: "file", properties: { marker: "verbatim" }, createdAt: "2001-01-01T00:00:00Z" });
+ const changedEdge = edge("e", "a", "c", { type: "uses", weight: 0.4 });
+ await r.call("mem::import", { exportData: exported([renamed], [changedEdge]), strategy: "merge" });
+ await expectGraph(r, ["a", "b", "c"], 1);
+ expect(await r.kv.get(KV.graphNodes, "a")).toEqual(renamed);
+ expect(await r.kv.get(KV.graphNameIndex, "concept|Old")).toBeNull();
+ expect(await r.kv.get(KV.graphNameIndex, "file|src/new.ts")).toBe("a");
+ expect(await r.kv.get(KV.graphEdgeKey, "a|b|related_to")).toBeNull();
+ expect(await r.kv.get(KV.graphEdgeKey, "a|c|uses")).toBe("e");
+ expect(await r.kv.get(KV.graphNodeDegree, "b")).toBe(0);
+ expect(await r.kv.get(KV.graphNodeDegree, "c")).toBe(1);
+ expect(await r.call("mem::graph-stats")).toMatchObject({ nodesByType: { concept: 2, file: 1 }, edgesByType: { uses: 1 } });
+ });
+
+ it("does not merge distinct IDs that have the same name", async () => {
+ const r = await rig();
+ await r.call("mem::import", { exportData: exported([node("one", "Same"), node("two", "Same")], [edge("e", "one", "two")]) });
+ await expectGraph(r, ["one", "two"], 1);
+ expect(await r.kv.get(KV.graphEdges, "e")).toMatchObject({ sourceNodeId: "one", targetNodeId: "two" });
+ });
+
+ it("keeps existing graph records under skip and counts only skipped records", async () => {
+ const r = await rig();
+ const original = node("a", "Original");
+ const relation = edge("e", "a", "b");
+ await r.call("mem::import", { exportData: exported([original, node("b")], [relation]) });
+ const result = await r.call("mem::import", {
+ strategy: "skip", exportData: exported([node("a", "Changed"), node("c")], [edge("e", "c", "b")]),
+ });
+ expect(result).toMatchObject({ success: true, skipped: 2 });
+ expect(await r.kv.get(KV.graphNodes, "a")).toEqual(original);
+ expect(await r.kv.get(KV.graphEdges, "e")).toEqual(relation);
+ expect(await r.kv.get(KV.graphNameIndex, "concept|Changed")).toBeNull();
+ await expectGraph(r, ["a", "b", "c"], 1);
+ });
+
+ it.each(["omitted", "empty", "new records"])("replace clears graph history and obsolete derived state with %s", async (kind) => {
+ const r = await rig();
+ await r.call("mem::import", { exportData: exported([node("old-a"), node("old-b")], [edge("old-e", "old-a", "old-b")]) });
+ await r.kv.set(KV.graphEdgeHistory, "old-history", edge("old-history", "old-a", "old-b"));
+ const replacement = kind === "omitted" ? exported() : exported(kind === "empty" ? [] : [node("new")], []);
+ expect((await r.call("mem::import", { exportData: replacement, strategy: "replace" })).success).toBe(true);
+ await expectGraph(r, kind === "new records" ? ["new"] : [], 0);
+ for (const [scope, id] of [[KV.graphNodes, "old-a"], [KV.graphNameIndex, "concept|old-a"], [KV.graphEdgeKey, "old-a|old-b|related_to"], [KV.graphNodeDegree, "old-a"], [KV.graphEdgeHistory, "old-history"]]) {
+ expect(await r.kv.get(scope, id)).toBeNull();
+ }
+ });
+
+ it.each(["merge", "skip", "replace"])("rejects invalid graph data before any %s mutation", async (strategy) => {
+ const r = await rig();
+ await r.call("mem::import", { exportData: exported([node("retained")], []) });
+ const memory = { id: "kept-memory", title: "handwritten", content: "preserve me", sessionIds: [] };
+ const session = { id: "kept-session", project: "fixture", startedAt: timestamp };
+ await r.kv.set(KV.memories, memory.id, memory);
+ await r.kv.set(KV.sessions, session.id, session);
+ const mutations = vi.fn();
+ r.intercept(async (operation) => {
+ if (operation !== "state::get" && operation !== "state::list") mutations(operation);
+ });
+ const payload = { ...exported([{ ...node("invalid"), name: undefined } as never], []), memories: [{ ...memory, content: "changed" }] };
+ expect(await r.call("mem::import", { strategy, exportData: payload })).toEqual({ success: false, error: "Invalid graph node or edge" });
+ expect(mutations).not.toHaveBeenCalled();
+ expect(await r.kv.get(KV.memories, memory.id)).toEqual(memory);
+ expect(await r.kv.get(KV.sessions, session.id)).toEqual(session);
+ await expectGraph(r, ["retained"], 0);
+ });
+
+ it.each([
+ { graphNodes: {}, graphEdges: [] },
+ { graphNodes: [], graphEdges: {} },
+ { graphNodes: [], graphEdges: [{ ...edge("invalid", "a", "b"), sourceNodeId: "" }] },
+ ])("rejects malformed graph containers and edges before replacement", async (graph) => {
+ const r = await rig();
+ await r.call("mem::import", { exportData: exported([node("retained")], []) });
+ expect(await r.call("mem::import", { strategy: "replace", exportData: { ...exported(), ...graph } })).toMatchObject({ success: false });
+ await expectGraph(r, ["retained"], 0);
+ });
+
+ it.each([["mem::import", "merge"], ["mem::import", "replace"], ["mem::mesh-receive", "lww"]])("keeps delayed %s (%s) writes in their original generation", async (id, strategy) => {
+ const r = await rig();
+ const entered = deferred();
+ const release = deferred();
+ let hold = true;
+ r.intercept(async (operation, payload) => {
+ if (hold && operation === "state::set" && payload.scope === KV.memories) {
+ hold = false; entered.resolve(); await release.promise;
+ }
+ });
+ const memories = [{ id: "memory", type: "fact", title: "fixture", content: "fixture", sessionIds: [], concepts: [], files: [], strength: 5, version: 1, isLatest: true, createdAt: timestamp, updatedAt: timestamp }];
+ const payload = id === "mem::import"
+ ? { exportData: { ...exported([node("late")], []), memories }, strategy }
+ : { graphNodes: [node("late")], memories };
+ const pending = r.call(id, payload);
+ await entered.promise;
+ await r.call("mem::graph-reset");
+ release.resolve();
+ expect((await pending).success).toBe(true);
+ await expectGraph(r, [], 0);
+ expect(await r.kv.get(KV.graphNodes, "late")).toBeNull();
+ });
+
+ it("reports a derived-state write failure and repairs it when ingestion is retried", async () => {
+ const r = await rig();
+ const payload = { exportData: exported([node("a"), node("b")], [edge("e", "a", "b")]) };
+ let fail = true;
+ r.intercept(async (operation, p) => {
+ if (fail && operation === "state::set" && p.scope.startsWith(KV.graphNodeDegree)) {
+ fail = false; throw new Error("injected degree failure");
+ }
+ });
+ await expect(r.call("mem::import", payload)).rejects.toThrow("injected degree failure");
+ expect((await r.call("mem::import", payload)).success).toBe(true);
+ await expectGraph(r, ["a", "b"], 1);
+ expect(await r.kv.get(KV.graphNodeDegree, "a")).toBe(1);
+ });
+});
+
+describe("mesh raw graph reconciliation", () => {
+ it("does not access graph storage when receiving only non-graph records", async () => {
+ const r = await rig();
+ r.intercept(async (operation, payload) => {
+ if (operation === "state::get" && payload.scope.startsWith(KV.graphSnapshot)) {
+ throw new Error("graph storage unavailable");
+ }
+ });
+ const memory = { id: "memory-only", updatedAt: timestamp, content: "fixture" };
+ expect(await r.call("mem::mesh-receive", { memories: [memory] })).toMatchObject({ success: true, accepted: 1 });
+ expect(await r.kv.get(KV.memories, memory.id)).toEqual(memory);
+ });
+
+ it("uses node update timestamps and edge creation timestamps while preserving metadata", async () => {
+ const r = await rig();
+ const original = node("a", "Original");
+ await r.call("mem::mesh-receive", { graphNodes: [original, node("b"), node("c")], graphEdges: [edge("e", "a", "b")] });
+ const newer = node("a", "Changed", { updatedAt: "2026-10-13T00:00:00Z", aliases: ["alternate"], properties: { source: "peer" } });
+ const relation = edge("e", "a", "c", { type: "uses", createdAt: "2026-10-13T00:00:00Z", tvalid: "2026-09-01T00:00:00Z" });
+ expect(await r.call("mem::mesh-receive", { graphNodes: [newer], graphEdges: [relation] })).toMatchObject({ success: true, accepted: 2 });
+ expect(await r.kv.get(KV.graphNodes, "a")).toEqual(newer);
+ expect(await r.kv.get(KV.graphEdges, "e")).toEqual(relation);
+ expect(await r.kv.get(KV.graphNameIndex, "concept|Original")).toBeNull();
+ expect(await r.kv.get(KV.graphEdgeKey, "a|b|related_to")).toBeNull();
+ expect(await r.kv.get(KV.graphNodeDegree, "b")).toBe(0);
+ await expectGraph(r, ["a", "b", "c"], 1);
+ expect(await r.call("mem::mesh-receive", { graphNodes: [original, { ...newer, name: "Equal timestamp" }, node("invalid", "invalid", { createdAt: "not-a-date" })], graphEdges: [edge("e", "c", "b"), { ...relation, weight: 0.1 }] })).toMatchObject({ accepted: 0 });
+ expect(await r.kv.get(KV.graphNodes, "a")).toEqual(newer);
+ expect(await r.kv.get(KV.graphEdges, "e")).toEqual(relation);
+ });
+
+ it("preserves edge-only acceptance and bounds provenance without changing other metadata", async () => {
+ const r = await rig();
+ const ids = Array.from({ length: 80 }, (_, i) => `obs-${i}`);
+ expect(await r.call("mem::mesh-receive", { graphEdges: [edge("e", "unknown-a", "unknown-b", { sourceObservationIds: ids })] })).toMatchObject({ accepted: 1 });
+ expect(await r.kv.get(KV.graphEdges, "e")).toMatchObject({ sourceNodeId: "unknown-a", targetNodeId: "unknown-b", sourceObservationIds: ids.slice(-32), weight: 0.8 });
+ expect(await r.call("mem::graph-stats")).toMatchObject({ totalNodes: 0, totalEdges: 1 });
+ });
+
+ it("shows previously received edges when their endpoint nodes arrive in a later batch", async () => {
+ const r = await rig();
+ const relation = edge("early-edge", "late-a", "late-b");
+ await r.call("mem::mesh-receive", { graphEdges: [relation] });
+ await r.call("mem::mesh-receive", { graphNodes: [node("late-a"), node("late-b")] });
+ await expectGraph(r, ["late-a", "late-b"], 1);
+ expect((await r.call("mem::graph-query")).edges).toEqual([relation]);
+ });
+
+ it("reconciles graph data from pull sync and honors the peer's selected graph scopes", async () => {
+ const r = await rig();
+ const remote = { graphNodes: [node("remote-a"), node("remote-b")], graphEdges: [edge("remote-edge", "remote-a", "remote-b")] };
+ vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify(remote), { status: 200 })));
+ await r.kv.set(KV.mesh, "peer", { id: "peer", name: "fixture", url: "https://peer.example.test", status: "connected", sharedScopes: ["graph:nodes"] });
+ const first = await r.call("mem::mesh-sync", { peerId: "peer", direction: "pull" });
+ expect(first.results[0]).toMatchObject({ pulled: 2, errors: [] });
+ await expectGraph(r, ["remote-a", "remote-b"], 0);
+ const second = await r.call("mem::mesh-sync", { peerId: "peer", direction: "pull", scopes: ["graph:edges"] });
+ expect(second.results[0]).toMatchObject({ pulled: 1, errors: [] });
+ await expectGraph(r, ["remote-a", "remote-b"], 1);
+ });
+});
diff --git a/test/graph-ingestion-snapshot.test.ts b/test/graph-ingestion-snapshot.test.ts
new file mode 100644
index 00000000..42907fe5
--- /dev/null
+++ b/test/graph-ingestion-snapshot.test.ts
@@ -0,0 +1,276 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { registerSnapshotFunction } from "../src/functions/snapshot.js";
+import { persistGraphDelta, registerGraphFunction } from "../src/functions/graph.js";
+import { getSearchIndex, indexRecords, setEmbeddingProvider, setIndexPersistence, setVectorIndex } from "../src/functions/search.js";
+import { StateKV } from "../src/state/kv.js";
+import { KV } from "../src/state/schema.js";
+import { SearchIndex } from "../src/state/search-index.js";
+import { VectorIndex } from "../src/state/vector-index.js";
+import { setGraphGenerationListener } from "../src/state/graph-generation.js";
+import type { CompressedObservation, GraphEdge, GraphNode, Memory } from "../src/types.js";
+
+vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }));
+
+const timestamp = "2026-10-12T12:00:00.000Z";
+const node = (id: string, name = id): GraphNode => ({ id, name, type: "concept", properties: {}, sourceObservationIds: [], createdAt: timestamp });
+const edge = (id: string, sourceNodeId: string, targetNodeId: string): GraphEdge => ({ id, sourceNodeId, targetNodeId, type: "related_to", weight: 0.8, sourceObservationIds: [], createdAt: timestamp });
+const memory = (id: string, marker: string, extra: Partial<Memory> = {}): Memory => ({ id, title: marker, content: marker, type: "fact", concepts: [], files: [], sessionIds: [], strength: 5, version: 1, isLatest: true, createdAt: timestamp, updatedAt: timestamp, ...extra });
+const observation = (id: string, marker: string): CompressedObservation => ({ id, sessionId: "session", timestamp, type: "discovery", title: marker, narrative: marker, concepts: [], files: [], facts: [], importance: 5 });
+const dirs: string[] = [];
+
+function setup() {
+ const dir = mkdtempSync(join(process.cwd(), ".graph-ingestion-snapshot-test-"));
+ dirs.push(dir);
+ const store = new Map<string, Map<string, unknown>>();
+ const handlers = new Map<string, (data?: any) => Promise<any>>();
+ let intercept: ((id: string, payload: any) => Promise<void>) | undefined;
+ const sdk = {
+ registerFunction: (id: string, fn: (data?: any) => Promise<any>) => handlers.set(id, fn),
+ registerTrigger: vi.fn(),
+ trigger: async ({ function_id: id, payload }: { function_id: string; payload: any }): Promise<any> => {
+ if (!id.startsWith("state::")) return handlers.get(id)!(payload);
+ await intercept?.(id, payload);
+ const rows = store.get(payload.scope) ?? new Map<string, unknown>();
+ if (id === "state::get") return structuredClone(rows.get(payload.key) ?? null);
+ if (id === "state::list") return structuredClone([...rows.values()]);
+ if (id === "state::delete") { rows.delete(payload.key); return; }
+ if (id === "state::set") {
+ rows.set(payload.key, structuredClone(payload.value));
+ store.set(payload.scope, rows);
+ return structuredClone(payload.value);
+ }
+ throw new Error(`unexpected state call ${id}`);
+ },
+ };
+ const kv = new StateKV(sdk as never);
+ registerGraphFunction(sdk as never, kv, { name: "noop" } as never);
+ registerSnapshotFunction(sdk as never, kv, dir);
+ const call = (id: string, payload: any = {}) => sdk.trigger({ function_id: id, payload });
+ const git = (...args: string[]) => execFileSync("git", args, { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+ const archive = (data: unknown) => {
+ git("init"); git("config", "user.email", "agentmemory@local"); git("config", "user.name", "agentmemory");
+ writeFileSync(join(dir, "state.json"), JSON.stringify(data));
+ git("add", "state.json"); git("commit", "-m", "Synthetic snapshot fixture");
+ return git("rev-parse", "HEAD");
+ };
+ return { kv, call, dir, git, archive, intercept: (fn?: typeof intercept) => { intercept = fn; } };
+}
+
+beforeEach(() => {
+ getSearchIndex().clear();
+ setEmbeddingProvider(null);
+ setVectorIndex(null);
+ setIndexPersistence(null);
+});
+afterEach(() => {
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+ setGraphGenerationListener(null);
+ setIndexPersistence(null);
+ setEmbeddingProvider(null);
+ setVectorIndex(null);
+ getSearchIndex().clear();
+});
+
+describe("Git snapshot ingestion", () => {
+ it("round-trips graph edges and makes a restore after reset immediately queryable and deduplicated", async () => {
+ const r = setup();
+ await persistGraphDelta(r.kv, [node("a", "alpha"), node("b", "beta")], [edge("ab", "a", "b")]);
+ const created = await r.call("mem::snapshot-create");
+ expect(created.success).toBe(true);
+ expect(JSON.parse(r.git("show", `${created.snapshot.commitHash}:state.json`)).graphEdges).toHaveLength(1);
+ await r.call("mem::graph-reset");
+ expect((await r.call("mem::graph-stats")).totalNodes).toBe(0);
+ expect(await r.call("mem::snapshot-restore", { commitHash: created.snapshot.commitHash })).toMatchObject({ success: true });
+ expect(await r.call("mem::graph-stats")).toMatchObject({ totalNodes: 2, totalEdges: 1 });
+ const graph = await r.call("mem::graph-query");
+ expect(graph.nodes.map((n: GraphNode) => n.id).sort()).toEqual(["a", "b"]);
+ expect(graph.edges.map((e: GraphEdge) => e.id)).toEqual(["ab"]);
+ await persistGraphDelta(r.kv, [node("duplicate", "alpha")], []);
+ expect((await r.kv.list(KV.graphNodes)).length).toBe(2);
+ });
+
+ it("restores legacy nodes-only archives as an overlay without changing the Git worktree", async () => {
+ const r = setup();
+ await persistGraphDelta(r.kv, [node("existing")], []);
+ const commitHash = r.archive({ graphNodes: [node("legacy")] });
+ const uncommitted = '{"uncommitted":"preserve me"}';
+ writeFileSync(join(r.dir, "state.json"), uncommitted);
+ const statusBefore = r.git("status", "--porcelain");
+ expect(await r.call("mem::snapshot-restore", { commitHash })).toMatchObject({ success: true });
+ expect((await r.call("mem::graph-query")).nodes.map((n: GraphNode) => n.id).sort()).toEqual(["existing", "legacy"]);
+ expect(readFileSync(join(r.dir, "state.json"), "utf8")).toBe(uncommitted);
+ expect(r.git("status", "--porcelain")).toBe(statusBefore);
+ });
+
+ it("replaces warm keyword terms and stale vectors while preserving unrelated indexed rows", async () => {
+ const r = setup();
+ const oldMemory = memory("mem_restore", "olduniquememory"), oldObs = observation("obs_restore", "olduniqueobservation");
+ const unrelated = memory("mem_keep", "unrelatedmarker");
+ await indexRecords([oldObs], [oldMemory, unrelated]);
+ const vectors = new VectorIndex();
+ vectors.add(oldMemory.id, "memory", new Float32Array([1, 0]));
+ vectors.add(oldObs.id, "session", new Float32Array([1, 0]));
+ vectors.add(unrelated.id, "memory", new Float32Array([1, 0]));
+ setVectorIndex(vectors);
+ let persisted = "";
+ const save = vi.fn(async () => { persisted = getSearchIndex().serialize(); });
+ setIndexPersistence({ scheduleSave: vi.fn(), save });
+ const commitHash = r.archive({ memories: [memory(oldMemory.id, "newuniquememory")], observations: { session: [observation(oldObs.id, "newuniqueobservation")] } });
+ expect(await r.call("mem::snapshot-restore", { commitHash })).toMatchObject({ success: true });
+ expect(getSearchIndex().search("olduniquememory olduniqueobservation")).toEqual([]);
+ expect(getSearchIndex().search("newuniquememory").map(x => x.obsId)).toEqual([oldMemory.id]);
+ expect(getSearchIndex().search("newuniqueobservation").map(x => x.obsId)).toEqual([oldObs.id]);
+ expect(getSearchIndex().has(unrelated.id)).toBe(true);
+ expect(vectors.has(oldMemory.id)).toBe(false);
+ expect(vectors.has(oldObs.id)).toBe(false);
+ expect(vectors.has(unrelated.id)).toBe(true);
+ expect(save).toHaveBeenCalledTimes(1);
+ expect(SearchIndex.deserialize(persisted).search("newuniquememory").map(x => x.obsId)).toEqual([oldMemory.id]);
+ expect(SearchIndex.deserialize(persisted).search("olduniquememory")).toEqual([]);
+ });
+
+ it("removes old keyword and vector entries for raw observations and nonlatest memories", async () => {
+ const r = setup();
+ const oldMemory = memory("mem_raw", "oldmemory"), oldObs = observation("obs_raw", "oldobservation");
+ await indexRecords([oldObs], [oldMemory]);
+ const vectors = new VectorIndex();
+ for (const id of [oldMemory.id, oldObs.id]) vectors.add(id, "session", new Float32Array([1, 0]));
+ setVectorIndex(vectors);
+ const save = vi.fn(async () => {});
+ setIndexPersistence({ scheduleSave: vi.fn(), save });
+ const raw = { id: oldObs.id, sessionId: "session", timestamp, toolName: "Read", toolInput: {}, toolOutput: "raw evidence" };
+ const commitHash = r.archive({ memories: [memory(oldMemory.id, "nonlatest", { isLatest: false })], observations: { session: [raw] } });
+ expect(await r.call("mem::snapshot-restore", { commitHash })).toMatchObject({ success: true });
+ expect(getSearchIndex().size).toBe(0);
+ expect(vectors.size).toBe(0);
+ expect(await r.kv.get(KV.observations("session"), oldObs.id)).toEqual(raw);
+ expect(save).toHaveBeenCalledTimes(1);
+ });
+
+ it("rejects corrupt graph rows before restoring any memory records", async () => {
+ const r = setup();
+ const original = memory("mem_preflight", "originalmarker");
+ await r.kv.set(KV.memories, original.id, original);
+ await indexRecords([], [original]);
+ const commitHash = r.archive({ memories: [memory(original.id, "invalidarchivemarker")], graphNodes: [{ id: "invalid" }] });
+ expect(await r.call("mem::snapshot-restore", { commitHash })).toMatchObject({ success: false });
+ expect(await r.kv.get(KV.memories, original.id)).toEqual(original);
+ expect(getSearchIndex().search("originalmarker").map(x => x.obsId)).toEqual([original.id]);
+ expect(getSearchIndex().search("invalidarchivemarker")).toEqual([]);
+ });
+
+ it("reconciles committed records when a later restore write fails", async () => {
+ const r = setup();
+ const untouched = memory("mem_failed", "untouchedmarker");
+ await r.kv.set(KV.memories, untouched.id, untouched);
+ await indexRecords([], [untouched]);
+ const save = vi.fn(async () => {});
+ setIndexPersistence({ scheduleSave: vi.fn(), save });
+ const commitHash = r.archive({ memories: [memory("mem_committed", "committedmarker"), memory(untouched.id, "rejectedmarker")] });
+ r.intercept(async (id, p) => { if (id === "state::set" && p.key === untouched.id) throw new Error("synthetic state write failure"); });
+ expect(await r.call("mem::snapshot-restore", { commitHash })).toMatchObject({ success: false, error: "synthetic state write failure" });
+ expect(getSearchIndex().search("committedmarker").map(x => x.obsId)).toEqual(["mem_committed"]);
+ expect(getSearchIndex().search("untouchedmarker").map(x => x.obsId)).toEqual([untouched.id]);
+ expect(getSearchIndex().search("rejectedmarker")).toEqual([]);
+ expect(save).toHaveBeenCalledTimes(1);
+ });
+
+ it("reconciles committed search rows when graph ingestion fails", async () => {
+ const r = setup();
+ const commitHash = r.archive({ memories: [memory("mem_before_graph", "beforegraphmarker")], graphNodes: [node("graph_failure")] });
+ r.intercept(async (id, p) => { if (id === "state::set" && p.key === "graph_failure") throw new Error("synthetic graph write failure"); });
+ expect(await r.call("mem::snapshot-restore", { commitHash })).toMatchObject({ success: false });
+ expect(getSearchIndex().search("beforegraphmarker").map(x => x.obsId)).toEqual(["mem_before_graph"]);
+ });
+
+ it("indexes the current committed row if another writer replaced it during restore", async () => {
+ const r = setup();
+ const commitHash = r.archive({ memories: [memory("mem_race", "snapshotmarker")], graphNodes: [node("gate")] });
+ r.intercept(async (id, p) => {
+ if (id === "state::set" && p.key === "gate") {
+ r.intercept();
+ await r.kv.set(KV.memories, "mem_race", memory("mem_race", "newerwriter"));
+ }
+ });
+ expect(await r.call("mem::snapshot-restore", { commitHash })).toMatchObject({ success: true });
+ expect(getSearchIndex().search("snapshotmarker")).toEqual([]);
+ expect(getSearchIndex().search("newerwriter").map(x => x.obsId)).toEqual(["mem_race"]);
+ });
+
+ it("preserves a newer first record while reconciliation waits for a second record", async () => {
+ const r = setup();
+ const first = memory("mem_first", "firstsnapshotmarker");
+ const second = memory("mem_second", "secondsnapshotmarker");
+ const commitHash = r.archive({ memories: [first, second] });
+ const vectors = new VectorIndex();
+ setVectorIndex(vectors);
+ setEmbeddingProvider({
+ name: "synthetic", dimensions: 2, embed: async () => new Float32Array([1, 0]),
+ embedBatch: async (texts) => texts.map((text) => new Float32Array(text.includes("newerfirstmarker") ? [0, 1] : [1, 0])),
+ });
+ let entered!: () => void;
+ let release!: () => void;
+ const reading = new Promise<void>((resolve) => { entered = resolve; });
+ const blocked = new Promise<void>((resolve) => { release = resolve; });
+ r.intercept(async (id, p) => {
+ if (id === "state::get" && p.scope === KV.memories && p.key === second.id) {
+ entered();
+ await blocked;
+ }
+ });
+ const restoring = r.call("mem::snapshot-restore", { commitHash });
+ await reading;
+ const newer = memory(first.id, "newerfirstmarker");
+ await r.kv.set(KV.memories, first.id, newer);
+ await indexRecords([], [newer]);
+ release();
+ expect(await restoring).toMatchObject({ success: true });
+ expect(getSearchIndex().search("firstsnapshotmarker")).toEqual([]);
+ expect(getSearchIndex().search("newerfirstmarker").map((hit) => hit.obsId)).toEqual([first.id]);
+ expect(getSearchIndex().search("secondsnapshotmarker").map((hit) => hit.obsId)).toEqual([second.id]);
+ expect(vectors.get(first.id)?.embedding).toEqual(new Float32Array([0, 1]));
+ });
+
+ it("reads snapshots larger than execFile's default output buffer", async () => {
+ const r = setup();
+ const large = memory("mem_large", "largemarker", { content: "largemarker " + "x".repeat(1_100_000) });
+ const commitHash = r.archive({ memories: [large] });
+ expect(await r.call("mem::snapshot-restore", { commitHash })).toMatchObject({ success: true });
+ expect((await r.kv.get<Memory>(KV.memories, large.id))?.content.length).toBe(large.content.length);
+ expect(getSearchIndex().has(large.id)).toBe(true);
+ });
+
+ it("reports index reconciliation failures, flushes stale-entry removals, and permits retry", async () => {
+ const r = setup();
+ await indexRecords([], [memory("mem_retry", "obsoletekeyword")]);
+ const save = vi.fn(async () => {});
+ setIndexPersistence({ scheduleSave: vi.fn(), save });
+ const commitHash = r.archive({ memories: [memory("mem_retry", "restoredkeyword")] });
+ r.intercept(async (id, p) => {
+ if (id === "state::get" && p.scope === KV.memories && p.key === "mem_retry") throw new Error("synthetic index read failure");
+ });
+ expect(await r.call("mem::snapshot-restore", { commitHash })).toMatchObject({ success: false, error: "synthetic index read failure" });
+ expect(getSearchIndex().has("mem_retry")).toBe(false);
+ expect(save).toHaveBeenCalledTimes(1);
+ r.intercept();
+ expect((await r.kv.get<Memory>(KV.memories, "mem_retry"))?.content).toBe("restoredkeyword");
+ expect(await r.call("mem::snapshot-restore", { commitHash })).toMatchObject({ success: true });
+ expect(getSearchIndex().search("restoredkeyword").map(x => x.obsId)).toEqual(["mem_retry"]);
+ });
+
+ it("embeds replacement records using their restored text", async () => {
+ const r = setup();
+ const vectors = new VectorIndex();
+ vectors.add("mem_vector", "memory", new Float32Array([1, 0]));
+ setVectorIndex(vectors);
+ const embedBatch = vi.fn(async (texts: string[]) => texts.map(() => new Float32Array([0, 1])));
+ setEmbeddingProvider({ name: "synthetic", dimensions: 2, embed: async () => new Float32Array([0, 1]), embedBatch });
+ const commitHash = r.archive({ memories: [memory("mem_vector", "restoredvector")] });
+ expect(await r.call("mem::snapshot-restore", { commitHash })).toMatchObject({ success: true });
+ expect(embedBatch).toHaveBeenCalledWith(["restoredvector restoredvector"]);
+ expect(Array.from(vectors.get("mem_vector")!.embedding)).toEqual([0, 1]);
+ });
+});
diff --git a/test/graph-ingestion.test.ts b/test/graph-ingestion.test.ts
new file mode 100644
index 00000000..9e440194
--- /dev/null
+++ b/test/graph-ingestion.test.ts
@@ -0,0 +1,782 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { StateKV, applyUpdateOps } from "../src/state/kv.js";
+import { KV } from "../src/state/schema.js";
+import { pinGraphState, setGraphGenerationListener } from "../src/state/graph-generation.js";
+import { persistGraphDelta, registerGraphFunction } from "../src/functions/graph.js";
+import { persistGraphRecords } from "../src/state/graph-ingestion.js";
+import { registerViewerStreamTriggers } from "../src/triggers/viewer-streams.js";
+import { resetViewerCounts } from "../src/state/viewer-counts.js";
+import { setAuditRecordedListener } from "../src/functions/audit.js";
+import type { GraphEdge, GraphNode, GraphSnapshot } from "../src/types.js";
+
+vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }));
+
+const timestamp = "2026-10-12T12:00:00.000Z";
+const later = "2026-10-13T12:00:00.000Z";
+const node = (id: string, overrides: Partial<GraphNode> = {}): GraphNode => ({
+ id, name: id, type: "concept", properties: {}, sourceObservationIds: [id], createdAt: timestamp,
+ ...overrides,
+});
+const edge = (id: string, sourceNodeId: string, targetNodeId: string, overrides: Partial<GraphEdge> = {}): GraphEdge => ({
+ id, sourceNodeId, targetNodeId, type: "related_to", weight: 0.8,
+ sourceObservationIds: [id], createdAt: timestamp, ...overrides,
+});
+const inScope = (physical: string, logical: string) => physical === logical || physical.startsWith(`${logical}:generation:`);
+
+function deferred() {
+ let resolve!: () => void;
+ const promise = new Promise<void>((done) => { resolve = done; });
+ return { promise, resolve };
+}
+
+type Payload = { scope: string; key: string; value?: any; [key: string]: any };
+
+function setup(backend: "file" | "redis" = "file") {
+ const store = new Map<string, Map<string, unknown>>();
+ const handlers = new Map<string, (data?: any) => Promise<any>>();
+ const calls: Array<{ id: string; payload: Payload }> = [];
+ const sent: any[] = [];
+ let intercept: ((id: string, payload: Payload) => Promise<void> | void) | undefined;
+ const sdk = {
+ registerFunction: (id: string, fn: (data?: any) => Promise<any>) => handlers.set(id, fn),
+ registerTrigger: vi.fn(),
+ trigger: async ({ function_id: id, payload }: { function_id: string; payload: any }): Promise<any> => {
+ if (id === "stream::send") { sent.push(structuredClone(payload)); return {}; }
+ if (!id.startsWith("state::")) return handlers.get(id)!(payload);
+ calls.push({ id, payload: structuredClone(payload) });
+ await intercept?.(id, payload);
+ const rows = store.get(payload.scope) ?? new Map<string, unknown>();
+ if (id === "state::get") return structuredClone(rows.get(payload.key) ?? null);
+ if (id === "state::list") return structuredClone([...rows.values()]);
+ if (id === "state::delete") { rows.delete(payload.key); return; }
+ if (id === "state::set") {
+ rows.set(payload.key, structuredClone(payload.value));
+ store.set(payload.scope, rows);
+ return structuredClone(payload.value);
+ }
+ if (id === "state::update") {
+ const oldValue = structuredClone(rows.get(payload.key) ?? null);
+ const newValue = applyUpdateOps(oldValue, payload.ops);
+ rows.set(payload.key, structuredClone(newValue));
+ store.set(payload.scope, rows);
+ return { old_value: oldValue, new_value: newValue, errors: [] };
+ }
+ throw new Error(`Unexpected state call ${id}`);
+ },
+ };
+ const kv = new StateKV(sdk as never, { backend });
+ registerGraphFunction(sdk as never, kv, { name: "noop" } as never);
+ const call = (id: string, payload: any = {}) => sdk.trigger({ function_id: id, payload });
+ const snapshot = async (view = kv) => (await view.get<GraphSnapshot>(KV.graphSnapshot, "current"))!;
+ return { kv, sdk, store, calls, sent, call, snapshot, intercept: (fn?: typeof intercept) => { intercept = fn; } };
+}
+
+async function degrees(kv: StateKV, ids: string[]) {
+ return Object.fromEntries(await Promise.all(ids.map(async (id) => [id, await kv.get<number>(KV.graphNodeDegree, id)])));
+}
+
+afterEach(() => {
+ setGraphGenerationListener(null);
+ setAuditRecordedListener(null);
+ resetViewerCounts();
+});
+
+describe("raw graph ingestion reconciliation", () => {
+ it("checks a clean snapshot once across repeated graph row reads until the next snapshot write", async () => {
+ const { kv, snapshot, calls } = setup();
+ await persistGraphRecords(kv, [node("a")], [], { mode: "merge" });
+ calls.length = 0;
+ for (let i = 0; i < 100; i++) {
+ await kv.get(KV.graphNodes, "a");
+ await kv.get(KV.graphNodeDegree, "a");
+ await kv.get(KV.graphNameIndex, "concept|a");
+ }
+ const snapshotReads = () => calls.filter((call) => call.id === "state::get" && call.payload.scope === KV.graphSnapshot).length;
+ expect(snapshotReads()).toBe(1);
+ const clean = await snapshot();
+ await kv.set(KV.graphSnapshot, "current", clean);
+ calls.length = 0;
+ await kv.get(KV.graphNodes, "a");
+ await kv.get(KV.graphNodes, "a");
+ expect(snapshotReads()).toBe(1);
+ });
+
+ it("bounds snapshot check entries across generations and checks an evicted scope again", async () => {
+ const { kv, calls } = setup();
+ const scope = (i: number) => `${KV.graphNodes}:generation:cache-${i}`;
+ const snapshotReads = () => calls.filter((call) => call.id === "state::get" && inScope(call.payload.scope, KV.graphSnapshot)).length;
+ for (let i = 0; i < 64; i++) await kv.get(scope(i), "missing");
+ expect(snapshotReads()).toBe(64);
+ await kv.get(scope(0), "missing");
+ expect(snapshotReads()).toBe(64);
+ await kv.get(scope(64), "missing");
+ await kv.get(scope(64), "missing");
+ expect(snapshotReads()).toBe(65);
+ await kv.get(scope(0), "missing");
+ expect(snapshotReads()).toBe(66);
+ });
+
+ it("does not cache a failed clean snapshot check", async () => {
+ const { kv, calls, intercept } = setup();
+ intercept((id, p) => {
+ if (id === "state::get" && p.scope === KV.graphSnapshot) throw new Error("snapshot unavailable");
+ });
+ await expect(kv.get(KV.graphNodes, "missing")).rejects.toThrow("snapshot unavailable");
+ intercept();
+ await kv.get(KV.graphNodes, "missing");
+ await kv.get(KV.graphNodes, "missing");
+ expect(calls.filter((call) => call.id === "state::get" && call.payload.scope === KV.graphSnapshot)).toHaveLength(2);
+ });
+
+ it("does not restore an evicted check when an older clean peek finishes", async () => {
+ const { kv, sdk, calls } = setup();
+ const entered = deferred();
+ const release = deferred();
+ const trigger = sdk.trigger.bind(sdk);
+ let paused = false;
+ vi.spyOn(sdk, "trigger").mockImplementation(async (request) => {
+ const value = await trigger(request);
+ if (!paused && request.function_id === "state::get" && request.payload.scope === KV.graphSnapshot) {
+ paused = true; entered.resolve(); await release.promise;
+ }
+ return value;
+ });
+ const reading = kv.get(KV.graphNodes, "missing");
+ await entered.promise;
+ try {
+ for (let i = 0; i < 64; i++) await kv.get(`${KV.graphNodes}:generation:cache-${i}`, "missing");
+ } finally {
+ release.resolve(); await reading;
+ }
+ calls.length = 0;
+ await kv.get(KV.graphNodes, "missing");
+ await kv.get(KV.graphNodes, "missing");
+ expect(calls.filter((call) => call.id === "state::get" && call.payload.scope === KV.graphSnapshot)).toHaveLength(1);
+ });
+
+ it.each([false, true])("invalidates an in-flight clean peek after snapshot deletion, response lost: %s", async (responseLost) => {
+ const { kv, store, calls, intercept } = setup();
+ await persistGraphRecords(kv, [node("before")], [], { mode: "merge" });
+ const entered = deferred();
+ const release = deferred();
+ intercept(async (id, p) => {
+ if (id === "state::delete" && p.scope === KV.graphSnapshot) {
+ entered.resolve(); await release.promise;
+ if (responseLost) {
+ store.get(KV.graphSnapshot)!.delete("current");
+ throw new Error("delete response lost");
+ }
+ }
+ });
+ const deleting = kv.delete(KV.graphSnapshot, "current");
+ const finished = responseLost ? expect(deleting).rejects.toThrow("delete response lost") : deleting;
+ await entered.promise;
+ try {
+ expect(await kv.get(KV.graphNodes, "before")).toMatchObject({ id: "before" });
+ } finally {
+ release.resolve(); await finished; intercept();
+ }
+ calls.length = 0;
+ await kv.get(KV.graphNodes, "before");
+ await kv.get(KV.graphNodes, "before");
+ expect(calls.filter((call) => call.id === "state::get" && call.payload.scope === KV.graphSnapshot)).toHaveLength(1);
+ });
+
+ it.each([
+ ["file", "set"], ["file", "update"], ["redis", "update"],
+ ] as const)("invalidates a clean in-flight peek when a %s %s journal commits but its response is lost", async (backend, operation) => {
+ const { kv, store, snapshot, intercept } = setup(backend);
+ await persistGraphRecords(kv, [node("before")], [], { mode: "merge" });
+ const clean = await snapshot();
+ const added = node("added");
+ const next: GraphSnapshot = {
+ ...clean, topNodes: [...clean.topNodes, added],
+ topDegrees: { ...clean.topDegrees, added: 0 },
+ stats: { ...clean.stats, totalNodes: 2, nodesByType: { concept: 2 } },
+ };
+ const pending: GraphSnapshot = {
+ ...clean, dirty: true,
+ pendingMutation: {
+ snapshot: next,
+ writes: [{ scope: KV.graphNodes, key: added.id, value: added }],
+ },
+ };
+ const entered = deferred();
+ const release = deferred();
+ let paused = false;
+ intercept(async (id, p) => {
+ if (!paused && (id === "state::set" || id === "state::update") && p.scope === KV.graphSnapshot) {
+ paused = true; entered.resolve(); await release.promise;
+ store.get(KV.graphSnapshot)!.set("current", structuredClone(pending));
+ throw new Error("committed response lost");
+ }
+ });
+ const writing = operation === "set"
+ ? kv.set(KV.graphSnapshot, "current", pending)
+ : kv.update(KV.graphSnapshot, "current", [{ type: "set", path: "", value: pending }]);
+ const failed = expect(writing).rejects.toThrow("committed response lost");
+ await entered.promise;
+ try {
+ expect(await kv.get(KV.graphNodes, "before")).toMatchObject({ id: "before" });
+ } finally {
+ release.resolve(); await failed; intercept();
+ }
+ expect((await snapshot()).pendingMutation).toBeUndefined();
+ expect((await snapshot()).stats.totalNodes).toBe(2);
+ expect(await kv.get(KV.graphNodes, "added")).toMatchObject({ id: "added" });
+ });
+
+ it("serves a clean committed snapshot while a larger ingestion is still planning its next batch", async () => {
+ const { kv, call, intercept } = setup();
+ const entered = deferred();
+ const release = deferred();
+ intercept(async (id, p) => {
+ if (id === "state::get" && p.scope === KV.graphNodes && p.key === "batch-50") {
+ entered.resolve(); await release.promise;
+ }
+ });
+ const writing = persistGraphRecords(kv, Array.from({ length: 51 }, (_, i) => node(`batch-${i}`)), [], { mode: "merge" });
+ await entered.promise;
+ let observed: { totalNodes: number } | undefined;
+ const reading = call("mem::graph-stats").then((result) => { observed = result; });
+ try {
+ await new Promise<void>((done) => setImmediate(done));
+ expect(observed).toMatchObject({ totalNodes: 50 });
+ } finally {
+ release.resolve();
+ await Promise.all([writing, reading]);
+ }
+ });
+
+ it("does not cache a clean peek that was overtaken by a failed journaled write", async () => {
+ const { kv, sdk, snapshot, intercept } = setup();
+ await persistGraphRecords(kv, [node("before")], [], { mode: "merge" });
+ const entered = deferred();
+ const release = deferred();
+ const trigger = sdk.trigger.bind(sdk);
+ let paused = false;
+ vi.spyOn(sdk, "trigger").mockImplementation(async (request) => {
+ const value = await trigger(request);
+ if (!paused && request.function_id === "state::get" && request.payload.scope === KV.graphSnapshot) {
+ paused = true; entered.resolve(); await release.promise;
+ }
+ return value;
+ });
+ const reading = snapshot();
+ await entered.promise;
+ intercept((id, p) => {
+ if (id === "state::set" && p.scope === KV.graphNameIndex && p.key === "concept|after") throw new Error("injected failure");
+ });
+ try {
+ await expect(persistGraphRecords(kv, [node("after")], [], { mode: "merge" })).rejects.toThrow("injected failure");
+ } finally {
+ intercept(); release.resolve();
+ }
+ await reading;
+ const recovered = await snapshot();
+ expect(recovered.pendingMutation).toBeUndefined();
+ expect(recovered.stats.totalNodes).toBe(2);
+ expect(await kv.get(KV.graphNodes, "after")).toMatchObject({ id: "after" });
+ });
+
+ it("does not cache old clean state while an invalidated journal write is still in flight", async () => {
+ const { kv, call, snapshot, intercept } = setup();
+ await persistGraphRecords(kv, [node("before")], [], { mode: "merge" });
+ const entered = deferred();
+ const release = deferred();
+ intercept(async (id, p) => {
+ if (id === "state::set" && p.scope === KV.graphSnapshot && p.value?.pendingMutation) {
+ entered.resolve(); await release.promise;
+ }
+ if (id === "state::set" && p.scope === KV.graphNameIndex && p.key === "concept|after") throw new Error("injected failure");
+ });
+ const writing = persistGraphRecords(kv, [node("after")], [], { mode: "merge" });
+ const failed = expect(writing).rejects.toThrow("injected failure");
+ await entered.promise;
+ let observed: { totalNodes: number } | undefined;
+ const reading = call("mem::graph-stats").then((result) => { observed = result; });
+ try {
+ await new Promise<void>((done) => setImmediate(done));
+ expect(observed).toMatchObject({ totalNodes: 1 });
+ } finally {
+ release.resolve();
+ await Promise.all([failed, reading]);
+ intercept();
+ }
+ const recovered = await snapshot();
+ expect(recovered.pendingMutation).toBeUndefined();
+ expect(recovered.stats.totalNodes).toBe(2);
+ expect(await kv.get(KV.graphNodes, "after")).toMatchObject({ id: "after" });
+ });
+
+ it("matches a raw-record oracle through a deterministic sequence of overlapping mutations", async () => {
+ const { kv, snapshot } = setup();
+ let randomState = 0x1525;
+ const random = (limit: number) => {
+ randomState = (Math.imul(randomState, 1664525) + 1013904223) >>> 0;
+ return randomState % limit;
+ };
+ const nodes = new Map<string, GraphNode>();
+ const edges = new Map<string, GraphEdge>();
+ const namesSeen = new Set<string>();
+ const edgeKeysSeen = new Set<string>();
+ const apply = async (incomingNodes: GraphNode[], incomingEdges: GraphEdge[]) => {
+ await persistGraphRecords(kv, incomingNodes, incomingEdges, { mode: "merge" });
+ for (const n of incomingNodes) { nodes.set(n.id, n); namesSeen.add(`${n.type}|${n.name}`); }
+ for (const e of incomingEdges) { edges.set(e.id, e); edgeKeysSeen.add(`${e.sourceNodeId}|${e.targetNodeId}|${e.type}`); }
+ };
+ await apply(
+ Array.from({ length: 16 }, (_, i) => node(`n${i}`, { name: `shared-${i % 4}` })),
+ Array.from({ length: 24 }, (_, i) => edge(`e${i}`, `n${random(16)}`, `n${random(16)}`)),
+ );
+ for (let step = 0; step < 100; step++) {
+ const incomingNodes: GraphNode[] = [];
+ const incomingEdges: GraphEdge[] = [];
+ if (step % 3 !== 2) {
+ const id = `n${random(16)}`;
+ const updated = node(id, {
+ name: `shared-${random(5)}`,
+ type: (["concept", "file", "function"] as const)[random(3)],
+ stale: random(5) === 0,
+ properties: { revision: step },
+ });
+ if (step % 7 === 0) incomingNodes.push(node(id, { name: "intermediate" }));
+ incomingNodes.push(updated);
+ }
+ if (step % 3 !== 0) {
+ const id = `e${random(24)}`;
+ const updated = edge(id, `n${random(16)}`, `n${random(16)}`, {
+ type: (["related_to", "uses", "imports"] as const)[random(3)],
+ stale: random(4) === 0,
+ weight: random(100) / 100,
+ });
+ if (step % 9 === 0) incomingEdges.push(edge(id, "n0", "n0"));
+ incomingEdges.push(updated);
+ }
+ await apply(incomingNodes, incomingEdges);
+
+ const liveNodes = [...nodes.values()].filter((n) => !n.stale);
+ const liveEdges = [...edges.values()].filter((e) => !e.stale);
+ const liveIds = new Set(liveNodes.map((n) => n.id));
+ const countTypes = (rows: Array<{ type: string }>) => {
+ const counts: Record<string, number> = {};
+ for (const row of rows) counts[row.type] = (counts[row.type] ?? 0) + 1;
+ return counts;
+ };
+ const expectedDegrees = Object.fromEntries([...nodes.keys()].map((id) => [id, 0]));
+ for (const e of liveEdges) { expectedDegrees[e.sourceNodeId]++; expectedDegrees[e.targetNodeId]++; }
+ const snap = await snapshot();
+ expect(snap.stats, `counts after step ${step}`).toEqual({
+ totalNodes: liveNodes.length, totalEdges: liveEdges.length,
+ nodesByType: countTypes(liveNodes), edgesByType: countTypes(liveEdges),
+ });
+ expect(snap.topNodes.map((n) => n.id).sort(), `nodes after step ${step}`).toEqual([...liveIds].sort());
+ expect(snap.topEdges.map((e) => e.id).sort(), `edges after step ${step}`).toEqual(
+ liveEdges.filter((e) => liveIds.has(e.sourceNodeId) && liveIds.has(e.targetNodeId)).map((e) => e.id).sort(),
+ );
+ expect(await degrees(kv, [...nodes.keys()]), `degrees after step ${step}`).toEqual(expectedDegrees);
+ for (const n of snap.topNodes) {
+ expect(n).toEqual(nodes.get(n.id));
+ expect(snap.topDegrees[n.id]).toBe(expectedDegrees[n.id]);
+ }
+ for (const e of snap.topEdges) expect(e).toEqual(edges.get(e.id));
+ for (const key of namesSeen) {
+ const members = liveNodes.filter((n) => `${n.type}|${n.name}` === key).map((n) => n.id);
+ const indexed = await kv.get(KV.graphNameIndex, key);
+ if (members.length) expect(members, `name ${key} after step ${step}`).toContain(indexed);
+ else expect(indexed, `removed name ${key} after step ${step}`).toBeNull();
+ }
+ for (const key of edgeKeysSeen) {
+ const members = liveEdges.filter((e) => `${e.sourceNodeId}|${e.targetNodeId}|${e.type}` === key).map((e) => e.id);
+ const indexed = await kv.get(KV.graphEdgeKey, key);
+ if (members.length) expect(members, `edge key ${key} after step ${step}`).toContain(indexed);
+ else expect(indexed, `removed edge key ${key} after step ${step}`).toBeNull();
+ }
+ }
+ expect(await kv.list(KV.graphNodes)).toHaveLength(nodes.size);
+ expect(await kv.list(KV.graphEdges)).toHaveLength(edges.size);
+ });
+
+ it("preserves raw IDs and endpoint references when multiple records share a name or edge key", async () => {
+ const { kv, snapshot } = setup();
+ const nodes = [node("raw-a", { name: "shared" }), node("raw-b", { name: "shared" })];
+ const edges = [edge("raw-e1", "raw-a", "raw-b"), edge("raw-e2", "raw-a", "raw-b")];
+ await persistGraphRecords(kv, nodes, edges, { mode: "merge" });
+ expect((await kv.list<GraphNode>(KV.graphNodes)).map((n) => n.id).sort()).toEqual(["raw-a", "raw-b"]);
+ expect((await kv.list<GraphEdge>(KV.graphEdges)).map((e) => [e.id, e.sourceNodeId, e.targetNodeId]).sort()).toEqual([
+ ["raw-e1", "raw-a", "raw-b"], ["raw-e2", "raw-a", "raw-b"],
+ ]);
+ expect((await snapshot()).stats).toMatchObject({ totalNodes: 2, totalEdges: 2 });
+ expect(await degrees(kv, ["raw-a", "raw-b"])).toEqual({ "raw-a": 2, "raw-b": 2 });
+ expect(["raw-a", "raw-b"]).toContain(await kv.get(KV.graphNameIndex, "concept|shared"));
+ expect(["raw-e1", "raw-e2"]).toContain(await kv.get(KV.graphEdgeKey, "raw-a|raw-b|related_to"));
+
+ await persistGraphRecords(kv, nodes, edges, { mode: "merge" });
+ expect((await snapshot()).stats).toMatchObject({ totalNodes: 2, totalEdges: 2 });
+ expect(await degrees(kv, ["raw-a", "raw-b"])).toEqual({ "raw-a": 2, "raw-b": 2 });
+ });
+
+ it("reconciles same-ID renames, type changes and edge retargeting without resetting degrees", async () => {
+ const { kv, snapshot } = setup();
+ await persistGraphRecords(kv, [node("a"), node("b"), node("c")], [edge("e", "a", "b")], { mode: "merge" });
+ await persistGraphRecords(kv, [node("a", { name: "renamed", type: "file", properties: { imported: true } })], [], { mode: "merge" });
+ expect(await kv.get(KV.graphNameIndex, "concept|a")).toBeNull();
+ expect(await kv.get(KV.graphNameIndex, "file|renamed")).toBe("a");
+ expect(await kv.get(KV.graphNodeDegree, "a")).toBe(1);
+ expect((await snapshot()).stats).toMatchObject({ totalNodes: 3, totalEdges: 1, nodesByType: { concept: 2, file: 1 } });
+ expect((await snapshot()).topNodes.find((n) => n.id === "a")).toMatchObject({ name: "renamed", type: "file", properties: { imported: true } });
+
+ await persistGraphRecords(kv, [], [edge("e", "b", "c", { type: "uses", weight: 0.25 })], { mode: "merge" });
+ expect(await kv.get(KV.graphEdgeKey, "a|b|related_to")).toBeNull();
+ expect(await kv.get(KV.graphEdgeKey, "b|c|uses")).toBe("e");
+ expect(await degrees(kv, ["a", "b", "c"])).toEqual({ a: 0, b: 1, c: 1 });
+ const snap = await snapshot();
+ expect(snap.stats.totalEdges).toBe(1);
+ expect(snap.stats.edgesByType.uses).toBe(1);
+ expect(snap.stats.edgesByType.related_to ?? 0).toBe(0);
+ expect(snap.topEdges).toEqual([expect.objectContaining({ id: "e", sourceNodeId: "b", targetNodeId: "c", type: "uses", weight: 0.25 })]);
+ });
+
+ it("removes only the overwritten record's own old lookup entries", async () => {
+ const { kv } = setup();
+ await persistGraphRecords(kv, [node("a"), node("b"), node("c")], [edge("e", "a", "b"), edge("other-e", "b", "c")], { mode: "merge" });
+ await kv.set(KV.graphNameIndex, "concept|a", "b");
+ await kv.set(KV.graphEdgeKey, "a|b|related_to", "other-e");
+ await persistGraphRecords(kv, [node("a", { name: "new-name" })], [edge("e", "a", "c")], { mode: "merge" });
+ expect(await kv.get(KV.graphNameIndex, "concept|a")).toBe("b");
+ expect(await kv.get(KV.graphEdgeKey, "a|b|related_to")).toBe("other-e");
+ expect(await kv.get(KV.graphNameIndex, "concept|new-name")).toBe("a");
+ expect(await kv.get(KV.graphEdgeKey, "a|c|related_to")).toBe("e");
+ });
+
+ it("applies duplicate IDs once using the final accepted record in the batch", async () => {
+ const { kv, snapshot } = setup();
+ await persistGraphRecords(kv, [node("a"), node("a", { name: "final", type: "file" }), node("b")], [
+ edge("e", "a", "a"), edge("e", "a", "b", { type: "uses" }),
+ ], { mode: "merge" });
+ expect((await snapshot()).stats).toMatchObject({ totalNodes: 2, totalEdges: 1, nodesByType: { file: 1, concept: 1 } });
+ expect(await kv.get(KV.graphNameIndex, "concept|a")).toBeNull();
+ expect(await kv.get(KV.graphNameIndex, "file|final")).toBe("a");
+ expect(await kv.get(KV.graphEdgeKey, "a|a|related_to")).toBeNull();
+ expect(await kv.get(KV.graphEdgeKey, "a|b|uses")).toBe("e");
+ expect(await degrees(kv, ["a", "b"])).toEqual({ a: 1, b: 1 });
+ });
+
+ it("handles self loops and repeated stale/live transitions without double counting", async () => {
+ const { kv, snapshot } = setup();
+ await persistGraphRecords(kv, [node("a"), node("b")], [edge("loop", "a", "a"), edge("e", "a", "b")], { mode: "merge" });
+ expect(await degrees(kv, ["a", "b"])).toEqual({ a: 3, b: 1 });
+ await persistGraphRecords(kv, [], [edge("loop", "a", "a", { stale: true })], { mode: "merge" });
+ await persistGraphRecords(kv, [], [edge("loop", "a", "a", { stale: true })], { mode: "merge" });
+ expect(await degrees(kv, ["a", "b"])).toEqual({ a: 1, b: 1 });
+ expect((await snapshot()).stats.totalEdges).toBe(1);
+ expect((await snapshot()).topEdges.map((e) => e.id)).toEqual(["e"]);
+ expect(await kv.get(KV.graphEdgeKey, "a|a|related_to")).toBeNull();
+ await persistGraphRecords(kv, [], [edge("loop", "a", "a")], { mode: "merge" });
+ expect(await degrees(kv, ["a", "b"])).toEqual({ a: 3, b: 1 });
+ expect((await snapshot()).stats.totalEdges).toBe(2);
+
+ await persistGraphRecords(kv, [node("a", { stale: true })], [], { mode: "merge" });
+ const stale = await snapshot();
+ expect(stale.stats.totalNodes).toBe(1);
+ expect(stale.topNodes.map((n) => n.id)).toEqual(["b"]);
+ expect(stale.topEdges).toEqual([]);
+ expect(await kv.get(KV.graphNameIndex, "concept|a")).toBeNull();
+ await persistGraphRecords(kv, [node("a")], [], { mode: "merge" });
+ expect((await snapshot()).stats.totalNodes).toBe(2);
+ expect(await kv.get(KV.graphNodeDegree, "a")).toBe(3);
+ });
+
+ it("honors skip and LWW decisions before touching derived state", async () => {
+ const { kv, snapshot } = setup();
+ await persistGraphRecords(kv, [node("a"), node("b")], [edge("e", "a", "b")], { mode: "merge" });
+ const original = await snapshot();
+ await persistGraphRecords(kv, [node("a", { name: "skip", type: "file" })], [edge("e", "b", "b")], { mode: "skip" });
+ expect((await snapshot()).stats).toEqual(original.stats);
+ expect(await kv.get<GraphNode>(KV.graphNodes, "a")).toMatchObject({ name: "a", type: "concept" });
+ expect(await degrees(kv, ["a", "b"])).toEqual({ a: 1, b: 1 });
+ await persistGraphRecords(kv, [node("a", { name: "equal-timestamp" })], [edge("e", "b", "b")], { mode: "lww" });
+ expect(await kv.get<GraphNode>(KV.graphNodes, "a")).toMatchObject({ name: "a" });
+ await persistGraphRecords(kv, [node("a", { name: "newer", updatedAt: later })], [edge("e", "b", "b", { createdAt: later })], { mode: "lww" });
+ expect(await kv.get<GraphNode>(KV.graphNodes, "a")).toMatchObject({ name: "newer" });
+ expect(await degrees(kv, ["a", "b"])).toEqual({ a: 0, b: 2 });
+ expect((await snapshot()).stats).toMatchObject({ totalNodes: 2, totalEdges: 1 });
+ });
+
+ it("updates a large graph using targeted operations and a bounded snapshot sample", async () => {
+ const { kv, snapshot, calls, intercept } = setup();
+ const topNodes = Array.from({ length: 500 }, (_, i) => node(`existing-${i}`));
+ const seeded: GraphSnapshot = {
+ version: 1, topNodes, topEdges: [], topDegrees: Object.fromEntries(topNodes.map((n) => [n.id, 0])),
+ stats: { totalNodes: 75000, totalEdges: 0, nodesByType: { concept: 75000 }, edgesByType: {} },
+ updatedAt: timestamp, dirty: false,
+ };
+ await kv.set(KV.graphSnapshot, "current", seeded);
+ for (const n of topNodes) {
+ await kv.set(KV.graphNodes, n.id, n);
+ await kv.set(KV.graphNodeDegree, n.id, 0);
+ }
+ calls.length = 0;
+ intercept((id, p) => {
+ if (id === "state::list" && p.scope.startsWith("mem:graph:")) throw new Error("Unbounded graph enumeration");
+ });
+ await persistGraphRecords(kv, [node("new")], [edge("new-edge", "new", "existing-0")], { mode: "merge" });
+ const snap = await snapshot();
+ expect(snap.stats).toMatchObject({ totalNodes: 75001, totalEdges: 1 });
+ expect(snap.topNodes.length).toBeLessThanOrEqual(500);
+ expect(snap.topNodes.some((n) => n.id === "new")).toBe(true);
+ expect(snap.topEdges).toContainEqual(expect.objectContaining({ id: "new-edge" }));
+ expect(await degrees(kv, ["new", "existing-0"])).toEqual({ new: 1, "existing-0": 1 });
+ await persistGraphRecords(kv, [node("existing-0", { stale: true })], [], { mode: "merge" });
+ const removed = await snapshot();
+ expect(removed.stats.totalNodes).toBe(75000);
+ expect(removed.topNodes.some((n) => n.id === "existing-0")).toBe(false);
+ expect(removed.topEdges).toEqual([]);
+ expect(removed.sampleIncomplete).toBe(true);
+ expect(calls.some((c) => c.id === "state::list")).toBe(false);
+ });
+
+ it("does not change raw rows when the durable mutation journal cannot be written", async () => {
+ const { kv, snapshot, intercept } = setup();
+ await persistGraphRecords(kv, [node("before")], [], { mode: "merge" });
+ intercept((id, p) => {
+ if (id === "state::set" && inScope(p.scope, KV.graphSnapshot) && p.key === "current" && p.value?.pendingMutation) {
+ throw new Error("injected journal failure");
+ }
+ });
+ await expect(persistGraphRecords(kv, [node("after")], [], { mode: "merge" })).rejects.toThrow("injected journal failure");
+ intercept();
+ expect(await kv.get(KV.graphNodes, "after")).toBeNull();
+ expect((await snapshot()).stats.totalNodes).toBe(1);
+ });
+
+ it("rejects an oversized reconciliation journal before sending it to the engine", async () => {
+ const { kv, snapshot, intercept } = setup();
+ await persistGraphRecords(kv, [node("before")], [], { mode: "merge" });
+ let sentOversized = false;
+ intercept((id, p) => {
+ if (id === "state::set" && Buffer.byteLength(JSON.stringify(p), "utf8") > 16 * 1024 * 1024) {
+ sentOversized = true;
+ throw new Error("Engine transport disconnected");
+ }
+ });
+ const oversized = node("large", { properties: { content: "x".repeat(8 * 1024 * 1024) } });
+ await expect(persistGraphRecords(kv, [oversized], [], { mode: "merge" })).rejects.toThrow();
+ expect(sentOversized).toBe(false);
+ expect(await kv.get(KV.graphNodes, "large")).toBeNull();
+ expect((await snapshot()).stats.totalNodes).toBe(1);
+ expect((await snapshot()).pendingMutation).toBeUndefined();
+ });
+
+ it("validates the complete persisted journal before applying any of its writes", async () => {
+ const { kv, sdk, store, snapshot } = setup();
+ await persistGraphRecords(kv, [node("before")], [], { mode: "merge" });
+ const clean = await snapshot();
+ store.get(KV.graphSnapshot)!.set("current", {
+ ...clean, dirty: true,
+ pendingMutation: {
+ snapshot: clean,
+ writes: [
+ { scope: KV.graphNodes, key: "injected", value: node("injected") },
+ { scope: KV.memories, key: "invalid-scope", value: { content: "unexpected" } },
+ ],
+ },
+ });
+ const restarted = new StateKV(sdk as never);
+ await expect(restarted.get(KV.graphSnapshot, "current")).rejects.toThrow("Invalid graph reconciliation write");
+ expect(store.get(KV.graphNodes)?.has("injected")).toBe(false);
+ expect(store.get(KV.memories)?.has("invalid-scope") ?? false).toBe(false);
+ expect(store.get(KV.graphSnapshot)?.get("current")).toMatchObject({ dirty: true });
+ });
+
+ it.each(["file", "redis"] as const)("invalidates a previously checked snapshot after a %s update installs a journal", async (backend) => {
+ const { kv, sdk, snapshot } = setup();
+ await persistGraphRecords(kv, [node("before")], [], { mode: "merge" });
+ const writer = new StateKV(sdk as never, { backend });
+ const clean = await snapshot(writer);
+ const added = node("added");
+ const next: GraphSnapshot = {
+ ...clean,
+ topNodes: [...clean.topNodes, added],
+ topDegrees: { ...clean.topDegrees, added: 0 },
+ stats: { ...clean.stats, totalNodes: 2, nodesByType: { concept: 2 } },
+ };
+ const pending: GraphSnapshot = {
+ ...clean, dirty: true,
+ pendingMutation: {
+ snapshot: next,
+ writes: [
+ { scope: KV.graphNodes, key: added.id, value: added },
+ { scope: KV.graphNameIndex, key: "concept|added", value: added.id },
+ { scope: KV.graphNodeDegree, key: added.id, value: 0 },
+ ],
+ },
+ };
+ await writer.update(KV.graphSnapshot, "current", [{ type: "set", path: "", value: pending }]);
+ const recovered = await snapshot(writer);
+ expect(recovered.pendingMutation).toBeUndefined();
+ expect(recovered.dirty).toBe(false);
+ expect(recovered.stats.totalNodes).toBe(2);
+ expect(await writer.get(KV.graphNodes, "added")).toMatchObject({ id: "added" });
+ });
+
+ it.each(["index", "snapshot"])("recovers a committed raw write after %s failure across restart and retry", async (failure) => {
+ const { kv, sdk, snapshot, intercept } = setup();
+ await persistGraphRecords(kv, [node("a"), node("b")], [edge("e", "a", "b")], { mode: "merge" });
+ let failed = false;
+ intercept((id, p) => {
+ const indexWrite = id === "state::set" && inScope(p.scope, KV.graphNameIndex) && p.key === "file|renamed";
+ const snapshotWrite = id === "state::set" && inScope(p.scope, KV.graphSnapshot) && p.key === "current" && !p.value?.pendingMutation;
+ if (!failed && (failure === "index" ? indexWrite : snapshotWrite)) {
+ failed = true;
+ throw new Error(`injected ${failure} failure`);
+ }
+ });
+ const changed = node("a", { name: "renamed", type: "file" });
+ await expect(persistGraphRecords(kv, [changed], [], { mode: "merge" })).rejects.toThrow(`injected ${failure} failure`);
+ expect(failed).toBe(true);
+ intercept();
+ const restarted = new StateKV(sdk as never);
+ const recovered = await snapshot(restarted);
+ expect(recovered.stats).toMatchObject({ totalNodes: 2, totalEdges: 1, nodesByType: { concept: 1, file: 1 } });
+ expect(recovered.topNodes.find((n) => n.id === "a")).toMatchObject({ name: "renamed", type: "file" });
+ expect(await restarted.get(KV.graphNameIndex, "concept|a")).toBeNull();
+ expect(await restarted.get(KV.graphNameIndex, "file|renamed")).toBe("a");
+ expect(await degrees(restarted, ["a", "b"])).toEqual({ a: 1, b: 1 });
+ await persistGraphRecords(restarted, [changed], [], { mode: "merge" });
+ expect((await snapshot(restarted)).stats).toEqual(recovered.stats);
+ expect(await degrees(restarted, ["a", "b"])).toEqual({ a: 1, b: 1 });
+ });
+
+ it("recovers pending ingestion before a subsequent extraction mutates the same record", async () => {
+ const { kv, snapshot, intercept } = setup();
+ await persistGraphRecords(kv, [node("a")], [], { mode: "merge" });
+ let failed = false;
+ intercept((id, p) => {
+ if (!failed && id === "state::set" && inScope(p.scope, KV.graphNameIndex) && p.key === "concept|renamed") {
+ failed = true; throw new Error("injected failure");
+ }
+ });
+ await expect(persistGraphRecords(kv, [node("a", { name: "renamed" })], [], { mode: "merge" })).rejects.toThrow("injected failure");
+ intercept();
+ await persistGraphDelta(kv, [node("fresh-id", { name: "renamed", sourceObservationIds: ["fresh-observation"] })], []);
+ expect((await snapshot()).stats.totalNodes).toBe(1);
+ expect((await kv.get<GraphNode>(KV.graphNodes, "a"))?.sourceObservationIds).toContain("fresh-observation");
+ expect(await kv.get(KV.graphNodes, "fresh-id")).toBeNull();
+ });
+
+ it("retries a failure beyond the first batch without losing or recounting committed rows", async () => {
+ const { kv, snapshot, intercept } = setup();
+ const nodes = Array.from({ length: 205 }, (_, i) => node(`batch-${i}`));
+ let failed = false;
+ intercept((id, p) => {
+ if (!failed && id === "state::set" && inScope(p.scope, KV.graphNameIndex) && p.key === "concept|batch-130") {
+ failed = true; throw new Error("injected later-batch failure");
+ }
+ });
+ await expect(persistGraphRecords(kv, nodes, [], { mode: "merge" })).rejects.toThrow("injected later-batch failure");
+ intercept();
+ const recovered = await snapshot();
+ expect(recovered.stats.totalNodes).toBeGreaterThanOrEqual(100);
+ expect(recovered.stats.totalNodes).toBeLessThanOrEqual(205);
+ await persistGraphRecords(kv, nodes, [], { mode: "merge" });
+ expect((await snapshot()).stats).toMatchObject({ totalNodes: 205, totalEdges: 0, nodesByType: { concept: 205 } });
+ expect((await kv.list<GraphNode>(KV.graphNodes))).toHaveLength(205);
+ expect(await kv.get(KV.graphNameIndex, "concept|batch-130")).toBe("batch-130");
+ });
+
+ it("replays absolute edge accounting after a committed row's write response is lost", async () => {
+ const { kv, snapshot, store, intercept } = setup();
+ await persistGraphRecords(kv, [node("a"), node("b")], [edge("e", "a", "b")], { mode: "merge" });
+ let failed = false;
+ intercept((id, p) => {
+ if (!failed && id === "state::set" && inScope(p.scope, KV.graphEdges) && p.key === "e") {
+ failed = true;
+ store.get(p.scope)!.set(p.key, structuredClone(p.value));
+ throw new Error("committed response lost");
+ }
+ });
+ const changed = edge("e", "a", "a", { type: "uses" });
+ await expect(persistGraphRecords(kv, [], [changed], { mode: "merge" })).rejects.toThrow("committed response lost");
+ intercept();
+ expect((await snapshot()).stats).toMatchObject({ totalNodes: 2, totalEdges: 1, edgesByType: { uses: 1 } });
+ expect(await degrees(kv, ["a", "b"])).toEqual({ a: 2, b: 0 });
+ expect(await kv.get(KV.graphEdgeKey, "a|b|related_to")).toBeNull();
+ expect(await kv.get(KV.graphEdgeKey, "a|a|uses")).toBe("e");
+ await persistGraphRecords(kv, [], [changed], { mode: "merge" });
+ expect((await snapshot()).stats.totalEdges).toBe(1);
+ expect(await degrees(kv, ["a", "b"])).toEqual({ a: 2, b: 0 });
+ });
+
+ it("replaces graph state by publishing a fresh generation without enumerating the old corpus", async () => {
+ const { kv, call, snapshot, intercept } = setup();
+ await persistGraphRecords(kv, [node("old-a"), node("old-b")], [edge("old-edge", "old-a", "old-b")], { mode: "merge" });
+ await kv.set(KV.graphEdgeHistory, "old-history", edge("old-history", "old-a", "old-b"));
+ const previous = await kv.get(KV.graphControl, "generation");
+ intercept((id, p) => {
+ if (id === "state::list" && p.scope.startsWith("mem:graph:")) throw new Error("Unbounded graph enumeration");
+ });
+ await persistGraphRecords(kv, [node("new")], [edge("loop", "new", "new")], { mode: "merge", replace: true });
+ expect(await kv.get(KV.graphControl, "generation")).not.toBe(previous);
+ expect(await kv.get(KV.graphNodes, "old-a")).toBeNull();
+ expect(await kv.get(KV.graphEdges, "old-edge")).toBeNull();
+ expect(await kv.get(KV.graphEdgeHistory, "old-history")).toBeNull();
+ expect(await kv.get(KV.graphNameIndex, "concept|old-a")).toBeNull();
+ expect(await kv.get(KV.graphNodeDegree, "old-a")).toBeNull();
+ expect((await snapshot()).stats).toMatchObject({ totalNodes: 1, totalEdges: 1 });
+ expect((await call("mem::graph-query")).nodes).toEqual([expect.objectContaining({ id: "new" })]);
+ expect(await kv.get(KV.graphNodeDegree, "new")).toBe(2);
+ await persistGraphRecords(kv, [], [], { mode: "merge", replace: true });
+ expect((await snapshot()).stats).toMatchObject({ totalNodes: 0, totalEdges: 0 });
+ expect((await snapshot()).topNodes).toEqual([]);
+ expect((await snapshot()).topEdges).toEqual([]);
+ });
+
+ it("retains the prior generation if replacement publication fails", async () => {
+ const { kv, snapshot, intercept } = setup();
+ await persistGraphRecords(kv, [node("old")], [], { mode: "merge" });
+ const previous = await kv.get(KV.graphControl, "generation");
+ intercept((id, p) => {
+ if (id === "state::set" && p.scope === KV.graphControl && p.key === "generation") throw new Error("injected publish failure");
+ });
+ await expect(persistGraphRecords(kv, [node("new")], [], { mode: "merge", replace: true })).rejects.toThrow("injected publish failure");
+ intercept();
+ expect(await kv.get(KV.graphControl, "generation")).toBe(previous);
+ expect((await snapshot()).topNodes.map((n) => n.id)).toEqual(["old"]);
+ expect(await kv.get(KV.graphNodes, "new")).toBeNull();
+ await persistGraphRecords(kv, [node("new")], [], { mode: "merge", replace: true });
+ expect((await snapshot()).topNodes.map((n) => n.id)).toEqual(["new"]);
+ });
+
+ it("cannot publish a replacement or replay old pending records over a newer reset", async () => {
+ const { kv, call, snapshot, intercept } = setup();
+ await persistGraphRecords(kv, [node("old")], [], { mode: "merge" });
+ const oldView = await pinGraphState(kv);
+ let failed = false;
+ intercept((id, p) => {
+ if (!failed && id === "state::set" && inScope(p.scope, KV.graphNameIndex) && p.key === "concept|pending") {
+ failed = true; throw new Error("injected failure");
+ }
+ });
+ await expect(persistGraphRecords(oldView, [node("pending")], [], { mode: "merge" })).rejects.toThrow("injected failure");
+ intercept();
+ await call("mem::graph-reset");
+ await persistGraphRecords(kv, [node("current")], [], { mode: "merge" });
+ const currentGeneration = await kv.get(KV.graphControl, "generation");
+ await snapshot(oldView);
+ await Promise.allSettled([persistGraphRecords(oldView, [node("late-replace")], [], { mode: "merge", replace: true })]);
+ expect(await kv.get(KV.graphControl, "generation")).toBe(currentGeneration);
+ expect((await snapshot()).topNodes.map((n) => n.id)).toEqual(["current"]);
+ expect(await kv.get(KV.graphNodes, "pending")).toBeNull();
+ expect(await kv.get(KV.graphNodes, "late-replace")).toBeNull();
+ });
+
+ it("publishes the reconciled snapshot with a registered viewer listener without lock reentrance", async () => {
+ const { kv, sdk, call, snapshot, sent } = setup();
+ registerViewerStreamTriggers(sdk as never, kv);
+ await call("mem::graph-reset");
+ await persistGraphRecords(kv, [node("a"), node("b")], [edge("e", "a", "b")], { mode: "merge" });
+ expect((await snapshot()).stats).toMatchObject({ totalNodes: 2, totalEdges: 1 });
+ expect(sent.filter((event) => event.type === "graph.changed").at(-1)?.data.stats).toMatchObject({ totalNodes: 2, totalEdges: 1 });
+ }, 5000);
+});
diff --git a/test/graph.test.ts b/test/graph.test.ts
index d3c26313..7b30e5de 100644
--- a/test/graph.test.ts
+++ b/test/graph.test.ts
@@ -5,6 +5,7 @@ vi.mock("../src/logger.js", () => ({
}));
import { registerGraphFunction } from "../src/functions/graph.js";
+import { pinGraphState } from "../src/state/graph-generation.js";
import type {
CompressedObservation,
GraphNode,
@@ -547,7 +548,7 @@ describe("Graph Functions", () => {
};
expect(result.success).toBe(true);
- const snap = await kv.get<{
+ const snap = await (await pinGraphState(kv as never)).get<{
stats: { totalNodes: number };
}>("mem:graph:snapshot", "current");
expect(snap?.stats.totalNodes).toBe(0);
@@ -564,7 +565,7 @@ describe("Graph Functions", () => {
await sdk.trigger("mem::graph-reset", {});
- const snap = await kv.get<{
+ const snap = await (await pinGraphState(kv as never)).get<{
stats: { totalNodes: number; totalEdges: number };
}>("mem:graph:snapshot", "current");
expect(snap?.stats.totalNodes).toBe(0);
diff --git a/test/keyed-mutex.test.ts b/test/keyed-mutex.test.ts
new file mode 100644
index 00000000..351f8901
--- /dev/null
+++ b/test/keyed-mutex.test.ts
@@ -0,0 +1,154 @@
+import { describe, expect, it, vi } from "vitest";
+import { afterKeyedLock, isKeyedLockHeld, withKeyedLock, withKeyedLocks } from "../src/state/keyed-mutex.js";
+
+function deferred() {
+ let resolve!: () => void;
+ const promise = new Promise<void>((done) => { resolve = done; });
+ return { promise, resolve };
+}
+
+describe("keyed mutex context", () => {
+ it("retains ancestor locks while isolating sibling asynchronous contexts", async () => {
+ const entered = deferred();
+ const release = deferred();
+ await withKeyedLock("outer", async () => {
+ const first = withKeyedLock("first", async () => {
+ entered.resolve();
+ await release.promise;
+ expect(isKeyedLockHeld("outer")).toBe(true);
+ expect(isKeyedLockHeld("first")).toBe(true);
+ expect(isKeyedLockHeld("second")).toBe(false);
+ });
+ await entered.promise;
+ expect(isKeyedLockHeld("first")).toBe(false);
+ await withKeyedLock("second", async () => {
+ expect(isKeyedLockHeld("outer")).toBe(true);
+ expect(isKeyedLockHeld("second")).toBe(true);
+ expect(isKeyedLockHeld("first")).toBe(false);
+ });
+ release.resolve();
+ await first;
+ expect(isKeyedLockHeld("outer")).toBe(true);
+ expect(isKeyedLockHeld("first")).toBe(false);
+ });
+ expect(isKeyedLockHeld("outer")).toBe(false);
+ });
+
+ it("coalesces named callbacks and releases their lock before running them", async () => {
+ const events: string[] = [];
+ await withKeyedLock("outer", async () => {
+ await withKeyedLock("inner", async () => {
+ expect(afterKeyedLock("inner", async () => { events.push("obsolete"); }, "snapshot")).toBe(true);
+ expect(afterKeyedLock("inner", async () => {
+ expect(isKeyedLockHeld("outer")).toBe(true);
+ expect(isKeyedLockHeld("inner")).toBe(false);
+ await withKeyedLock("inner", async () => { events.push("latest"); });
+ }, "snapshot")).toBe(true);
+ afterKeyedLock("inner", async () => { events.push("anonymous-first"); });
+ afterKeyedLock("inner", async () => { events.push("anonymous-second"); });
+ expect(afterKeyedLock("missing", async () => { events.push("missing"); })).toBe(false);
+ events.push("body");
+ });
+ events.push("inner-complete");
+ });
+ expect(events).toEqual(["body", "latest", "anonymous-first", "anonymous-second", "inner-complete"]);
+ });
+
+ it("releases failed work, flushes callbacks and admits the next queued task", async () => {
+ const entered = deferred();
+ const release = deferred();
+ const callback = vi.fn(async () => { expect(isKeyedLockHeld("failure")).toBe(false); });
+ const events: string[] = [];
+ const first = withKeyedLock("failure", async () => {
+ afterKeyedLock("failure", callback);
+ events.push("first");
+ entered.resolve();
+ await release.promise;
+ throw new Error("expected failure");
+ });
+ const rejected = expect(first).rejects.toThrow("expected failure");
+ await entered.promise;
+ const second = withKeyedLock("failure", async () => {
+ expect(isKeyedLockHeld("failure")).toBe(true);
+ events.push("second");
+ return 42;
+ });
+ expect(events).toEqual(["first"]);
+ release.resolve();
+ await rejected;
+ expect(await second).toBe(42);
+ expect(callback).toHaveBeenCalledOnce();
+ expect(events).toEqual(["first", "second"]);
+ });
+
+ it("runs later callbacks and preserves a single callback failure after successful work", async () => {
+ const failure = new Error("notification failed");
+ const later = vi.fn(async () => {});
+ const work = withKeyedLock("callback-failure", async () => {
+ afterKeyedLock("callback-failure", async () => { throw failure; });
+ afterKeyedLock("callback-failure", later);
+ return 42;
+ });
+ await expect(work).rejects.toBe(failure);
+ expect(later).toHaveBeenCalledOnce();
+ expect(await withKeyedLock("callback-failure", async () => 43)).toBe(43);
+ });
+
+ it("collects multiple notification failures while running every callback", async () => {
+ const first = new Error("synchronous notification failure");
+ const second = new Error("asynchronous notification failure");
+ const events: string[] = [];
+ const failure = await withKeyedLock("multiple-failures", async () => {
+ afterKeyedLock("multiple-failures", () => { events.push("first"); throw first; });
+ afterKeyedLock("multiple-failures", async () => { events.push("second"); throw second; });
+ afterKeyedLock("multiple-failures", async () => { events.push("last"); });
+ }).catch((error: unknown) => error);
+ expect(failure).toBeInstanceOf(AggregateError);
+ expect((failure as AggregateError).errors).toEqual([first, second]);
+ expect(events).toEqual(["first", "second", "last"]);
+ });
+
+ it("preserves the body error when notification callbacks also fail", async () => {
+ const bodyError = new Error("original mutation failure");
+ const first = vi.fn(async () => { throw new Error("first notification failure"); });
+ const second = vi.fn(async () => { throw new Error("second notification failure"); });
+ const last = vi.fn(async () => {});
+ const work = withKeyedLock("body-and-callback-failure", async () => {
+ afterKeyedLock("body-and-callback-failure", first);
+ afterKeyedLock("body-and-callback-failure", second);
+ afterKeyedLock("body-and-callback-failure", last);
+ throw bodyError;
+ });
+ await expect(work).rejects.toBe(bodyError);
+ for (const callback of [first, second, last]) expect(callback).toHaveBeenCalledOnce();
+ });
+
+ it("does not treat a released frame retained by background work as held", async () => {
+ const release = deferred();
+ const callback = vi.fn(async () => {});
+ let background!: Promise<{ held: boolean; queued: boolean }>;
+ await withKeyedLock("released", async () => {
+ background = release.promise.then(() => ({
+ held: isKeyedLockHeld("released"),
+ queued: afterKeyedLock("released", callback),
+ }));
+ });
+ release.resolve();
+ expect(await background).toEqual({ held: false, queued: false });
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it("acquires 10,000 import keys while preserving outer and inner lock semantics", async () => {
+ const keys = Array.from({ length: 10_000 }, (_, i) => `obs:${String(i).padStart(5, "0")}`);
+ const callback = vi.fn(async () => {
+ expect(isKeyedLockHeld(keys[0])).toBe(false);
+ expect(isKeyedLockHeld(keys.at(-1)!)).toBe(false);
+ });
+ await withKeyedLocks([...keys].reverse().concat(keys[0]), async () => {
+ for (const key of [keys[0], keys[5000], keys.at(-1)!]) expect(isKeyedLockHeld(key)).toBe(true);
+ expect(afterKeyedLock(keys[0], callback)).toBe(true);
+ });
+ expect(callback).toHaveBeenCalledOnce();
+ expect(isKeyedLockHeld(keys[0])).toBe(false);
+ });
+});
diff --git a/test/live-source-budget.test.ts b/test/live-source-budget.test.ts
index 99587013..06e0be3c 100644
--- a/test/live-source-budget.test.ts
+++ b/test/live-source-budget.test.ts
@@ -14,7 +14,7 @@ vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), err
const sessionId = "live-source-budget";
const scope = KV.observations(sessionId);
const output = "captured evidence ".repeat(1500);
-const xml = "<type>file_read</type><title>Read configuration</title><facts><fact>Port configured</fact></facts><narrative>Read the configuration file.</narrative><concepts><concept>config</concept></concepts><files></files><importance>5</importance>";
+const xml = "<observation><type>file_read</type><title>Read configuration</title><facts><fact>Port configured</fact></facts><narrative>Read the configuration file.</narrative><concepts><concept>config</concept></concepts><files></files><importance>5</importance></observation>";
function raw(id: string): RawObservation {
return { id, sessionId, timestamp: "2026-09-30T00:00:00Z", hookType: "post_tool_use", toolName: "Read", toolOutput: output, raw: {} };
diff --git a/test/multimodal.test.ts b/test/multimodal.test.ts
index 0157dad0..d07006a5 100644
--- a/test/multimodal.test.ts
+++ b/test/multimodal.test.ts
@@ -50,14 +50,14 @@ import { registerObserveFunction } from "../src/functions/observe.js";
import { registerCompressFunction } from "../src/functions/compress.js";
import type { RawObservation, CompressedObservation, MemoryProvider } from "../src/types.js";
-const VALID_COMPRESS_XML = `<type>image</type>
+const VALID_COMPRESS_XML = `<observation><type>image</type>
<title>Screenshot of Red Dot</title>
<subtitle>Test image observation</subtitle>
<facts><fact>Image shows a single red pixel on white background</fact></facts>
<narrative>A vision model described a screenshot showing a red dot on a white background</narrative>
<concepts><concept>testing</concept><concept>screenshot</concept></concepts>
<files></files>
-<importance>5</importance>`;
+<importance>5</importance></observation>`;
describe("End-to-End Multimodal Flow", () => {
let savedImagePath: string | undefined;
diff --git a/test/observation-source.test.ts b/test/observation-source.test.ts
index 5788e6d2..0ce16f27 100644
--- a/test/observation-source.test.ts
+++ b/test/observation-source.test.ts
@@ -153,7 +153,7 @@ describe("retained observation source", () => {
vi.stubEnv("AGENTMEMORY_AUTO_COMPRESS", "true");
const provider: MemoryProvider = {
name: "test", summarize: vi.fn(),
- compress: vi.fn(async () => "<type>file_read</type><title>Read configuration</title><facts><fact>Port configured</fact></facts><narrative>Read the configuration file.</narrative><concepts><concept>config</concept></concepts><files></files><importance>5</importance>"),
+ compress: vi.fn(async () => "<observation><type>file_read</type><title>Read configuration</title><facts><fact>Port configured</fact></facts><narrative>Read the configuration file.</narrative><concepts><concept>config</concept></concepts><files></files><importance>5</importance></observation>"),
};
registerCompressFunction(r.sdk as never, r.kv as never, provider);
const tail = "MODEL_SOURCE_ONLY_TAIL";
diff --git a/test/remember-lock-scope.test.ts b/test/remember-lock-scope.test.ts
index 750ec55f..0d2f5c49 100644
--- a/test/remember-lock-scope.test.ts
+++ b/test/remember-lock-scope.test.ts
@@ -6,6 +6,8 @@ vi.mock("../src/logger.js", () => ({
import { registerRememberFunction } from "../src/functions/remember.js";
import {
+ getSearchIndex,
+ indexRecords,
setVectorIndex,
setEmbeddingProvider,
setIndexPersistence,
@@ -191,6 +193,46 @@ describe("mem::remember lock scope", () => {
}
});
+ it("does not overwrite a newer imported body while its commit reread is pending", async () => {
+ getSearchIndex().clear();
+ const sdk = mockSdk();
+ const kv = mockKV();
+ let captured!: Memory;
+ let release!: () => void;
+ let entered!: () => void;
+ const reading = new Promise<void>((resolve) => { entered = resolve; });
+ const blocked = new Promise<void>((resolve) => { release = resolve; });
+ registerRememberFunction(sdk as never, {
+ ...kv,
+ set: async <T>(scope: string, key: string, value: T) => {
+ if (scope === KV.memories) captured = value as Memory;
+ return kv.set(scope, key, value);
+ },
+ get: async <T>(scope: string, key: string): Promise<T | null> => {
+ if (scope === KV.memories && key === captured?.id) {
+ entered();
+ await blocked;
+ }
+ return kv.get<T>(scope, key);
+ },
+ } as never);
+ setEmbeddingProvider({
+ name: "race-test", dimensions: 3,
+ embed: async () => new Float32Array([1, 0, 0]),
+ embedBatch: async (texts) => texts.map(() => new Float32Array([0, 1, 0])),
+ });
+ const saving = sdk.trigger({ function_id: "mem::remember", payload: { content: "original body before import" } });
+ await reading;
+ const replacement = { ...captured, title: "newimportmarker", content: "newimportmarker" };
+ await kv.set(KV.memories, replacement.id, replacement);
+ await indexRecords([], [replacement]);
+ release();
+ await saving;
+ expect(vectorIndex.get(replacement.id)?.embedding).toEqual(new Float32Array([0, 1, 0]));
+ expect(getSearchIndex().search("newimportmarker").map((hit) => hit.obsId)).toEqual([replacement.id]);
+ getSearchIndex().clear();
+ });
+
it("logs a vector-index commit failure distinctly from an embed failure", async () => {
const failingCommit = vi.fn(async () => {
throw new Error("kv unavailable");
diff --git a/test/search-index-write-race.test.ts b/test/search-index-write-race.test.ts
new file mode 100644
index 00000000..d234da44
--- /dev/null
+++ b/test/search-index-write-race.test.ts
@@ -0,0 +1,213 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { SearchIndex } from "../src/state/search-index.js";
+import { VectorIndex } from "../src/state/vector-index.js";
+import { KV } from "../src/state/schema.js";
+import {
+ backfillVectorBacklog, getPendingVectorBackfillCount, getSearchIndex,
+ indexRecords, rebuildKeywordIndex, setEmbeddingProvider, setIndexPersistence,
+ setPendingVectorBackfillCount, setVectorIndex, vectorIndexAddBatchGuarded,
+ vectorIndexAddGuarded, vectorIndexRemove,
+} from "../src/functions/search.js";
+import type { VectorBackfillJob } from "../src/functions/search.js";
+import type { CompressedObservation } from "../src/types.js";
+
+vi.mock("../src/logger.js", () => ({ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } }));
+
+function deferred<T>() {
+ let resolve!: (value: T) => void;
+ let reject!: (reason: unknown) => void;
+ const promise = new Promise<T>((yes, no) => { resolve = yes; reject = no; });
+ return { promise, resolve, reject };
+}
+const oldVector = () => new Float32Array([1, 0]);
+const newVector = () => new Float32Array([0, 1]);
+const observation = (id: string, text = id): CompressedObservation => ({
+ id, sessionId: "session", type: "discovery", title: text, narrative: text,
+ timestamp: "2026-10-12T12:00:00.000Z", facts: [], concepts: [], files: [], importance: 5,
+});
+const context = (id: string) => ({ kind: "observation" as const, logId: id });
+const job = (id: string): VectorBackfillJob => ({ id, sessionId: "session", text: id, context: context(id) });
+const provider = () => ({
+ name: "test", dimensions: 2,
+ embed: vi.fn(async (_text: string) => newVector()),
+ embedBatch: vi.fn(async (texts: string[]) => texts.map(() => newVector())),
+});
+
+let vectors: VectorIndex;
+let embedding: ReturnType<typeof provider>;
+beforeEach(() => {
+ getSearchIndex().clear();
+ vectors = new VectorIndex();
+ embedding = provider();
+ setVectorIndex(vectors);
+ setEmbeddingProvider(embedding);
+ setIndexPersistence(null);
+ setPendingVectorBackfillCount(0);
+});
+afterEach(() => {
+ vi.unstubAllEnvs();
+ getSearchIndex().clear();
+ setVectorIndex(null);
+ setEmbeddingProvider(null);
+ setIndexPersistence(null);
+ setPendingVectorBackfillCount(0);
+});
+
+describe("search indexing async write ownership", () => {
+ it("keeps newer keywords/vectors and deletion while accepting unaffected rows from the same old batch", async () => {
+ const entered = deferred<void>();
+ const pending = deferred<Float32Array[]>();
+ embedding.embedBatch.mockImplementationOnce(async () => { entered.resolve(); return pending.promise; });
+ const old = indexRecords([
+ observation("same", "antiquarium"), observation("unaffected", "moonstone"), observation("deleted", "obsoletezebra"),
+ ], []);
+ expect(getSearchIndex().has("unaffected")).toBe(true);
+ await entered.promise;
+ await indexRecords([observation("same", "xylophone")], []);
+ getSearchIndex().remove("deleted");
+ vectorIndexRemove("deleted");
+ pending.resolve([oldVector(), oldVector(), oldVector()]);
+ await old;
+ expect([...vectors.get("same")!.embedding]).toEqual([0, 1]);
+ expect([...vectors.get("unaffected")!.embedding]).toEqual([1, 0]);
+ expect(vectors.has("deleted")).toBe(false);
+ expect(getSearchIndex().has("deleted")).toBe(false);
+ expect(getSearchIndex().search("xylophone").map((r) => r.obsId)).toEqual(["same"]);
+ expect(getSearchIndex().search("antiquarium")).toEqual([]);
+ });
+
+ it("captures queued record revisions before an earlier vector batch awaits", async () => {
+ vi.stubEnv("REBUILD_EMBED_BATCH_SIZE", "1");
+ const entered = deferred<void>();
+ const pending = deferred<Float32Array[]>();
+ embedding.embedBatch.mockImplementationOnce(async () => { entered.resolve(); return pending.promise; });
+ const indexing = indexRecords([observation("first"), observation("queued", "antiquarium")], []);
+ await entered.promise;
+ getSearchIndex().add(observation("queued", "xylophone"));
+ vectors.add("queued", "session", newVector());
+ pending.resolve([oldVector()]);
+ await indexing;
+ expect(embedding.embedBatch).toHaveBeenCalledTimes(1);
+ expect([...vectors.get("queued")!.embedding]).toEqual([0, 1]);
+ expect(getSearchIndex().search("antiquarium")).toEqual([]);
+ });
+
+ it("does not cancel an absent-ID vector write when another ID is removed", async () => {
+ const pending = deferred<Float32Array>();
+ embedding.embed.mockReturnValueOnce(pending.promise);
+ const adding = vectorIndexAddGuarded("absent", "session", "new text", context("absent"));
+ getSearchIndex().remove("unrelated");
+ vectorIndexRemove("also-unrelated");
+ pending.resolve(oldVector());
+ expect(await adding).toBe(true);
+ expect([...vectors.get("absent")!.embedding]).toEqual([1, 0]);
+ });
+
+ it("rejects an absent-ID completion after delete/add/delete returns the ID to absence", async () => {
+ const pending = deferred<Float32Array>();
+ embedding.embed.mockReturnValueOnce(pending.promise);
+ const adding = vectorIndexAddGuarded("absent", "session", "old text", context("absent"));
+ getSearchIndex().remove("absent");
+ getSearchIndex().add(observation("absent", "new text"));
+ getSearchIndex().remove("absent");
+ pending.resolve(oldVector());
+ expect(await adding).toBe(false);
+ expect(vectors.has("absent")).toBe(false);
+ expect(await vectorIndexAddGuarded("absent", "session", "deliberate new add", context("absent"))).toBe(true);
+ });
+
+ it.each(["clear", "restore", "provider", "vector"] as const)("rejects batch completion after %s replacement", async (change) => {
+ getSearchIndex().add(observation("doc"));
+ const pending = deferred<Float32Array[]>();
+ embedding.embedBatch.mockReturnValueOnce(pending.promise);
+ const adding = vectorIndexAddBatchGuarded([job("doc")]);
+ let replacement: VectorIndex | undefined;
+ if (change === "clear") getSearchIndex().clear();
+ if (change === "restore") {
+ const restored = new SearchIndex(); restored.add(observation("doc"));
+ getSearchIndex().restoreFrom(restored);
+ }
+ if (change === "provider") setEmbeddingProvider(provider());
+ if (change === "vector") { replacement = new VectorIndex(); setVectorIndex(replacement); }
+ pending.resolve([oldVector()]);
+ expect(await adding).toEqual({ ok: 0, fail: 0, skipped: 1 });
+ expect(vectors.has("doc")).toBe(false);
+ expect(replacement?.has("doc") ?? false).toBe(false);
+ });
+
+ it("skips outdated jobs returned by keyword rebuild without submitting them to the provider", async () => {
+ const rows = [observation("changed"), observation("deleted")];
+ const kv = {
+ list: async (scope: string) => scope === KV.sessions ? [{ id: "session" }]
+ : scope === KV.observations("session") ? rows : [],
+ };
+ const rebuilt = await rebuildKeywordIndex(kv as never, "2020-01-01T00:00:00.000Z");
+ expect(rebuilt.vectorJobs).toHaveLength(2);
+ getSearchIndex().add(observation("changed", "newer"));
+ getSearchIndex().remove("deleted");
+ const result = await backfillVectorBacklog(rebuilt.vectorJobs, { pauseMs: 0 });
+ expect(result).toEqual({ added: 0, failed: 0, remaining: 0, complete: true });
+ expect(getPendingVectorBackfillCount()).toBe(0);
+ expect(embedding.embedBatch).not.toHaveBeenCalled();
+ });
+
+ it("completes an entirely superseded in-flight backlog even when its provider rejects", async () => {
+ getSearchIndex().add(observation("a")); getSearchIndex().add(observation("b"));
+ const pending = deferred<Float32Array[]>();
+ const entered = deferred<void>();
+ embedding.embedBatch.mockImplementationOnce(async () => { entered.resolve(); return pending.promise; });
+ const jobs = [job("a"), job("b")].map((j) => ({ ...j, revision: getSearchIndex().watchRevision(j.id) }));
+ const backlog = backfillVectorBacklog(jobs, { pauseMs: 0 });
+ await entered.promise;
+ getSearchIndex().remove("a"); getSearchIndex().add(observation("b", "newer"));
+ pending.reject(new Error("provider offline"));
+ expect(await backlog).toEqual({ added: 0, failed: 0, remaining: 0, complete: true });
+ expect(getPendingVectorBackfillCount()).toBe(0);
+ expect(vectors.size).toBe(0);
+ jobs.forEach((j) => j.revision.release());
+ });
+
+ it("keeps only current failed jobs pending when an in-flight batch is partly superseded", async () => {
+ getSearchIndex().add(observation("a")); getSearchIndex().add(observation("b"));
+ const pending = deferred<Float32Array[]>();
+ const entered = deferred<void>();
+ embedding.embedBatch.mockImplementationOnce(async () => { entered.resolve(); return pending.promise; });
+ const jobs = [job("a"), job("b")].map((j) => ({ ...j, revision: getSearchIndex().watchRevision(j.id) }));
+ const backlog = backfillVectorBacklog(jobs, { pauseMs: 0 });
+ await entered.promise;
+ getSearchIndex().remove("a");
+ pending.reject(new Error("provider offline"));
+ expect(await backlog).toEqual({ added: 0, failed: 1, remaining: 1, complete: false });
+ expect(getPendingVectorBackfillCount()).toBe(1);
+ expect(await backfillVectorBacklog(jobs, { pauseMs: 0 })).toEqual({ added: 1, failed: 0, remaining: 0, complete: true });
+ expect(vectors.has("a")).toBe(false); expect(vectors.has("b")).toBe(true);
+ jobs.forEach((j) => j.revision.release());
+ });
+
+ it("allows a custom commit callback to reject ownership lost during its own await", async () => {
+ getSearchIndex().add(observation("doc"));
+ const entered = deferred<void>();
+ const resume = deferred<void>();
+ const adding = vectorIndexAddGuarded("doc", "session", "old", context("doc"), async (value, isCurrent) => {
+ entered.resolve(); await resume.promise;
+ if (!isCurrent()) return false;
+ vectors.add("doc", "session", value); return true;
+ });
+ await entered.promise;
+ getSearchIndex().add(observation("doc", "newer"));
+ vectors.add("doc", "session", oldVector());
+ resume.resolve();
+ expect(await adding).toBe(false);
+ expect([...vectors.get("doc")!.embedding]).toEqual([1, 0]);
+ });
+
+ it.each(["provider", "callback"] as const)("can retry an absent ID after %s failure", async (failure) => {
+ if (failure === "provider") embedding.embed.mockRejectedValueOnce(new Error("provider offline"));
+ const failed = await vectorIndexAddGuarded("absent", "session", "text", context("absent"), failure === "callback"
+ ? async () => { throw new Error("callback failed"); } : undefined);
+ expect(failed).toBe(false);
+ expect(vectors.has("absent")).toBe(false);
+ expect(await vectorIndexAddGuarded("absent", "session", "retry", context("absent"))).toBe(true);
+ expect([...vectors.get("absent")!.embedding]).toEqual([0, 1]);
+ });
+});
diff --git a/test/snapshot.test.ts b/test/snapshot.test.ts
index 70969cfa..f6b74ac6 100644
--- a/test/snapshot.test.ts
+++ b/test/snapshot.test.ts
@@ -1,5 +1,7 @@
import { describe, it, expect, beforeEach, vi } from "vitest";
+const snapshotContent = vi.hoisted(() => vi.fn(() => '{"version":"0.4.0","sessions":[],"memories":[]}'));
+
vi.mock("../src/logger.js", () => ({
logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
}));
@@ -19,7 +21,7 @@ vi.mock("node:util", async () => {
>;
return {
...actual,
- promisify: () => async () => ({ stdout: "abc1234\n", stderr: "" }),
+ promisify: () => async (_file: string, args: string[]) => ({ stdout: args[0] === "show" ? snapshotContent() : "abc1234\n", stderr: "" }),
};
});
@@ -27,12 +29,8 @@ vi.mock("node:fs", () => ({
existsSync: vi.fn().mockReturnValue(true),
mkdirSync: vi.fn(),
writeFileSync: vi.fn(),
- readFileSync: vi
- .fn()
- .mockReturnValue('{"version":"0.4.0","sessions":[],"memories":[]}'),
}));
-import { readFileSync } from "node:fs";
import { registerSnapshotFunction } from "../src/functions/snapshot.js";
import { currentAuditScope } from "./helpers/mocks.js";
import { getProjectSessionIndex } from "../src/state/session-index.js";
@@ -169,7 +167,7 @@ describe("Snapshot Functions", () => {
status: "completed",
observationCount: 0,
};
- vi.mocked(readFileSync).mockReturnValueOnce(
+ snapshotContent.mockReturnValueOnce(
JSON.stringify({
version: "0.4.0",
sessions: [restoredSession],
@@ -267,7 +265,7 @@ describe("snapshot-restore bounds graph provenance", () => {
const sdk = mockSdk();
const kv = mockKV();
registerSnapshotFunction(sdk as never, kv as never, "/tmp/agentmemory-snapshots");
- vi.mocked(readFileSync).mockReturnValueOnce(
+ snapshotContent.mockReturnValueOnce(
JSON.stringify({
version: "0.4.0",
sessions: [],
diff --git a/test/viewer-counts-reset.test.ts b/test/viewer-counts-reset.test.ts
new file mode 100644
index 00000000..64d7f1df
--- /dev/null
+++ b/test/viewer-counts-reset.test.ts
@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { StateKV } from "../src/state/kv.js";
+import {
+ getViewerCounts, invalidateViewerCounts, noteGraphStats,
+ resetViewerCounts, setViewerCountsEmitter,
+} from "../src/state/viewer-counts.js";
+
+const stats = (totalNodes: number) => ({ totalNodes, totalEdges: 0, nodesByType: {}, edgesByType: {} });
+
+function deferred() {
+ let resolve!: () => void;
+ const promise = new Promise<void>((r) => { resolve = r; });
+ return { promise, resolve };
+}
+
+afterEach(() => { resetViewerCounts(); vi.useRealTimers(); });
+
+describe("viewer count invalidation", () => {
+ it("reloads reset counts and preserves the live emitter", async () => {
+ vi.useFakeTimers();
+ let total = 2;
+ const kv = { list: async () => [], get: async () => ({ stats: stats(total) }) } as unknown as StateKV;
+ const emit = vi.fn();
+ setViewerCountsEmitter(emit);
+ expect((await getViewerCounts(kv)).graphNodes).toBe(2);
+ total = 0;
+ invalidateViewerCounts();
+ expect((await getViewerCounts(kv)).graphNodes).toBe(0);
+ noteGraphStats(stats(1));
+ await vi.advanceTimersByTimeAsync(500);
+ expect(emit).toHaveBeenLastCalledWith(expect.objectContaining({ graphNodes: 1 }));
+ });
+
+ it("does not retain stale counts when invalidated during both load attempts", async () => {
+ const entered = [deferred(), deferred()];
+ const release = [deferred(), deferred()];
+ let reads = 0;
+ let total = 2;
+ const kv = {
+ list: async () => [],
+ get: async () => {
+ const result = { stats: stats(total) };
+ const index = reads++;
+ if (index < 2) { entered[index].resolve(); await release[index].promise; }
+ return result;
+ },
+ } as unknown as StateKV;
+ const pending = getViewerCounts(kv);
+ await entered[0].promise;
+ total = 1;
+ invalidateViewerCounts();
+ release[0].resolve();
+ await entered[1].promise;
+ total = 0;
+ invalidateViewerCounts();
+ release[1].resolve();
+ await pending;
+ expect((await getViewerCounts(kv)).graphNodes).toBe(0);
+ expect(reads).toBe(3);
+ });
+});
diff --git a/test/viewer-generation-deltas.test.ts b/test/viewer-generation-deltas.test.ts
new file mode 100644
index 00000000..834d2099
--- /dev/null
+++ b/test/viewer-generation-deltas.test.ts
@@ -0,0 +1,231 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { StateKV } from "../src/state/kv.js";
+import { KV } from "../src/state/schema.js";
+import { resetGraphGeneration, setGraphGenerationListener } from "../src/state/graph-generation.js";
+import { registerViewerStreamTriggers } from "../src/triggers/viewer-streams.js";
+import { getViewerCounts, resetViewerCounts } from "../src/state/viewer-counts.js";
+import { setAuditRecordedListener } from "../src/functions/audit.js";
+import type { GraphNode, GraphSnapshot } from "../src/types.js";
+
+function snapshot(count: number): GraphSnapshot {
+ const topNodes: GraphNode[] = Array.from({ length: count }, (_, i) => ({
+ id: `n${i}`, type: "concept", name: `node ${i}`, properties: {},
+ sourceObservationIds: [], createdAt: "2026-10-12T12:00:00.000Z",
+ }));
+ return {
+ version: 1, topNodes, topEdges: [], topDegrees: Object.fromEntries(topNodes.map((n) => [n.id, 0])),
+ stats: { totalNodes: count, totalEdges: 0, nodesByType: { concept: count }, edgesByType: {} },
+ updatedAt: "2026-10-12T12:00:00.000Z", dirty: false,
+ };
+}
+
+async function setup() {
+ const store = new Map<string, Map<string, unknown>>();
+ const handlers = new Map<string, (data: any) => Promise<any>>();
+ const sent: Array<{ type: string; data: { delta: any; stats: any; generation?: string; reset?: boolean } }> = [];
+ let failSend = false;
+ const sdk = {
+ registerFunction: vi.fn((id: string, handler: (data: any) => Promise<any>) => handlers.set(id, handler)), registerTrigger: vi.fn(),
+ trigger: async ({ function_id, payload: p }: { function_id: string; payload: any }): Promise<any> => {
+ if (function_id === "stream::send") {
+ if (failSend) { failSend = false; throw new Error("stream unavailable"); }
+ sent.push(structuredClone(p)); return {};
+ }
+ const rows = store.get(p.scope) ?? new Map<string, unknown>();
+ if (function_id === "state::get") return structuredClone(rows.get(p.key) ?? null);
+ if (function_id === "state::list") return structuredClone([...rows.values()]);
+ if (function_id === "state::set") {
+ rows.set(p.key, structuredClone(p.value)); store.set(p.scope, rows); return p.value;
+ }
+ if (function_id === "state::delete") { rows.delete(p.key); return; }
+ throw new Error(`Unexpected call ${function_id}`);
+ },
+ };
+ const kv = new StateKV(sdk as never);
+ await resetGraphGeneration(kv, snapshot(0));
+ registerViewerStreamTriggers(sdk as never, kv);
+ const write = (value: GraphSnapshot) => kv.set(KV.graphSnapshot, "current", value);
+ const graphEvents = () => sent.filter((e) => e.type === "graph.changed");
+ return { kv, sdk, write, graphEvents, handlers, sent, failNextSend: () => { failSend = true; } };
+}
+
+afterEach(() => {
+ vi.restoreAllMocks();
+ vi.useRealTimers();
+ setGraphGenerationListener(null);
+ setAuditRecordedListener(null);
+ resetViewerCounts();
+});
+
+describe("generation graph viewer deltas", () => {
+ it("sends a bounded single-node patch for a 250-node graph after its initial invalidation", async () => {
+ const { write, graphEvents } = await setup();
+ const initial = snapshot(250);
+ await write(initial);
+ expect(graphEvents()[0].data.delta).toBeNull();
+ const changed = structuredClone(initial);
+ changed.topNodes[125].properties = { changed: true };
+ await write(changed);
+ expect(graphEvents()[1].data.delta).toEqual({
+ full: false, nodes: [changed.topNodes[125]], edges: [],
+ removedNodeIds: [], removedEdgeIds: [], degrees: {},
+ });
+ changed.topNodes.splice(10, 1);
+ delete changed.topDegrees.n10;
+ changed.stats.totalNodes--;
+ await write(changed);
+ expect(graphEvents()[2].data.delta).toMatchObject({ full: false, nodes: [], removedNodeIds: ["n10"] });
+ });
+
+ it("starts with a complete baseline after listener restart, then uses incremental patches", async () => {
+ const { kv, sdk, write, graphEvents } = await setup();
+ await write(snapshot(2));
+ await write(snapshot(3));
+ expect(graphEvents()[1].data.delta).toMatchObject({ full: false, nodes: [{ id: "n2" }] });
+ registerViewerStreamTriggers(sdk as never, kv);
+ await write(snapshot(4));
+ expect(graphEvents()[2].data.delta).toMatchObject({ full: true, nodes: snapshot(4).topNodes });
+ await write(snapshot(5));
+ expect(graphEvents()[3].data.delta).toMatchObject({ full: false, nodes: [{ id: "n4" }] });
+ });
+
+ it("does not advance its baseline when a stream send fails", async () => {
+ const { write, graphEvents, failNextSend } = await setup();
+ await write(snapshot(2));
+ failNextSend();
+ await write(snapshot(3));
+ expect(graphEvents()).toHaveLength(1);
+ await write(snapshot(4));
+ expect(graphEvents()[1].data.delta).toMatchObject({ full: false, nodes: [{ id: "n2" }, { id: "n3" }] });
+ });
+
+ it("invalidates the baseline across repeated same-timestamp resets, including a failed reset notification", async () => {
+ const { kv, write, graphEvents, failNextSend } = await setup();
+ await write(snapshot(2));
+ for (const lostReset of [false, true, false]) {
+ if (lostReset) failNextSend();
+ const before = graphEvents().length;
+ await resetGraphGeneration(kv, snapshot(0));
+ if (!lostReset) expect(graphEvents()[before].data.delta).toMatchObject({ full: true, nodes: [] });
+ await write(snapshot(1));
+ const latest = graphEvents().at(-1)!.data.delta;
+ expect(latest).toMatchObject({ full: lostReset, nodes: [{ id: "n0" }] });
+ expect(graphEvents().at(-1)!.data.reset).toBe(lostReset);
+ expect(graphEvents().at(-1)!.data.generation).toBe(await kv.get(KV.graphControl, "generation"));
+ await write(snapshot(2));
+ expect(graphEvents().at(-1)!.data.delta).toMatchObject({ full: false, nodes: [{ id: "n1" }] });
+ }
+ });
+
+ it("keeps the last delivered baseline after a snapshot read failure", async () => {
+ const { kv, write, graphEvents } = await setup();
+ await write(snapshot(2));
+ const original = kv.get.bind(kv);
+ let failRead = true;
+ vi.spyOn(kv, "get").mockImplementation(async (scope, key) => {
+ if (scope === KV.graphSnapshot && failRead) { failRead = false; throw new Error("read failed"); }
+ return original(scope, key);
+ });
+ await write(snapshot(3));
+ expect(graphEvents()).toHaveLength(2);
+ expect(graphEvents()[1].data).toMatchObject({ source: "items", coveredBySnapshot: false });
+ await write(snapshot(4));
+ expect(graphEvents()[2].data.delta).toMatchObject({ full: false, nodes: [{ id: "n2" }, { id: "n3" }] });
+ });
+
+ it("refreshes cached counts even if reading the reset snapshot fails", async () => {
+ const { kv, write, graphEvents } = await setup();
+ await write(snapshot(20));
+ expect((await getViewerCounts(kv)).graphNodes).toBe(20);
+ const original = kv.get.bind(kv);
+ let failRead = true;
+ vi.spyOn(kv, "get").mockImplementation(async (scope, key) => {
+ if (scope === KV.graphSnapshot && failRead) { failRead = false; throw new Error("read failed"); }
+ return original(scope, key);
+ });
+ await resetGraphGeneration(kv, snapshot(0));
+ expect((await getViewerCounts(kv)).graphNodes).toBe(0);
+ expect(graphEvents().at(-1)!.data).toMatchObject({ source: "items", reset: true, coveredBySnapshot: false });
+ expect(graphEvents().at(-1)!.data).not.toHaveProperty("generation");
+ });
+
+ it("still pushes counts immediately after a successful reset", async () => {
+ vi.useFakeTimers();
+ const { kv, write, sent } = await setup();
+ await write(snapshot(20));
+ await getViewerCounts(kv);
+ await resetGraphGeneration(kv, snapshot(0));
+ await vi.advanceTimersByTimeAsync(500);
+ expect(sent.filter((e) => e.type === "counts.changed").at(-1)?.data).toMatchObject({ counts: { graphNodes: 0 } });
+ });
+
+ it("does not mark coalesced item events covered by a failed snapshot send", async () => {
+ vi.useFakeTimers();
+ const { kv, write, graphEvents, failNextSend } = await setup();
+ await write(snapshot(2));
+ await kv.set(KV.graphNodes, "n2", snapshot(3).topNodes[2]);
+ failNextSend();
+ await write(snapshot(3));
+ await vi.advanceTimersByTimeAsync(1000);
+ expect(graphEvents().at(-1)?.data).toMatchObject({ source: "items", coveredBySnapshot: false });
+ });
+
+ it("tags the reconnect snapshot with its generation", async () => {
+ const { kv, write, handlers } = await setup();
+ await write(snapshot(2));
+ const response = await handlers.get("api::viewer-snapshot")!({ headers: {}, query_params: {} });
+ expect(response.body.graph).toMatchObject({
+ generation: await kv.get(KV.graphControl, "generation"), stats: { totalNodes: 2 },
+ });
+ });
+
+ it("orders queued snapshot deltas from the last delivered graph", async () => {
+ const { kv, write, graphEvents } = await setup();
+ await write(snapshot(250));
+ const original = kv.get.bind(kv);
+ let entered!: () => void;
+ let release!: () => void;
+ const ready = new Promise<void>((r) => { entered = r; });
+ const gate = new Promise<void>((r) => { release = r; });
+ let pause = true;
+ vi.spyOn(kv, "get").mockImplementation(async (scope, key) => {
+ const value = await original(scope, key);
+ if (scope === KV.graphSnapshot && pause) { pause = false; entered(); await gate; }
+ return value;
+ });
+ const first = write(snapshot(251));
+ await ready;
+ const second = write(snapshot(252));
+ release();
+ await Promise.all([first, second]);
+ expect(graphEvents()[1].data.delta).toMatchObject({ full: false, nodes: [{ id: "n250" }] });
+ expect(graphEvents()[2].data.delta).toMatchObject({ full: false, nodes: [{ id: "n251" }] });
+ });
+
+ it("does not associate a pre-reset snapshot with the new generation when reads overlap reset", async () => {
+ const { kv, write, graphEvents } = await setup();
+ await write(snapshot(250));
+ const original = kv.get.bind(kv);
+ let entered!: () => void;
+ let release!: () => void;
+ const ready = new Promise<void>((r) => { entered = r; });
+ const gate = new Promise<void>((r) => { release = r; });
+ let pause = true;
+ vi.spyOn(kv, "get").mockImplementation(async (scope, key) => {
+ const value = await original(scope, key);
+ if (scope === KV.graphSnapshot && pause) { pause = false; entered(); await gate; }
+ return value;
+ });
+ const writeBeforeReset = write(snapshot(251));
+ await ready;
+ const oldGeneration = await original(KV.graphControl, "generation");
+ const reset = resetGraphGeneration(kv, snapshot(0));
+ // Wait for publication, while its notification remains queued behind the old read.
+ await vi.waitFor(async () => expect(await original(KV.graphControl, "generation")).not.toBe(oldGeneration));
+ release();
+ await Promise.all([writeBeforeReset, reset]);
+ for (const event of graphEvents().slice(1)) {
+ expect(event.data).toMatchObject({ reset: true, stats: { totalNodes: 0 }, delta: { full: true, nodes: [] } });
+ }
+ });
+});
diff --git a/test/viewer-graph-reset.test.ts b/test/viewer-graph-reset.test.ts
new file mode 100644
index 00000000..84e74cad
--- /dev/null
+++ b/test/viewer-graph-reset.test.ts
@@ -0,0 +1,223 @@
+import { readFileSync } from "node:fs";
+import { runInNewContext } from "node:vm";
+import ts from "typescript";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const viewer = readFileSync("src/viewer/index.html", "utf8");
+const script = viewer.match(/<script[^>]*>([\s\S]*?)<\/script>/)![1];
+const parsed = ts.createSourceFile("viewer.js", script, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+const names = ["clearGraphView", "noteGraphGeneration", "setGraphData", "mergeGraphRows", "loadGraph", "applyGraphDelta", "handleGraphChange", "scheduleGraphReload", "fetchGraphDetail", "searchGraphRemote", "loadSnapshot", "applySnapshot"];
+const functions = parsed.statements.filter((s) => ts.isFunctionDeclaration(s) && names.includes(s.name!.text)).map((s) => s.getText(parsed)).join("\n");
+const oldNode = { id: "old", type: "concept", name: "Old graph evidence" };
+const fullEmpty = { full: true, nodes: [], edges: [], degrees: {} };
+
+function deferred<T = any>() {
+ let resolve!: (value: T) => void;
+ const promise = new Promise<T>((r) => { resolve = r; });
+ return { promise, resolve };
+}
+
+function rig() {
+ const graph = {
+ loaded: true, loading: false, dirty: false, generation: "before", requestSeq: 0, searchRequestSeq: 0, resetSeq: 0,
+ nodeMap: { old: oldNode } as Record<string, unknown>, edgeMap: {}, degrees: { old: 2 }, fresh: { old: 1 },
+ selectedId: "old" as string | null, detail: { id: "old", data: { node: oldNode } } as any,
+ totalNodes: 1, totalEdges: 0, rev: 0, patches: 0, fetches: 0, search: "", searchOpen: false,
+ };
+ const api = vi.fn();
+ const apiPost = vi.fn();
+ const route = vi.fn();
+ const context = {
+ state: { graph, activeTab: "graph" }, api, apiGet: api, apiPost, setRouteEntity: route,
+ store: { graph: { stats: { totalNodes: 1, totalEdges: 0 } } },
+ GRAPH_LIMIT: 500, graphReloadTimer: null, graphSim: { canvas: null, hoverId: "old", drag: {} },
+ setTimeout, clearTimeout, document: { getElementById: () => null },
+ renderGraphView: vi.fn(), renderGraphDetail: vi.fn(), renderGraphOverview: vi.fn(),
+ syncGraphSim: vi.fn(), requestGraphDraw: vi.fn(), centerGraphOn: vi.fn(), selectGraphNode: vi.fn(),
+ graphSearchMatches: () => [],
+ renderFlagsChip: vi.fn(), renderFlagsPanel: vi.fn(), updateCountBadges: vi.fn(), updateFooter: vi.fn(),
+ markDirty: vi.fn(), renderTab: vi.fn(), tabRendered: { graph: true },
+ };
+ const f = runInNewContext(`${functions}\n({${names.join(",")}})`, context);
+ return { ...f, graph, api, apiPost, route, context };
+}
+
+function reset(r: ReturnType<typeof rig>, delta: unknown = fullEmpty) {
+ r.handleGraphChange({ source: "snapshot", reset: true, generation: "after", delta });
+}
+
+beforeEach(() => vi.useFakeTimers());
+afterEach(() => vi.useRealTimers());
+
+describe("viewer graph reset boundaries", () => {
+ it("clears a selected node, details, degrees and route on an empty full reset", () => {
+ const r = rig();
+ reset(r);
+ expect(r.graph).toMatchObject({ selectedId: null, detail: null, nodeMap: {}, edgeMap: {}, degrees: {}, fresh: {}, loaded: true });
+ expect(r.route).toHaveBeenCalledWith("graph", "");
+ expect(r.context.graphSim).toMatchObject({ hoverId: null, drag: null });
+ });
+
+ it.each([true, false])("ignores a pre-reset graph query (previously loaded: %s)", async (loaded) => {
+ const r = rig();
+ r.graph.loaded = loaded;
+ const response = deferred();
+ r.apiPost.mockReturnValueOnce(response.promise);
+ const pending = r.loadGraph();
+ reset(r);
+ response.resolve({ nodes: [oldNode], edges: [] });
+ await pending;
+ expect(r.graph.nodeMap).toEqual({});
+ expect(r.graph).toMatchObject({ selectedId: null, loading: false, loaded: true });
+ });
+
+ it("ignores an old detail response even when the same id is requested again", async () => {
+ const r = rig();
+ const before = deferred();
+ const after = deferred();
+ r.api.mockReturnValueOnce(before.promise).mockReturnValueOnce(after.promise);
+ const first = r.fetchGraphDetail("old");
+ reset(r);
+ const second = r.fetchGraphDetail("old");
+ before.resolve({ node: oldNode, relations: [] });
+ await first;
+ expect(r.graph.nodeMap).toEqual({});
+ expect(r.graph.detail.loading).toBe(true);
+ after.resolve({ error: "Node not found" });
+ await second;
+ expect(r.graph.nodeMap).toEqual({});
+ expect(r.graph.detail.error).toBe("Node not found");
+ });
+
+ it("ignores a delayed remote search and its automatic selection after reset", async () => {
+ const r = rig();
+ const response = deferred();
+ r.apiPost.mockReturnValueOnce(response.promise);
+ const pending = r.searchGraphRemote("Old graph");
+ reset(r);
+ response.resolve({ nodes: [oldNode], edges: [] });
+ await pending;
+ expect(r.graph.nodeMap).toEqual({});
+ expect(r.graph.searchOpen).toBe(false);
+ expect(r.context.selectGraphNode).not.toHaveBeenCalled();
+ });
+
+ it("ignores the stats fallback of a failed query when reset occurs during that second request", async () => {
+ const r = rig();
+ const stats = deferred();
+ const entered = deferred();
+ r.apiPost.mockResolvedValueOnce(null);
+ r.api.mockImplementationOnce(() => { entered.resolve(undefined); return stats.promise; });
+ const pending = r.loadGraph();
+ await entered.promise;
+ expect(r.api).toHaveBeenCalled();
+ reset(r);
+ stats.resolve({ error: "Old error", flag: "old" });
+ await pending;
+ expect(r.graph).toMatchObject({ queryError: null, disabledInfo: null, loaded: true });
+ });
+
+ it("clears a prior generation on reconnect and handles explicit same-generation resets", () => {
+ const r = rig();
+ r.noteGraphGeneration({ generation: "after" });
+ expect(r.graph).toMatchObject({ selectedId: null, detail: null, nodeMap: {}, generation: "after" });
+ r.graph.nodeMap.old = oldNode;
+ r.graph.selectedId = "old";
+ reset(r);
+ expect(r.graph).toMatchObject({ selectedId: null, nodeMap: {} });
+ });
+
+ it("discards a viewer snapshot captured before a reset without reverting generation or counts", async () => {
+ const r = rig();
+ const snapshot = deferred();
+ r.api.mockReturnValueOnce(snapshot.promise);
+ const pending = r.loadSnapshot();
+ reset(r);
+ snapshot.resolve({ graph: { generation: "before", stats: { totalNodes: 1 } }, counts: { graphNodes: 1 } });
+ expect(await pending).toBe(false);
+ expect(r.graph).toMatchObject({ generation: "after", nodeMap: {}, selectedId: null });
+ });
+
+ it("retries a reset-invalidated snapshot once to recover startup metadata", async () => {
+ const r = rig();
+ const snapshot = deferred();
+ r.api.mockReturnValueOnce(snapshot.promise).mockResolvedValueOnce({
+ graph: { generation: "after", stats: { totalNodes: 0 } },
+ provider: "fixture-provider", flags: [{ name: "fixture-flag" }], version: "fixture-version",
+ });
+ const pending = r.loadSnapshot();
+ reset(r);
+ snapshot.resolve({ graph: { generation: "before" }, provider: "obsolete" });
+ expect(await pending).toBe(true);
+ expect(r.api).toHaveBeenCalledTimes(2);
+ expect(r.context.store).toMatchObject({ provider: "fixture-provider", version: "fixture-version", flags: [{ name: "fixture-flag" }] });
+ expect(r.graph.generation).toBe("after");
+ });
+
+ it("stops retrying when another reset invalidates the second snapshot", async () => {
+ const r = rig();
+ const first = deferred();
+ const second = deferred();
+ const entered = deferred();
+ r.api.mockReturnValueOnce(first.promise).mockImplementationOnce(() => { entered.resolve(undefined); return second.promise; });
+ const pending = r.loadSnapshot();
+ reset(r);
+ first.resolve({ graph: { generation: "before" } });
+ await entered.promise;
+ reset(r);
+ second.resolve({ graph: { generation: "after" } });
+ expect(await pending).toBe(false);
+ expect(r.api).toHaveBeenCalledTimes(2);
+ });
+
+ it.each(["query", "full delta"])("keeps the initial snapshot valid after an ordinary empty %s", async (kind) => {
+ const r = rig();
+ Object.assign(r.graph, { nodeMap: {}, selectedId: null, detail: null, loaded: false, generation: undefined });
+ const snapshot = deferred();
+ r.api.mockReturnValueOnce(snapshot.promise);
+ const pending = r.loadSnapshot();
+ if (kind === "query") r.setGraphData({ nodes: [], edges: [], totalNodes: 0 });
+ else r.applyGraphDelta(fullEmpty);
+ expect(r.graph.resetSeq).toBe(0);
+ snapshot.resolve({ graph: { generation: "current" }, provider: "fixture-provider" });
+ expect(await pending).toBe(true);
+ expect(r.api).toHaveBeenCalledTimes(1);
+ expect(r.context.store).toMatchObject({ provider: "fixture-provider" });
+ });
+
+ it("invalidates old queries and selection even when the reset delta requires a reload", () => {
+ const r = rig();
+ reset(r, null);
+ expect(r.graph).toMatchObject({ selectedId: null, detail: null, nodeMap: {}, loaded: false, dirty: true });
+ expect(r.graph.requestSeq).toBeGreaterThan(0);
+ });
+
+ it("drops old snapshot totals when a reset could only send an item invalidation", () => {
+ const r = rig();
+ r.handleGraphChange({ source: "items", reset: true, coveredBySnapshot: false });
+ expect(r.context.store.graph).toBeNull();
+ expect(r.graph).toMatchObject({ selectedId: null, detail: null, nodeMap: {}, dirty: true, totalNodes: 0 });
+ });
+
+ it("preserves selected nodes outside an ordinary snapshot's top-node window", () => {
+ const r = rig();
+ const detail = r.graph.detail;
+ r.handleGraphChange({ source: "snapshot", generation: "before", delta: { full: true, nodes: [{ id: "top", type: "concept", name: "Top node" }], edges: [] } });
+ expect(r.graph.nodeMap.old).toEqual(oldNode);
+ expect(r.graph.selectedId).toBe("old");
+ expect(r.graph.detail).toBe(detail);
+ expect(r.graph.requestSeq).toBe(0);
+ });
+
+ it("clears stale selected data when a reload returns an empty graph without a reset event", async () => {
+ const r = rig();
+ const detail = deferred();
+ r.api.mockReturnValueOnce(detail.promise);
+ const pending = r.fetchGraphDetail("old");
+ r.apiPost.mockResolvedValueOnce({ nodes: [], edges: [], totalNodes: 0, totalEdges: 0 });
+ await r.loadGraph();
+ detail.resolve({ node: oldNode });
+ await pending;
+ expect(r.graph).toMatchObject({ selectedId: null, detail: null, nodeMap: {}, loaded: true });
+ });
+});