Skip to content

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

feat(cursor): workspace adapter on top of the marketplace plugin (#1112)

Andrew Wang22dc07ce3498
diff --git a/.gitignore b/.gitignore
index 3686577b..22064b38 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,8 +10,8 @@ dist/
.DS_Store
.claude/
-plugin/scripts/*.map
-plugin/scripts/*.d.mts
+plugin/scripts/**/*.map
+plugin/scripts/**/*.d.mts
data/
!eval/data/
!eval/data/**
diff --git a/AGENTS.md b/AGENTS.md
index 1da74983..628dbcd0 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` (3,900+ 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` (4,000+ 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
- 324+ iii functions
-- 3,900+ tests
+- 4,000+ tests
diff --git a/README.md b/README.md
index e0e4235d..6a880f69 100644
--- a/README.md
+++ b/README.md
@@ -72,7 +72,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="3,900+ 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="4,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -704,6 +704,19 @@ copilot plugin install rohitg00/agentmemory:plugin
`agentmemory connect copilot-cli` merges `mcpServers.agentmemory` into `~/.copilot/mcp-config.json` (or `$COPILOT_HOME/mcp-config.json` when `COPILOT_HOME` is set) and preserves existing servers. On native Windows this is the only automated `connect` adapter; configure every other native Windows agent manually. WSL `connect` is supported only when the target agent is installed in that same WSL environment. Copilot picks up the MCP server on next launch or after `/mcp`. Install the plugin as well when you want the full hook/skill experience.
+### Cursor
+
+```bash
+# MCP wiring
+agentmemory connect cursor
+```
+
+Then add the native hooks: **Settings → Plugins → Add marketplace** → select an agentmemory checkout (the directory containing `.cursor-plugin/plugin.json`), enable the **agentmemory** plugin, and reload the window.
+
+Cursor runs the same lifecycle hooks as every other host — they are the canonical `plugin/scripts/*.mjs`, not a separate implementation. A thin adapter in front of them resolves which project a session belongs to, which Cursor does not reliably report: its payload `cwd` can be `.cursor`, the Cursor install directory, or missing entirely. Do not also wire hooks into `~/.cursor/hooks.json` — the plugin already dispatches them, and both copies firing records every observation twice.
+
+Full guide: [`integrations/cursor/`](integrations/cursor/)
+
### OpenClaw
Start the installed AgentMemory server in a separate terminal, then install its native plugin and skills:
@@ -775,7 +788,7 @@ The agentmemory entry is the **same MCP server block** across every host that us
| Agent | Config file | Notes |
|---|---|---|
| **Cursor (MCP only)** | `~/.cursor/mcp.json` | Merge into `mcpServers`, or `agentmemory connect cursor`. One-click deeplink also available on the website. |
-| **Cursor (full plugin)** | `.cursor-plugin/` | Cursor Marketplace listing (submission in review) or Cursor Settings → Plugins → local checkout. Registers 7 auto-capture hooks (sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + 17 skills + the MCP server, with `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET` managed in Cursor's plugin dashboard. Works in the Cursor IDE and `cursor-agent` CLI; CLI print-mode prompts are backfilled from the session transcript at session end. |
+| **Cursor (full plugin)** | `.cursor-plugin/` | Cursor Marketplace listing or Settings → Plugins → local checkout. Registers lifecycle hooks via a thin adapter that delegates to the canonical `plugin/scripts/*.mjs`, plus skills and MCP. The adapter resolves the workspace Cursor does not reliably report. See [Cursor](#cursor). Works in the Cursor IDE and `cursor-agent` CLI. |
| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | Merge into `mcpServers`. Restart Claude Desktop after editing. |
| **Cline / Roo Code / Kilo Code** | Cline MCP settings (Settings UI → MCP Servers → Edit) | Same `mcpServers` block. |
| **Devin CLI (MCP + hooks)** | `~/.config/devin/config.json` | `agentmemory connect devin` merges the MCP entry; `--with-hooks` adds six native auto-capture hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) with Devin'"'"'s lowercase tool matchers. Verify with `devin mcp list` and `/hooks` inside devin. |
@@ -1436,7 +1449,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Custom plugin systems | `iii worker add <name>` |
-**245 source files · ~55,000 LOC · 3,400+ tests · 324 functions · 67 KV scopes**, all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.
+**250 source files · ~55,000 LOC · 3,400+ tests · 324 functions · 67 KV scopes**, all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.
---
@@ -1868,7 +1881,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 # 3,900+ tests
+npm test # 4,000+ 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 4b163e87..e9746827 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="3,900+ 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="4,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1439,8 +1439,7 @@ fi
| Prometheus / Grafana | OTEL في iii + مراقب الحالة الصحية |
| أنظمة إضافات مخصصة | `iii worker add <name>` |
-**245 ملف مصدري · ~55,000 سطر برمجي · 3,900+ اختبار · 324 دالة · 67 نطاق KV**، كل ذلك على ثلاث بنى أساسية. لا يوجد أمر `agentmemory plugin install`. نظام الإضافات هو iii نفسه.
-
+**250 ملف مصدري · ~55,000 سطر برمجي · 3,800+ اختبار · 324 دالة · 67 نطاق KV**، كل ذلك على ثلاث بنى أساسية. لا يوجد أمر `agentmemory plugin install`. نظام الإضافات هو iii نفسه.
---
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
@@ -1863,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 # 3,900+ tests
+npm test # 4,000+ 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 6ec95b3b..46c3647c 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="3,900+ টেস্ট পাস" 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="4,000+ টেস্ট পাস" height="38" /></picture>
</p>
<p align="center">
@@ -1437,7 +1437,7 @@ fi
| Prometheus / Grafana | iii OTEL + হেলথ মনিটর |
| কাস্টম প্লাগইন সিস্টেম | `iii worker add <name>` |
-**245 সোর্স ফাইল · ~55,000 LOC · 3,400+ টেস্ট · 324 ফাংশন · 67 KV স্কোপ**, সবকিছু তিনটি প্রিমিটিভের উপর। কোনো `agentmemory plugin install` নেই। প্লাগইন সিস্টেমটাই iii নিজে।
+**250 সোর্স ফাইল · ~55,000 LOC · 3,400+ টেস্ট · 324 ফাংশন · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 e9af2090..175a13d8 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="3,900+ 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="4,000+ 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>` |
-**245 zdrojových souborů · ~55,000 řádků kódu · 3,400+ testů · 324 funkcí · 67 KV scopes**, vše na třech primitivech. Žádné `agentmemory plugin install`. Systém pluginů je samo iii.
+**250 zdrojových souborů · ~55,000 řádků kódu · 3,400+ testů · 324 funkcí · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 be54a36e..8ab557d4 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="3,900+ 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="4,000+ 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>` |
-**245 kildefiler · ~55,000 LOC · 3,400+ tests · 324 funktioner · 67 KV-scopes**, alt på tre primitiver. Intet `agentmemory plugin install`. Plugin-systemet er iii selv.
+**250 kildefiler · ~55,000 LOC · 3,400+ tests · 324 funktioner · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 98642031..25b708aa 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="3,900+ 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="4,000+ 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>` |
-**245 Quelldateien · ~55,000 LOC · 3,400+ Tests · 324 Funktionen · 67 KV-Scopes**, alles auf drei Primitiven. Kein `agentmemory plugin install`. Das Plugin-System ist iii selbst.
+**250 Quelldateien · ~55,000 LOC · 3,400+ Tests · 324 Funktionen · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 f04db0b3..c9becaf8 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="3,900+ επιτυχημένες δοκιμές" 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="4,000+ επιτυχημένες δοκιμές" height="38" /></picture>
</p>
<p align="center">
@@ -1438,7 +1438,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor υγείας |
| Προσαρμοσμένα συστήματα plugin | `iii worker add <name>` |
-**245 αρχεία πηγαίου κώδικα · ~55,000 LOC · 3,400+ δοκιμές · 324 functions · 67 KV scopes**, όλα πάνω σε τρία primitives. Δεν υπάρχει `agentmemory plugin install`. Το σύστημα plugin είναι το ίδιο το iii.
+**250 αρχεία πηγαίου κώδικα · ~55,000 LOC · 3,400+ δοκιμές · 324 functions · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 53af017f..08cc2ae6 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="3,900+ 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="4,000+ 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>` |
-**245 ficheros de código · ~55,000 LOC · 3,400+ tests · 324 funciones · 67 scopes KV**, todo sobre tres primitivos. No hay `agentmemory plugin install`. El sistema de plugins es iii mismo.
+**250 ficheros de código · ~55,000 LOC · 3,400+ tests · 324 funciones · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 a7ef38d2..58abd565 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="3,900+ 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="4,000+ 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>` |
-**245 lähdetiedostoa · ~55,000 LOC · 3,400+ testiä · 324 funktiota · 67 KV-scopea**, kaikki kolmen primitiivin päällä. Ei `agentmemory plugin install` -komentoa. Plugin-järjestelmä on iii itse.
+**250 lähdetiedostoa · ~55,000 LOC · 3,400+ testiä · 324 funktiota · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 df970a0e..711daaa5 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="3,900+ 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="4,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1448,8 +1448,7 @@ fi
| Prometheus / Grafana | iii OTEL + moniteur de santé |
| Systèmes de plugins custom | `iii worker add <name>` |
-**245 fichiers sources · ~55,000 LOC · 3,900+ tests · 324 fonctions · 67 scopes KV**, tout sur trois primitives. Pas de `agentmemory plugin install`. Le système de plugins, c'est iii lui-même.
-
+**250 fichiers sources · ~55,000 LOC · 3,800+ tests · 324 fonctions · 67 scopes KV**, tout sur trois primitives. Pas de `agentmemory plugin install`. Le système de plugins, c'est iii lui-même.
---
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configuration" height="32" /></picture></h2>
@@ -1872,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 # 3,900+ tests
+npm test # 4,000+ 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 b0e4a194..5f0eb016 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="3,900+ בדיקות עוברות" 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="4,000+ בדיקות עוברות" height="38" /></picture>
</p>
<p align="center">
@@ -1439,7 +1439,7 @@ fi
| Prometheus / Grafana | iii OTEL + מוניטור health |
| מערכות plugin מותאמות אישית | `iii worker add <name>` |
-**245 קבצי מקור · ~55,000 LOC · 3,400+ בדיקות · 324 פונקציות · 67 תחומי KV**, הכול על שלושה primitives. אין `agentmemory plugin install`. מערכת ה-plugin היא iii עצמו.
+**250 קבצי מקור · ~55,000 LOC · 3,400+ בדיקות · 324 פונקציות · 67 תחומי 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 # 3,900+ tests
+npm test # 4,000+ 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 cc8e9c8c..3eafb2cc 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="3,900+ 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="4,000+ 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>` |
-**245 source files · ~55,000 LOC · 3,400+ tests · 324 functions · 67 KV scopes**, सब कुछ तीन primitives पर। कोई `agentmemory plugin install` नहीं। Plugin system iii स्वयं है।
+**250 source files · ~55,000 LOC · 3,400+ tests · 324 functions · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 d7af5504..b23825ca 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="3,900+ 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="4,000+ 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>` |
-**245 forrásfájl · ~55,000 LOC · 3,400+ teszt · 324 funkció · 67 KV-hatókör**, mindez három primitíven. Nincs `agentmemory plugin install`. A plugin-rendszer maga az iii.
+**250 forrásfájl · ~55,000 LOC · 3,400+ teszt · 324 funkció · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 32d9f9fc..35ced774 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="3,900+ 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="4,000+ pengujian lolos" height="38" /></picture>
</p>
<p align="center">
@@ -1447,8 +1447,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| Sistem plugin custom | `iii worker add <name>` |
-**245 file sumber · ~55,000 LOC · 3,900+ pengujian · 324 fungsi · 67 scope KV**, semua di atas tiga primitif. Tidak ada `agentmemory plugin install`. Sistem plugin-nya adalah iii itu sendiri.
-
+**250 file sumber · ~55,000 LOC · 3,800+ pengujian · 324 fungsi · 67 scope KV**, semua di atas tiga primitif. Tidak ada `agentmemory plugin install`. Sistem plugin-nya adalah iii itu sendiri.
---
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Konfigurasi" height="32" /></picture></h2>
@@ -1871,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 # 3,900+ tests
+npm test # 4,000+ 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 1b7e9468..799fd216 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="3,900+ 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="4,000+ 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>` |
-**245 file sorgente · ~55,000 righe di codice · 3,400+ test · 324 funzioni · 67 scope KV**, tutto su tre primitive. Nessun `agentmemory plugin install`. Il sistema di plugin è iii stesso.
+**250 file sorgente · ~55,000 righe di codice · 3,400+ test · 324 funzioni · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 1b0719ad..364e9471 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="3,900+ 件のテストが成功" 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="4,000+ 件のテストが成功" height="38" /></picture>
</p>
<p align="center">
@@ -1445,7 +1445,7 @@ fi
| Prometheus / Grafana | iii OTEL + ヘルスモニタ |
| カスタムプラグインシステム | `iii worker add <name>` |
-**245 ソースファイル · ~55,000 LOC · 3,400+ テスト · 324 functions · 67 KV スコープ** — すべて 3 つのプリミティブの上に。`agentmemory plugin install` はありません。プラグインシステムは iii そのものです。
+**250 ソースファイル · ~55,000 LOC · 3,400+ テスト · 324 functions · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 f966c451..6fd0d7a8 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="3,900+ 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="4,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + health 모니터 |
| 커스텀 플러그인 시스템 | `iii worker add <name>` |
-**소스 파일 245개 · LOC ~55,000줄 · 테스트 3,400+개 · 함수 324개 · KV 스코프 67개**, 모두 세 가지 프리미티브 위에서 동작합니다. `agentmemory plugin install` 같은 것은 없습니다. 플러그인 시스템은 곧 iii 자체입니다.
+**소스 파일 250개 · LOC ~55,000줄 · 테스트 3,400+개 · 함수 324개 · KV 스코프 67개**, 모두 세 가지 프리미티브 위에서 동작합니다. `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 # 3,900+ tests
+npm test # 4,000+ 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 e533e6ac..47bb607b 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="3,900+ 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="4,000+ 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>` |
-**245 kildefiler · ~55,000 LOC · 3,400+ tester · 324 funksjoner · 67 KV-scopes**, alt på tre primitiver. Ingen `agentmemory plugin install`. Plugin-systemet er iii selv.
+**250 kildefiler · ~55,000 LOC · 3,400+ tester · 324 funksjoner · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 65ea946e..01d49d34 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="3,900+ 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="4,000+ 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>` |
-**245 bronbestanden · ~55,000 LOC · 3,400+ tests · 324 functies · 67 KV-scopes**, allemaal op drie primitieven. Geen `agentmemory plugin install`. Het pluginsysteem is iii zelf.
+**250 bronbestanden · ~55,000 LOC · 3,400+ tests · 324 functies · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 5833c7b6..7fcee111 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="3,900+ 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="4,000+ zaliczonych testów" height="38" /></picture>
</p>
<p align="center">
@@ -1446,8 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor stanu |
| Niestandardowe systemy pluginów | `iii worker add <name>` |
-**245 pliki źródłowe · ~55,000 LOC · 3,900+ testów · 324 funkcje · 67 zakresów KV**, wszystko na trzech prymitywach. Nie ma `agentmemory plugin install`. Systemem pluginów jest sam iii.
-
+**250 pliki źródłowe · ~55,000 LOC · 3,800+ testów · 324 funkcje · 67 zakresów KV**, wszystko na trzech prymitywach. Nie ma `agentmemory plugin install`. Systemem pluginów jest sam iii.
---
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Konfiguracja" height="32" /></picture></h2>
@@ -1870,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 # 3,900+ tests
+npm test # 4,000+ 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 67e3f661..e5ce727c 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="3,900+ 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="4,000+ 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>` |
-**245 arquivos de código · ~55,000 LOC · 3,400+ testes · 324 funções · 67 escopos KV**, tudo em cima de três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
+**250 arquivos de código · ~55,000 LOC · 3,400+ testes · 324 funções · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 8b5c15ff..6634ebc0 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="3,900+ 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="4,000+ 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>` |
-**245 ficheiros de código-fonte · ~55,000 LOC · 3,400+ testes · 324 funções · 67 âmbitos de KV**, tudo sobre três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.
+**250 ficheiros de código-fonte · ~55,000 LOC · 3,400+ testes · 324 funções · 67 â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 # 3,900+ tests
+npm test # 4,000+ 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 7e3c8f08..339247ed 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="3,900+ 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="4,000+ teste trecute" height="38" /></picture>
</p>
<p align="center">
@@ -1430,8 +1430,7 @@ fi
| Prometheus / Grafana | iii OTEL + monitor de sănătate |
| Sisteme de plugin-uri personalizate | `iii worker add <name>` |
-**245 de fișiere sursă · ~55,000 LOC · 3,900+ de teste · 324 de funcții · 67 de domenii KV**, toate pe trei primitive. Niciun `agentmemory plugin install`. Sistemul de plugin-uri este chiar iii.
-
+**250 de fișiere sursă · ~55,000 LOC · 3,800+ de teste · 324 de funcții · 67 de domenii KV**, toate pe trei primitive. Niciun `agentmemory plugin install`. Sistemul de plugin-uri este chiar iii.
---
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="Configurare" height="32" /></picture></h2>
@@ -1854,7 +1853,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 # 3,900+ tests
+npm test # 4,000+ 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 50a7576d..b9bc6e2f 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="3,900+ 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="4,000+ tests passing" height="38" /></picture>
</p>
<p align="center">
@@ -1446,7 +1446,7 @@ fi
| Prometheus / Grafana | iii OTEL + монитор состояния |
| Самописные плагинные системы | `iii worker add <name>` |
-**245 исходных файлов · ~55,000 LOC · 3,400+ тестов · 324 функций · 67 KV-scope**, всё на трёх примитивах. Никакого `agentmemory plugin install`. Плагинная система — это сам iii.
+**250 исходных файлов · ~55,000 LOC · 3,400+ тестов · 324 функций · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 51697d8a..d29d37ee 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="3,900+ 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="4,000+ 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>` |
-**245 källkodsfiler · ~55,000 LOC · 3,400+ tester · 324 funktioner · 67 KV-scopes**, allt på tre primitiv. Inget `agentmemory plugin install`. Pluginsystemet är iii självt.
+**250 källkodsfiler · ~55,000 LOC · 3,400+ tester · 324 funktioner · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 55f9adcb..aaf0d548 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="ผ่านการทดสอบ 3,900+ รายการ" 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="ผ่านการทดสอบ 4,000+ รายการ" 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>` |
-**245 source file · ~55,000 LOC · 3,400+ การทดสอบ · 324 function · 67 KV scope** ทั้งหมดอยู่บน primitive สามตัว ไม่มี `agentmemory plugin install` ระบบ plugin ก็คือ iii เองนั่นแหละ
+**250 source file · ~55,000 LOC · 3,400+ การทดสอบ · 324 function · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 a21d2cc0..11d569cc 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="3,900+ 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="4,000+ 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>` |
-**245 na source file · ~55,000 LOC · 3,400+ na test · 324 na function · 67 na KV scope**, lahat sa tatlong primitive. Walang `agentmemory plugin install`. Ang plugin system mismo ay ang iii.
+**250 na source file · ~55,000 LOC · 3,400+ na test · 324 na function · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 d18d31c8..85be7b66 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="3,900+ 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="4,000+ 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>` |
-**245 kaynak dosya · ~55,000 LOC · 3,400+ test · 324 fonksiyon · 67 KV scope**, hepsi üç primitif üzerinde. `agentmemory plugin install` yok. Eklenti sistemi, iii'nin kendisidir.
+**250 kaynak dosya · ~55,000 LOC · 3,400+ test · 324 fonksiyon · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 75c48db3..629eed37 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="3,900+ тестів пройдено" 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="4,000+ тестів пройдено" height="38" /></picture>
</p>
<p align="center">
@@ -1447,7 +1447,7 @@ fi
| Prometheus / Grafana | iii OTEL + монітор стану здоров'я |
| Власні системи плагінів | `iii worker add <name>` |
-**245 вихідних файлів · ~55,000 LOC · 3,400+ тестів · 324 функцій · 67 KV-скоупів**, усе на трьох примітивах. Жодного `agentmemory plugin install`. Система плагінів — це сам iii.
+**250 вихідних файлів · ~55,000 LOC · 3,400+ тестів · 324 функцій · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 97b35da9..5697899e 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="3,900+ ٹیسٹس پاس ہو رہے ہیں" 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="4,000+ ٹیسٹس پاس ہو رہے ہیں" height="38" /></picture>
</p>
<p align="center">
@@ -1432,8 +1432,7 @@ fi
| Prometheus / Grafana | iii OTEL + health monitor |
| کسٹم plugin سسٹمز | `iii worker add <name>` |
-**245 سورس فائلز · ~55,000 لائنز کوڈ · 3,900+ ٹیسٹس · 324 فنکشنز · 67 KV اسکوپس**، سب تین primitives پر۔ کوئی `agentmemory plugin install` نہیں۔ plugin سسٹم خود iii ہی ہے۔
-
+**250 سورس فائلز · ~55,000 لائنز کوڈ · 3,800+ ٹیسٹس · 324 فنکشنز · 67 KV اسکوپس**، سب تین primitives پر۔ کوئی `agentmemory plugin install` نہیں۔ plugin سسٹم خود iii ہی ہے۔
---
<h2 id="configuration"><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/section-config.svg"><img src="../assets/tags/section-config.svg" alt="کنفیگریشن" height="32" /></picture></h2>
@@ -1854,7 +1853,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 # 3,900+ tests
+npm test # 4,000+ 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 05c487f0..96ded8ee 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="3,900+ 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="4,000+ 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>` |
-**245 file source · ~55,000 LOC · 3,400+ test · 324 function · 67 KV scope**, tất cả trên ba primitive. Không có `agentmemory plugin install`. Hệ thống plugin chính là iii.
+**250 file source · ~55,000 LOC · 3,400+ test · 324 function · 67 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 # 3,900+ tests
+npm test # 4,000+ 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 fb52992d..720a935f 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="3,900+ 项测试通过" 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="4,000+ 项测试通过" height="38" /></picture>
</p>
<p align="center">
@@ -1444,7 +1444,7 @@ fi
| Prometheus / Grafana | iii OTEL + 健康监控 |
| Custom plugin systems | `iii worker add <name>` |
-**245 个源文件 · ~55,000 行代码 · 3,400+ 个测试 · 324 个函数 · 67 个 KV 作用域**,全部基于三种原语。没有 `agentmemory plugin install`。插件系统就是 iii 本身。
+**250 个源文件 · ~55,000 行代码 · 3,400+ 个测试 · 324 个函数 · 67 个 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 # 3,900+ tests
+npm test # 4,000+ 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 a464d275..39a1c3c4 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="3,900+ 測試通過" 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="4,000+ 測試通過" height="38" /></picture>
</p>
<p align="center">
@@ -1430,7 +1430,7 @@ fi
| Prometheus / Grafana | iii OTEL + 健康監控 |
| 自訂外掛系統 | `iii worker add <name>` |
-**245 個原始檔 · ~55,000 行程式碼 · 3,400+ 測試 · 324 個函式 · 67 個 KV 範圍**,全部基於三種原語。沒有 `agentmemory plugin install`。外掛系統就是 iii 本身。
+**250 個原始檔 · ~55,000 行程式碼 · 3,400+ 測試 · 324 個函式 · 67 個 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 # 3,900+ tests
+npm test # 4,000+ 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 7c9502e5..915e1bab 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: 3900+">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 48" fill="none" role="img" aria-label="TESTS PASSING: 4000+">
<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">3900+</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">4000+</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 fbf53032..99b68053 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: 3900+">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 48" fill="none" role="img" aria-label="TESTS PASSING: 4000+">
<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">3900+</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">4000+</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/integrations/cursor/README.md b/integrations/cursor/README.md
new file mode 100644
index 00000000..96ad35a7
--- /dev/null
+++ b/integrations/cursor/README.md
@@ -0,0 +1,337 @@
+# agentmemory for Cursor
+
+Cursor-native plugin: **lifecycle hooks**, **MCP**, and shared **skills**.
+
+The hooks are the canonical ones. `plugin/scripts/*.mjs` — compiled from
+`src/hooks/*.ts` and shared with Claude Code, Codex and Copilot — do all the
+work. Cursor gets a thin adapter in front of them, compiled from
+`src/hooks/cursor/*.ts` through the same tsdown pipeline, and nothing else.
+
+---
+
+## Quick local install
+
+Set `AGENTMEMORY_URL` in the environment or `~/.agentmemory/.env`. Loopback
+connections discover the local daemon secret automatically. For a remote daemon,
+use HTTPS and set `AGENTMEMORY_SECRET` in the runtime environment.
+`AGENTMEMORY_CREDENTIAL_MODE=explicit` disables local credential discovery.
+
+```bash
+npm run build
+node integrations/cursor/install-local.mjs
+node integrations/cursor/verify-flow.mjs
+```
+
+Then in Cursor:
+
+1. **Settings → Plugins → Add marketplace** → select the **repo root**
+ `<path-to-your-agentmemory-clone>`
+ (must contain `.cursor-plugin/plugin.json`)
+2. Enable plugin **agentmemory**
+3. **Disable** any second agentmemory marketplace entry if both are on
+4. **Developer: Reload Window**
+5. Confirm the hooks log shows `plugin/scripts/cursor/run-hook.mjs` or `run-detached.mjs`
+
+Only after plugin hooks are confirmed, remove the old agentmemory entries from
+`~/.cursor/hooks.json` (only recognized AgentMemory script commands are removed, and a backup is written):
+
+```bash
+node integrations/cursor/install-local.mjs --clear-user-hooks
+```
+
+---
+
+## Layout
+
+```text
+agentmemory/ ← Cursor plugin root (git repo)
+ .cursor-plugin/plugin.json ← marketplace manifest (hooks + MCP + skills)
+ plugin/
+ cursor/hooks.json ← Cursor camelCase events → adapter
+ cursor/mcp.json
+ scripts/cursor/ ← built from src/hooks/cursor/
+ run-hook.mjs ← the synchronous hooks
+ run-detached.mjs ← stop / sessionEnd
+ scripts/*.mjs ← canonical hooks, shared with every agent
+ skills/
+ src/hooks/cursor/ ← the only Cursor-specific source
+ run-hook.ts, run-detached.ts ← CLI entrypoints
+ delegate.ts ← event -> canonical hook dispatch
+ workspace.ts ← resolveWorkspace()
+ cursor-db.ts ← reads Cursor's own SQLite storage
+integrations/cursor/
+ install-local.mjs ← local marketplace + MCP wiring
+ verify-flow.mjs ← live smoke test against a daemon
+ close-stale-am-sessions.mjs ← dev utility
+ _env.mjs ← shared config loading
+```
+
+`workspace.ts` and `delegate.ts` are not build entrypoints; they are inlined
+into each CLI, so the emitted files are self-contained exactly like every
+other hook artifact.
+
+---
+
+## What a hook call actually does
+
+```text
+Cursor
+ │ reads plugin/cursor/hooks.json, spawns a process, writes JSON to stdin
+ ▼
+run-hook.mjs <event> run-detached.mjs stop|sessionEnd
+ │ │ writes the payload to a temp file,
+ │ │ spawns a detached worker, returns
+ │ ▼
+ │ (background worker)
+ ▼
+resolveWorkspace(payload) ──► { project, cwd }
+ │
+ │ AGENTMEMORY_PROJECT_NAME=<project> in the environment
+ │ cwd=<cwd> merged into the payload
+ ▼
+node plugin/scripts/<canonical hook>.mjs ← unmodified
+ │
+ ▼
+POST $AGENTMEMORY_URL/agentmemory/...
+```
+
+`resolveProject()` in the canonical hooks reads `AGENTMEMORY_PROJECT_NAME`
+before falling back to git or cwd. That one environment variable is the whole
+delegation mechanism — it is how Cursor-specific knowledge reaches a hook that
+knows nothing about Cursor.
+
+### Differences from the Claude Code hooks
+
+| | Claude Code | Cursor |
+|---|---|---|
+| Event names | `PostToolUse` | `postToolUse` |
+| Config shape | `[{hooks:[{type,command}]}]` | `[{command}]` |
+| Plugin root var | `${CLAUDE_PLUGIN_ROOT}` | `${CURSOR_PLUGIN_ROOT}` |
+| `preToolUse` matcher | `Edit\|Write\|Read\|Glob\|Grep` | …`\|Shell` (Cursor has a Shell tool) |
+| Session id field | `session_id` | `session_id`, `sessionId` or `conversation_id` |
+| Working directory | reliable | **not reliable — see below** |
+
+The extra process hop costs about 100ms per synchronous hook (one additional
+Node startup plus resolution). The canonical hooks already spend ~500ms of
+their own deliberately, waiting for their fire-and-forget POST to leave, so
+this is roughly a 20% overhead on something the user does not wait for. It
+buys zero duplicated hook logic, which was the explicit trade.
+
+### Why `stop` and `sessionEnd` are detached
+
+`sessionEnd` sends the canonical session-end request and optionally syncs the
+Claude bridge. Summarization and consolidation are managed by the daemon.
+The detached worker lets the hook finish submitting those requests after its
+parent exits; delivery still depends on the daemon and operating system.
+
+`run-detached.mjs` runs the same file twice in two roles. The parent reads
+stdin, writes the payload to a `0600` temp file, spawns itself with
+`detached: true`, `stdio: 'ignore'` and `AM_HOOK_WORKER=1`, then exits as soon
+as the spawn is confirmed. The worker reads the file back, deletes it, and
+delegates normally under a watchdog.
+
+* Temp file, not a pipe, because `stdio: 'ignore'` is what keeps the parent
+ from being held open by the child.
+* `detached` puts the worker in its own process group, out of reach of
+ Cursor's teardown.
+* `unref()` stops the parent's event loop waiting on it.
+
+Measured: the parent returns in **99ms** where an inline `stop` would hold
+Cursor for about **1500ms**.
+
+The eight synchronous hooks stay inline: they are fast, and some need to write
+to stdout for Cursor to read (`sessionStart` can inject project context).
+
+---
+
+## Why there is a workspace resolver at all
+
+Every hook has to answer one question: **which project is this?** For Claude
+Code that is 20 lines — read `cwd`, run `git rev-parse --show-toplevel`, take
+the basename.
+
+Cursor does not give hooks a trustworthy working directory. In practice the
+payload contains one of:
+
+* `.cursor` — Cursor's own metadata directory, not the project;
+* the **Cursor install directory**, leaked through `VSCODE_CWD`, which resolves
+ to a project literally named `cursor`;
+* nothing at all, just a `tool_input` holding a *file* path;
+* a session id, with the workspace recorded somewhere else entirely.
+
+Getting this wrong is not a crash. It silently files a user's memories under
+the wrong project, or under `.cursor`, and nobody notices until the data is
+already there. That is why the resolver is the largest piece of this
+integration, and why every layer either verifies its answer against the
+filesystem or refuses to answer.
+
+### The chain
+
+Layers are tried in order. `resolveWorkspace` caches the workspace under the
+session id. Later hooks validate the entry and use the shared project resolver,
+so linked worktrees and `AGENTMEMORY_PROJECT_NAME` follow the same rules as
+other agents.
+
+| # | Layer | Basis | Notes |
+|---|---|---|---|
+| 1 | Session cache | previous answer | `~/.cursor/hooks/.agentmemory-session-cache.json`, written under a lock; entries expire after 7 days (max 200) and are ignored once their directory is gone |
+| 2 | Payload paths | `workspace_roots`, `workspace_folder`, `cwd`, … | eight aliases because Cursor is inconsistent; `cwd` is deliberately ranked low |
+| 3 | `tool_input` or `toolArgs` paths | existing paths in the tool arguments | file paths resolve to their directory; missing paths fall through |
+| 4 | **Cursor's database** | `composer.composerHeaders` | exact, no inference — see below |
+| 5 | Transcript directory name | `~/.cursor/projects/<slug>/` | slug is the workspace path with separators flattened |
+| 6 | Transcript contents | most-mentioned git root | a guess; needs ≥3 votes |
+| 7 | Environment | `CURSOR_PROJECT_DIR`, `CURSOR_WORKSPACE_ROOT`, `CURSOR_WORKSPACE_FOLDER` | Cursor's documented hook env var, then explicit overrides |
+| 7b | Launch directory | `PWD`, `VSCODE_CWD` | used for this hook only, never cached, because `VSCODE_CWD` lies |
+| 8 | `unknown-project` | — | the honest answer when nothing else is |
+
+Every candidate then passes the same gate: not `.cursor`, not an IDE install
+path, not an OS directory, not a bare drive root, and not another agent's
+state directory.
+
+That last one is narrower than it sounds. Sessions were landing under
+`.codex`, but rejecting every dot-named directory would be wrong — plenty of
+real projects are dot-named, from `~/.dotfiles` and `~/.emacs.d` to GitHub's
+convention of a repository literally called `.github`. What separates those
+from `~/.codex` or `~/.vscode` is not the name but that a human deliberately
+version controls them, so the rule is **a dot-named directory that is not a
+git repository**. No list of tool names to keep current as new agents ship.
+
+Layers 4–6 additionally require the directory to **exist exactly**. Climbing to
+whatever ancestor survives is right for a file path out of `tool_input`, but
+wrong for a workspace path a source claims is authoritative: a project that
+moved away from `D:/Andrew/Code/cc-router` otherwise resolves to the project
+`Code`, and every session from that machine piles up under it.
+
+Set **`AM_CURSOR_DEBUG=1`** to have the resolver print which layer answered.
+Every layer returns the same shape, so a wrong project is otherwise
+undiagnosable from the outside.
+
+---
+
+## How Cursor stores this (reverse engineered)
+
+Layers 4–6 rely on Cursor's on-disk state. The layout, as of Cursor 3.x:
+
+```text
+<userdir>/ %APPDATA%/Cursor/User (Windows)
+ │ ~/Library/Application Support/Cursor/User (macOS)
+ │ ~/.config/Cursor/User (Linux)
+ ├── globalStorage/state.vscdb SQLite; all chat content + the 3.0 index
+ └── workspaceStorage/<hash>/
+ ├── workspace.json {"folder":"file:///d%3A/repo"}
+ └── state.vscdb SQLite; pre-3.0 per-workspace chat list
+
+~/.cursor/projects/<slug>/agent-transcripts/<sessionId>/<sessionId>.jsonl
+```
+
+**A Cursor hook's `session_id` is the `composerId`.** That is what makes layer
+4 possible: `composer.composerHeaders` in the global database maps a
+`composerId` straight to `workspaceIdentifier.uri.fsPath`. One indexed read,
+measured at 4–7ms even against a 3.6GB database, and cached for the rest of
+the session.
+
+Two caveats, both handled:
+
+* **Cursor 3.0 (April 2026) centralised that index**, moving it out of the
+ per-workspace databases, and migrates each workspace lazily — when it is next
+ opened. Machines still on ≤2.6, or with workspaces untouched since the
+ upgrade, keep the old per-workspace `allComposers` array. On one real machine
+ 55 of 124 workspaces were still in the old format. Both shapes are read; the
+ legacy scan is ordered by recency and capped, because the workspace a live
+ session belongs to was touched moments ago.
+* **Reading SQLite needs a driver.** `node:sqlite` exists from Node 22.5 and
+ this package supports Node ≥20; `better-sqlite3` is optional. With neither,
+ every path in `cursor-db.ts` returns null and layers 5–6 take over. This
+ layer is an accuracy upgrade, never a requirement.
+
+### Data handling: what layer 4 reads from Cursor's database
+
+For Cursor Marketplace review: layer 4 opens Cursor's `state.vscdb`
+**read-only** — `node:sqlite` with `readOnly: true`, or `better-sqlite3`
+with `readonly: true, fileMustExist: true` — and runs a single-key lookup,
+`composer.composerHeaders` in global storage or `composer.composerData` in
+legacy workspace storage. These records map the session to a workspace; only
+that path is used. The adapter does not write the database or send its records
+to the daemon. Layer 6 separately reads a bounded transcript excerpt to infer
+a workspace when the metadata lookup fails.
+The connection is closed after the read, and a locked or half-migrated file
+just makes the layer return null so layers 5–6 take over.
+
+### The slug encoding (layer 5)
+
+`~/.cursor/projects/` names one directory per workspace after the workspace
+path with every separator flattened to `-`:
+
+```text
+D:\Andrew\Code\Github\agentmemory → d-Andrew-Code-Github-agentmemory
+```
+
+The encoding is lossy in one direction: a directory name may itself contain
+hyphens, so `d-Andrew-Code-cc-router` is `D:/Andrew/Code/cc-router` and, just
+as validly on paper, `D:/Andrew/Code/cc/router`. The disambiguator is the
+filesystem — try every grouping of consecutive segments, descend only into
+groupings that exist. Pruning turns what looks like a 2ⁿ search into the
+handful of real directories on the machine: 39 slugs decode in 29ms, with zero
+ambiguous results.
+
+### What layer 6 is for, and why it is last
+
+The transcript scan answers "which git root is mentioned most in this
+conversation". That is a guess, and it was originally asked *before* the slug —
+so a session about agentmemory that was actually running elsewhere resolved to
+agentmemory. It now runs last, only existing directories vote, they vote for
+their git root, and a winner needs at least three votes. Without the git-root
+rule the winner is whatever generic directory came up most: `/bin`, `C:/Users`.
+
+It stays because it is the only layer that can place a **workspace-less
+window** — a chat started from Cursor's welcome screen — that was nonetheless
+editing real files.
+
+### Measured behaviour
+
+Over 300 real sessions on a Windows machine, resolving from **`session_id`
+alone** (no payload at all — the worst case, which real hooks rarely hit
+because layer 2 usually answers):
+
+| Resolved by | Sessions |
+|---|---|
+| Cursor's database (layer 4) | 10 |
+| Slug decode (layer 5) | 8 |
+| `unknown-project` | 12 |
+
+The twelve unknowns are deleted or moved projects and workspace-less windows —
+cases where no correct answer exists. There were no wrong attributions. Before
+this work both layers returned **zero** on Windows: the slug decoder bailed
+unless the name started with `Users-`, and the transcript scan anchored its
+regex on `$HOME`, which never matches a checkout on another drive.
+
+---
+
+## Known Cursor limitations
+
+* `sessionEnd` on window close has been reported as unreliable in Cursor 3.13.x
+ (`MainThreadShellExec not initialized`). Run `verify-flow.mjs --with-session-end`
+ to verify the built hook's finalization request separately from native event
+ delivery. `stop` captures the reply and schedules idle finalization.
+* `verify-flow.mjs` sends one tool event and waits for it to appear. A successful
+ hook process exit alone does not prove delivery.
+
+---
+
+## Testing
+
+```bash
+npx vitest run test/cursor-adapter.test.ts test/cursor-workspace.test.ts # no daemon
+node integrations/cursor/verify-flow.mjs # live daemon
+node integrations/cursor/close-stale-am-sessions.mjs --dry-run # dev utility
+```
+
+The tests assert delegation against a local HTTP server and stand-in hooks.
+The live smoke test exercises the built hooks against a daemon. Cursor IDE
+window-close behavior still needs verification in the native host.
+
+One trap worth knowing if you extend them: **do not use `spawnSync`**.
+`spawnSync` blocks the caller's event loop, so an in-process HTTP server
+cannot accept the connection the child is opening. The requests only arrive
+after the child has exited, which looks exactly like "the hook sent nothing"
+and costs an afternoon.
diff --git a/integrations/cursor/_env.mjs b/integrations/cursor/_env.mjs
new file mode 100644
index 00000000..1529c625
--- /dev/null
+++ b/integrations/cursor/_env.mjs
@@ -0,0 +1,74 @@
+/**
+ * Shared configuration loading for the Cursor integration scripts.
+ *
+ * The documented contract for agentmemory is that `AGENTMEMORY_URL` and
+ * `AGENTMEMORY_SECRET` come from the runtime environment, with
+ * `~/.agentmemory/.env` as the persistent default. These scripts end and
+ * rewrite sessions on whatever host they are pointed at, so reading the file
+ * only -- and ignoring an explicit `AGENTMEMORY_URL=... node ...` -- would
+ * quietly aim a destructive operation at the wrong server.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const ENV_PATH = join(homedir(), '.agentmemory', '.env');
+
+export function parseEnvFile(path = ENV_PATH) {
+ const out = {};
+ if (!existsSync(path)) return out;
+ for (const line of readFileSync(path, 'utf-8').split('\n')) {
+ const trimmed = line.trim();
+ if (!trimmed || trimmed.startsWith('#')) continue;
+ const idx = trimmed.indexOf('=');
+ if (idx === -1) continue;
+ const key = trimmed.slice(0, idx).trim().replace(/^export\s+/, '');
+ let value = trimmed.slice(idx + 1).trim();
+ const quote = value[0] === '"' || value[0] === "'" ? value[0] : '';
+ if (quote) {
+ const close = value.indexOf(quote, 1);
+ if (close !== -1) value = value.slice(1, close);
+ } else {
+ const hash = value.indexOf(' #');
+ if (hash !== -1) value = value.slice(0, hash).trim();
+ }
+ out[key] = value;
+ }
+ return out;
+}
+
+/** Runtime environment first, `~/.agentmemory/.env` second, '' if neither. */
+export function loadConfig(keys, path = ENV_PATH) {
+ const file = parseEnvFile(path);
+ const out = {};
+ for (const key of keys) {
+ const fromEnv = process.env[key]?.trim();
+ out[key] = fromEnv || file[key] || '';
+ }
+ return out;
+}
+
+/** Resolve local credentials without forwarding stored secrets to remote daemons. */
+export function requireConnection(path = ENV_PATH) {
+ const { AGENTMEMORY_URL: url } = loadConfig(['AGENTMEMORY_URL'], path);
+ if (!url) throw new Error(`Missing AGENTMEMORY_URL. Set it in the environment or in ${path}.`);
+ const parsed = new URL(url);
+ if (!['http:', 'https:'].includes(parsed.protocol)) throw new Error('AGENTMEMORY_URL must use HTTP or HTTPS.');
+ const host = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+ const local = host === 'localhost' || host === '::1' || /^127(?:\.\d{1,3}){3}$/.test(host);
+ const usable = value => typeof value === 'string' && !value.trim().startsWith('${') ? value.trim() : '';
+ let secret = usable(process.env.AGENTMEMORY_SECRET);
+ if (!secret && local && process.env.AGENTMEMORY_CREDENTIAL_MODE !== 'explicit') {
+ secret = usable(parseEnvFile(path).AGENTMEMORY_SECRET);
+ if (!secret) {
+ try { secret = usable(readFileSync(join(homedir(), '.agentmemory/secret'), 'utf8')); } catch {}
+ }
+ }
+ if (secret && !local && parsed.protocol !== 'https:') throw new Error('Remote daemon credentials require HTTPS.');
+ return { url: url.replace(/\/+$/, ''), secret };
+}
+
+/** Bearer header only when a secret is configured. */
+export function authHeader(secret) {
+ return secret ? { Authorization: `Bearer ${secret}` } : {};
+}
diff --git a/integrations/cursor/close-stale-am-sessions.mjs b/integrations/cursor/close-stale-am-sessions.mjs
new file mode 100644
index 00000000..938c3a6b
--- /dev/null
+++ b/integrations/cursor/close-stale-am-sessions.mjs
@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * Close agentmemory sessions stuck in status "active" (sessionEnd hook never ran).
+ *
+ * Usage:
+ * node integrations/cursor/close-stale-am-sessions.mjs --dry-run
+ * node integrations/cursor/close-stale-am-sessions.mjs --min-age-hours 24
+ * node integrations/cursor/close-stale-am-sessions.mjs --min-age-hours 6 --project my-project
+ * node integrations/cursor/close-stale-am-sessions.mjs --exclude ses_abc123,def456
+ */
+import { authHeader, requireConnection } from './_env.mjs';
+
+function parseArgs() {
+ const args = process.argv.slice(2);
+ const opts = {
+ dryRun: args.includes('--dry-run'),
+ minAgeHours: 24,
+ project: null,
+ exclude: new Set()
+ };
+ for (let i = 0; i < args.length; i++) {
+ if (args[i] === '--min-age-hours' && args[i + 1]) {
+ const raw = args[++i];
+ const parsed = Number(raw);
+ if (!Number.isFinite(parsed) || parsed < 0) {
+ console.error(`Invalid --min-age-hours value: ${raw}`);
+ process.exit(1);
+ }
+ opts.minAgeHours = parsed;
+ } else if (args[i] === '--project' && args[i + 1]) {
+ opts.project = args[++i];
+ } else if (args[i] === '--exclude' && args[i + 1]) {
+ for (const id of args[++i].split(',')) {
+ const t = id.trim();
+ if (t) opts.exclude.add(t);
+ }
+ }
+ }
+ return opts;
+}
+
+async function main() {
+ const opts = parseArgs();
+ const { url: restUrl, secret } = requireConnection();
+
+ const headers = {
+ ...authHeader(secret),
+ 'Content-Type': 'application/json'
+ };
+
+ const listRes = await fetch(`${restUrl}/agentmemory/sessions`, { headers });
+ if (!listRes.ok) {
+ console.error('Failed to list sessions:', listRes.status, await listRes.text());
+ process.exit(1);
+ }
+
+ const { sessions } = await listRes.json();
+ const cutoff = Date.now() - opts.minAgeHours * 3600000;
+ const candidates = sessions.filter((s) => {
+ if (s.status !== 'active') return false;
+ if (opts.exclude.has(s.id)) return false;
+ if (opts.project && s.project !== opts.project) return false;
+ const started = Date.parse(s.startedAt);
+ if (!Number.isFinite(started) || started > cutoff) return false;
+ return true;
+ });
+
+ candidates.sort((a, b) => Date.parse(a.startedAt) - Date.parse(b.startedAt));
+
+ console.log(
+ `Found ${candidates.length} active session(s) older than ${opts.minAgeHours}h` +
+ (opts.project ? ` (project=${opts.project})` : '')
+ );
+
+ for (const s of candidates) {
+ const ageH = ((Date.now() - Date.parse(s.startedAt)) / 3600000).toFixed(1);
+ console.log(
+ ` ${s.id.slice(0, 12)}… ${s.project} obs=${s.observationCount ?? 0} age=${ageH}h`
+ );
+ }
+
+ if (!candidates.length) {
+ console.log('Nothing to close.');
+ return;
+ }
+
+ if (opts.dryRun) {
+ console.log(`Dry run: would close ${candidates.length} session(s) via POST /agentmemory/session/end`);
+ return;
+ }
+
+ let closed = 0;
+ let failed = 0;
+
+ for (const s of candidates) {
+ const res = await fetch(`${restUrl}/agentmemory/session/end`, {
+ method: 'POST',
+ headers,
+ body: JSON.stringify({ sessionId: s.id })
+ });
+ if (res.ok) {
+ closed++;
+ } else {
+ failed++;
+ console.error(` failed ${s.id}: ${res.status} ${await res.text()}`);
+ }
+ }
+
+ console.log(`Closed ${closed} session(s), ${failed} failed.`);
+
+ const verify = await fetch(`${restUrl}/agentmemory/sessions`, { headers }).then((r) =>
+ r.json()
+ );
+ const stillActive = verify.sessions.filter(
+ (s) => s.status === 'active' && Date.parse(s.startedAt) <= cutoff
+ ).length;
+ console.log(`Remaining stale active (>${opts.minAgeHours}h): ${stillActive}`);
+}
+
+main().catch((err) => {
+ console.error(err);
+ process.exit(1);
+});
diff --git a/integrations/cursor/install-local.mjs b/integrations/cursor/install-local.mjs
new file mode 100644
index 00000000..dbc48932
--- /dev/null
+++ b/integrations/cursor/install-local.mjs
@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, symlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig, requireConnection } from './_env.mjs';
+
+const INTEGRATION_ROOT = resolve(dirname(fileURLToPath(import.meta.url)));
+const REPO_ROOT = resolve(INTEGRATION_ROOT, '../..');
+const CURSOR_DIR = join(homedir(), '.cursor');
+const MCP_PATH = join(CURSOR_DIR, 'mcp.json');
+const HOOKS_PATH = join(CURSOR_DIR, 'hooks.json');
+const MARKETPLACE_NAME = 'local-agentmemory';
+const MARKETPLACE_DIR = join(CURSOR_DIR, 'plugins', 'marketplaces', MARKETPLACE_NAME);
+const LEGACY_MARKETPLACE_DIR = join(CURSOR_DIR, 'plugins', 'marketplaces', 'local-agentmemory-cursor');
+
+function readJson(path) {
+ if (!existsSync(path)) return {};
+ try {
+ return JSON.parse(readFileSync(path, 'utf-8'));
+ } catch (err) {
+ throw new Error(`Cannot parse ${path}: ${err.message}`);
+ }
+}
+
+function writeJson(path, data, restrictPermissions = false) {
+ mkdirSync(dirname(path), { recursive: true });
+ writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, 'utf-8');
+ if (restrictPermissions) {
+ try {
+ chmodSync(path, 0o600);
+ } catch {}
+ }
+}
+
+function isPlainObject(value) {
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function describeJsonType(value) {
+ if (value === null) return 'null';
+ if (Array.isArray(value)) return 'array';
+ return typeof value;
+}
+
+function requireObjectConfig(path, value, label) {
+ if (!isPlainObject(value)) {
+ console.error(`${path}: expected ${label} to be a JSON object, got ${describeJsonType(value)}`);
+ process.exit(1);
+ }
+}
+
+function requireObjectField(path, fieldName, value) {
+ if (value === undefined) return;
+ if (!isPlainObject(value)) {
+ console.error(`${path}: expected "${fieldName}" to be a JSON object, got ${describeJsonType(value)}`);
+ process.exit(1);
+ }
+}
+
+function linkMarketplace() {
+ mkdirSync(dirname(MARKETPLACE_DIR), { recursive: true });
+ if (!existsSync(MARKETPLACE_DIR)) {
+ symlinkSync(REPO_ROOT, MARKETPLACE_DIR, process.platform === 'win32' ? 'junction' : 'dir');
+ }
+}
+
+function mergeMcp(env) {
+ let mcp;
+ try {
+ mcp = existsSync(MCP_PATH) ? readJson(MCP_PATH) : {};
+ } catch (err) {
+ console.error(err.message);
+ console.error('Refusing to overwrite mcp.json. Fix the file or restore from backup.');
+ process.exit(1);
+ }
+ requireObjectConfig(MCP_PATH, mcp, 'mcp.json root');
+ requireObjectField(MCP_PATH, 'mcpServers', mcp.mcpServers);
+ if (!mcp.mcpServers) mcp.mcpServers = {};
+ mcp.mcpServers.agentmemory = {
+ command: 'npx',
+ args: ['-y', '@agentmemory/mcp'],
+ env: {
+ AGENTMEMORY_URL: env.AGENTMEMORY_URL || 'http://localhost:3111',
+ AGENTMEMORY_SECRET: env.AGENTMEMORY_SECRET || '',
+ AGENTMEMORY_TOOLS: env.AGENTMEMORY_TOOLS || 'all',
+ },
+ };
+ const backup = `${MCP_PATH}.bak-${Date.now()}`;
+ if (existsSync(MCP_PATH)) {
+ copyFileSync(MCP_PATH, backup);
+ try {
+ chmodSync(backup, 0o600);
+ } catch {}
+ }
+ writeJson(MCP_PATH, mcp, true);
+ return backup;
+}
+
+function isAgentmemoryHook(entry) {
+ if (typeof entry?.command !== 'string') return false;
+ const args = entry.command.match(/^\s*(?:"([^"]+)"|'([^']+)'|(\S+))\s+(?:"([^"]+)"|'([^']+)'|(\S+))(?:\s|$)/);
+ if (!args) return false;
+ const executable = (args[1] || args[2] || args[3]).replace(/\\/g, '/');
+ if (!/(?:^|\/)node(?:\.exe)?$/.test(executable)) return false;
+ const argument = args[4] || args[5] || args[6];
+ const script = (existsSync(argument) ? realpathSync(argument) : argument).replace(/\\/g, '/');
+ const roots = [REPO_ROOT.replace(/\\/g, '/'), '${CURSOR_PLUGIN_ROOT}'];
+ const hooks = ['session-start', 'prompt-submit', 'pre-tool-use', 'post-tool-use', 'post-tool-failure', 'pre-compact', 'subagent-start', 'subagent-stop', 'stop', 'session-end', 'cursor/run-hook', 'cursor/run-detached'];
+ return roots.some(root => hooks.some(hook => script === `${root}/plugin/scripts/${hook}.mjs`));
+}
+
+function disableUserHooks() {
+ if (!process.argv.includes('--clear-user-hooks')) return null;
+ if (!existsSync(HOOKS_PATH)) return null;
+ let hooks;
+ try {
+ hooks = readJson(HOOKS_PATH);
+ } catch (err) {
+ console.error(err.message);
+ console.error('Refusing to clear hooks.json until the file is valid JSON.');
+ process.exit(1);
+ }
+ requireObjectConfig(HOOKS_PATH, hooks, 'hooks.json root');
+ requireObjectField(HOOKS_PATH, 'hooks', hooks.hooks);
+ if (!hooks.hooks) return null;
+
+ let removed = 0;
+ const filtered = {};
+ for (const [event, entries] of Object.entries(hooks.hooks)) {
+ if (!Array.isArray(entries)) {
+ filtered[event] = entries;
+ continue;
+ }
+ const kept = entries.filter((entry) => !isAgentmemoryHook(entry));
+ removed += entries.length - kept.length;
+ if (kept.length > 0) filtered[event] = kept;
+ }
+ if (removed === 0) return null;
+
+ const backup = `${HOOKS_PATH}.pre-plugin-${Date.now()}.bak`;
+ copyFileSync(HOOKS_PATH, backup);
+ writeJson(HOOKS_PATH, { ...hooks, hooks: filtered });
+ return backup;
+}
+
+const { url, secret } = requireConnection();
+const env = { ...loadConfig(['AGENTMEMORY_TOOLS']), AGENTMEMORY_URL: url, AGENTMEMORY_SECRET: secret };
+
+linkMarketplace();
+const mcpBackup = mergeMcp(env);
+const hooksBackup = disableUserHooks();
+
+console.log('\nagentmemory Cursor plugin (local dev) wired.\n');
+console.log(`Repo root: ${REPO_ROOT}`);
+console.log(`Plugin package: ${join(REPO_ROOT, 'plugin')}`);
+console.log(`Marketplace junction: ${MARKETPLACE_DIR}`);
+if (existsSync(LEGACY_MARKETPLACE_DIR)) {
+ console.log(`Legacy junction still present: ${LEGACY_MARKETPLACE_DIR}`);
+ console.log(' Remove it in Cursor Settings → Plugins if you added marketplace from integrations/cursor before.');
+}
+if (mcpBackup) console.log(`mcp.json backup: ${mcpBackup}`);
+if (hooksBackup) console.log(`hooks.json backup: ${hooksBackup}`);
+console.log(`AGENTMEMORY_URL: ${env.AGENTMEMORY_URL}`);
+console.log(`AGENTMEMORY_SECRET: ${env.AGENTMEMORY_SECRET ? '<set, not printed>' : '<not configured>'}`);
+console.log('\nNext steps:');
+console.log('1. Cursor → Settings → Plugins → Add marketplace from folder:');
+console.log(` ${REPO_ROOT}`);
+console.log(' (repo root — must contain .cursor-plugin/plugin.json)');
+console.log('2. Enable plugin: agentmemory');
+console.log('3. Disable any second agentmemory marketplace entry if both are enabled.');
+console.log('4. Developer: Reload Window');
+console.log('5. Run: node integrations/cursor/verify-flow.mjs');
+console.log('6. In hooks log, confirm commands use plugin/scripts/cursor/run-hook.mjs');
+console.log('\nOnly after plugin hooks are confirmed:');
+console.log(' node integrations/cursor/install-local.mjs --clear-user-hooks');
diff --git a/integrations/cursor/verify-flow.mjs b/integrations/cursor/verify-flow.mjs
new file mode 100644
index 00000000..9985ac1c
--- /dev/null
+++ b/integrations/cursor/verify-flow.mjs
@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * End-to-end smoke test for the Cursor plugin hook pipeline against a live
+ * agentmemory daemon.
+ *
+ * Every assertion polls the daemon rather than sleeping for a fixed time.
+ * The hook processes are deliberately not synchronous with the work they
+ * cause: the canonical hooks fire-and-forget their HTTP calls and exit on a
+ * short timer, and run-detached.mjs returns as soon as its background worker
+ * is spawned. A fixed sleep therefore proves nothing -- too short and a
+ * healthy pipeline reports FAIL, too long and a broken one still has time to
+ * look healthy. Polling for the state change is the only honest check.
+ */
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { authHeader, requireConnection } from './_env.mjs';
+
+const INTEGRATION_ROOT = resolve(dirname(fileURLToPath(import.meta.url)));
+const REPO_ROOT = resolve(INTEGRATION_ROOT, '../..');
+const CURSOR_SCRIPTS = join(REPO_ROOT, 'plugin', 'scripts', 'cursor');
+
+const POLL_INTERVAL_MS = 1000;
+const POLL_TIMEOUT_MS = 90000;
+
+const { url, secret } = requireConnection();
+const authHeaders = authHeader(secret);
+
+function runHook(script, args, payload) {
+ const r = spawnSync(process.execPath, [join(CURSOR_SCRIPTS, script), ...args], {
+ input: JSON.stringify(payload),
+ encoding: 'utf-8',
+ timeout: 60000,
+ env: { ...process.env, AGENTMEMORY_URL: url, AGENTMEMORY_SECRET: secret }
+ });
+ return { status: r.status, stderr: r.stderr?.trim().slice(0, 300) ?? '' };
+}
+
+async function fetchSession(id) {
+ const r = await fetch(`${url}/agentmemory/sessions`, {
+ headers: authHeaders,
+ redirect: "error",
+ signal: AbortSignal.timeout(30000)
+ });
+ if (!r.ok) throw new Error(`GET /agentmemory/sessions -> ${r.status}`);
+ const data = await r.json();
+ return data.sessions?.find((s) => s.id === id) ?? null;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Poll until `predicate(session)` holds. Returns the last session seen. */
+async function waitFor(id, predicate, timeoutMs = POLL_TIMEOUT_MS) {
+ const deadline = Date.now() + timeoutMs;
+ let last = null;
+ for (;;) {
+ last = await fetchSession(id);
+ if (last && predicate(last)) return { session: last, ok: true, waitedMs: 0 };
+ if (Date.now() >= deadline) return { session: last, ok: false };
+ await sleep(POLL_INTERVAL_MS);
+ }
+}
+
+if (!existsSync(join(CURSOR_SCRIPTS, 'run-hook.mjs'))) {
+ console.error(`Missing Cursor shim at ${CURSOR_SCRIPTS}. Run \`npm run build\` first.`);
+ process.exit(1);
+}
+
+const workspace = mkdtempSync(join(tmpdir(), 'am-cursor-verify-'));
+process.on('exit', () => rmSync(workspace, { recursive: true, force: true }));
+const repoRootNorm = workspace.replace(/\\/g, '/');
+const expectedProject = process.env.AGENTMEMORY_PROJECT_NAME?.trim() || basename(workspace);
+const sessionId = `cursor-plugin-verify-${Date.now()}`;
+const basePayload = {
+ session_id: sessionId,
+ workspace_roots: [repoRootNorm],
+ cwd: repoRootNorm
+};
+
+console.log('=== agentmemory Cursor plugin verify ===\n');
+console.log(`Shim scripts: ${CURSOR_SCRIPTS}`);
+console.log(`Session id: ${sessionId}\n`);
+
+// A non-2xx /livez means the daemon is up but rejecting us (usually a bad
+// secret). Continuing past it turns one clear error into four confusing ones.
+let livez;
+try {
+ livez = await fetch(`${url}/agentmemory/livez`, {
+ headers: authHeaders,
+ redirect: "error",
+ signal: AbortSignal.timeout(15000)
+ });
+} catch (e) {
+ console.error(`livez: unreachable (${e.message})`);
+ process.exit(1);
+}
+if (!livez.ok) {
+ console.error(`livez: HTTP ${livez.status} -- check AGENTMEMORY_URL / AGENTMEMORY_SECRET`);
+ process.exit(1);
+}
+console.log('livez: ok');
+
+const results = [];
+function record(name, ok, detail) {
+ results.push({ name, ok, detail });
+ console.log(` ${ok ? 'PASS' : 'FAIL'} ${name}${detail ? ` -- ${detail}` : ''}`);
+}
+
+// 1. sessionStart: the session must show up on the daemon at all.
+console.log('\n[1/4] sessionStart');
+let r = runHook('run-hook.mjs', ['sessionStart'], basePayload);
+console.log(` shim exit ${r.status}${r.stderr ? ` (${r.stderr})` : ''}`);
+let w = await waitFor(sessionId, (s) => Boolean(s));
+record('session registered', w.ok, w.session ? `project=${w.session.project}` : 'never appeared');
+record(
+ 'resolver picked the test workspace, not .cursor',
+ w.session?.project === expectedProject,
+ `got ${w.session?.project ?? '(none)'}`
+);
+
+// 2. One tool event must be recorded; a different retry would hide a lost event.
+console.log('\n[2/4] postToolUse');
+r = runHook('run-hook.mjs', ['postToolUse'], {
+ ...basePayload,
+ tool_name: 'Read',
+ tool_input: { path: join(REPO_ROOT, 'package.json') },
+ tool_output: 'verify-flow smoke test'
+});
+record('tool hook completed', r.status === 0, r.stderr);
+w = await waitFor(sessionId, (s) => (s.observationCount ?? 0) >= 1);
+record('observation captured', w.ok, `obs=${w.session?.observationCount ?? 0}`);
+
+// Stop captures the reply and schedules idle finalization; it is not sessionEnd.
+console.log('\n[3/4] stop (detached)');
+const observationsBeforeStop = w.session?.observationCount ?? 0;
+r = runHook('run-detached.mjs', ['stop'], {
+ ...basePayload,
+ last_assistant_message: 'Cursor detached stop smoke test'
+});
+console.log(` parent exit ${r.status}${r.stderr ? ` (${r.stderr})` : ''} (worker continues in background)`);
+w = await waitFor(sessionId, (s) => (s.observationCount ?? 0) > observationsBeforeStop);
+record(
+ 'detached worker captured the reply',
+ r.status === 0 && w.ok,
+ `obs=${w.session?.observationCount ?? 0}`
+);
+
+// Use a separate session so the stop hook cannot satisfy the sessionEnd check.
+if (process.argv.includes('--with-session-end')) {
+ console.log('\n[4/4] sessionEnd');
+ const endId = `${sessionId}-end`;
+ const payload = { ...basePayload, session_id: endId };
+ runHook('run-hook.mjs', ['sessionStart'], payload);
+ const started = await waitFor(endId, () => true);
+ record('sessionEnd fixture registered', started.ok);
+ r = runHook('run-detached.mjs', ['sessionEnd'], { ...payload, reason: 'window_close' });
+ record('sessionEnd worker spawned', r.status === 0, r.stderr);
+ const ended = await waitFor(endId, (s) => s.status === 'completed' || Boolean(s.endedAt));
+ record('sessionEnd closed its own session', ended.ok);
+} else {
+ console.log('\n[4/4] sessionEnd skipped (pass --with-session-end to exercise it)');
+}
+
+const failed = results.filter((x) => !x.ok);
+console.log(`\n${results.length - failed.length}/${results.length} checks passed.`);
+if (failed.length) {
+ console.error(`FAILED: ${failed.map((f) => f.name).join(', ')}`);
+ process.exit(1);
+}
+console.log('Cursor hook pipeline OK.');
diff --git a/plugin/cursor/hooks.json b/plugin/cursor/hooks.json
index 8f6e393b..b652a9c6 100644
--- a/plugin/cursor/hooks.json
+++ b/plugin/cursor/hooks.json
@@ -3,38 +3,53 @@
"hooks": {
"sessionStart": [
{
- "command": "node ${CURSOR_PLUGIN_ROOT}/plugin/scripts/session-start.mjs"
+ "command": "node \"${CURSOR_PLUGIN_ROOT}/plugin/scripts/cursor/run-hook.mjs\" sessionStart"
}
],
"beforeSubmitPrompt": [
{
- "command": "node ${CURSOR_PLUGIN_ROOT}/plugin/scripts/prompt-submit.mjs"
+ "command": "node \"${CURSOR_PLUGIN_ROOT}/plugin/scripts/cursor/run-hook.mjs\" beforeSubmitPrompt"
}
],
"preToolUse": [
{
- "command": "node ${CURSOR_PLUGIN_ROOT}/plugin/scripts/pre-tool-use.mjs",
- "matcher": "Shell|Read|Write|Grep"
+ "matcher": "Edit|Write|Read|Glob|Grep|Shell",
+ "command": "node \"${CURSOR_PLUGIN_ROOT}/plugin/scripts/cursor/run-hook.mjs\" preToolUse"
}
],
"postToolUse": [
{
- "command": "node ${CURSOR_PLUGIN_ROOT}/plugin/scripts/post-tool-use.mjs"
+ "command": "node \"${CURSOR_PLUGIN_ROOT}/plugin/scripts/cursor/run-hook.mjs\" postToolUse"
}
],
"postToolUseFailure": [
{
- "command": "node ${CURSOR_PLUGIN_ROOT}/plugin/scripts/post-tool-failure.mjs"
+ "command": "node \"${CURSOR_PLUGIN_ROOT}/plugin/scripts/cursor/run-hook.mjs\" postToolUseFailure"
+ }
+ ],
+ "preCompact": [
+ {
+ "command": "node \"${CURSOR_PLUGIN_ROOT}/plugin/scripts/cursor/run-hook.mjs\" preCompact"
+ }
+ ],
+ "subagentStart": [
+ {
+ "command": "node \"${CURSOR_PLUGIN_ROOT}/plugin/scripts/cursor/run-hook.mjs\" subagentStart"
+ }
+ ],
+ "subagentStop": [
+ {
+ "command": "node \"${CURSOR_PLUGIN_ROOT}/plugin/scripts/cursor/run-hook.mjs\" subagentStop"
}
],
"stop": [
{
- "command": "node ${CURSOR_PLUGIN_ROOT}/plugin/scripts/stop.mjs"
+ "command": "node \"${CURSOR_PLUGIN_ROOT}/plugin/scripts/cursor/run-detached.mjs\" stop"
}
],
"sessionEnd": [
{
- "command": "node ${CURSOR_PLUGIN_ROOT}/plugin/scripts/session-end.mjs"
+ "command": "node \"${CURSOR_PLUGIN_ROOT}/plugin/scripts/cursor/run-detached.mjs\" sessionEnd"
}
]
}
diff --git a/plugin/scripts/cursor/run-detached.mjs b/plugin/scripts/cursor/run-detached.mjs
new file mode 100755
index 00000000..25515f55
--- /dev/null
+++ b/plugin/scripts/cursor/run-detached.mjs
@@ -0,0 +1,786 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { execSync, spawn, spawnSync } from "node:child_process";
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { basename, dirname, join, resolve } from "node:path";
+import { homedir, tmpdir } from "node:os";
+//#region src/hooks/_project.ts
+function resolveProject(cwd) {
+ const explicit = process.env["AGENTMEMORY_PROJECT_NAME"];
+ if (explicit && explicit.trim()) return explicit.trim();
+ const dir = cwd && cwd.trim() ? cwd : process.cwd();
+ try {
+ const [top, gitDir, commonDir] = execSync("git rev-parse --show-toplevel --git-dir --git-common-dir", {
+ cwd: dir,
+ stdio: [
+ "ignore",
+ "pipe",
+ "ignore"
+ ],
+ timeout: 500
+ }).toString().trim().split(/\r?\n/);
+ if (top) return basename(repositoryRoot(dir, top, gitDir, commonDir));
+ } catch {}
+ return basename(dir);
+}
+function repositoryRoot(dir, top, gitDir, commonDir) {
+ if (!gitDir || !commonDir) return top;
+ const physical = realpathSync(dir);
+ const common = resolve(physical, commonDir);
+ if (resolve(physical, gitDir) === common || basename(common) !== ".git") return top;
+ return dirname(common);
+}
+//#endregion
+//#region src/hooks/cursor/cursor-db.ts
+/**
+* Exact session -> workspace lookup from Cursor's own SQLite storage.
+*
+* Everything else in the resolver infers the workspace: from payload fields
+* Cursor may or may not send, from paths that happen to appear in tool
+* arguments, from a transcript directory name whose path separators have been
+* flattened into hyphens. Those work, but they are inference, and inference
+* that lands on the wrong project writes a user's memories into the wrong
+* place without ever reporting an error.
+*
+* Cursor knows the answer exactly, and stores it. The layout (reverse
+* engineered; see integrations/cursor/README.md for the full picture):
+*
+* <userdir>/globalStorage/state.vscdb
+* ItemTable["composer.composerHeaders"]
+* -> { allComposers: [ { composerId, workspaceIdentifier: {
+* id, uri: { fsPath, ... } } } ] }
+*
+* A Cursor hook's `session_id` is the `composerId`, so one indexed lookup
+* gives the workspace path with no guessing.
+*
+* Two things stop this from being the only strategy:
+*
+* - Cursor 3.0 (April 2026) moved this index from per-workspace databases
+* into the global one, and the migration is lazy: a workspace migrates
+* when it is next opened. Machines still on <=2.6, or with workspaces not
+* opened since the upgrade, keep the old per-workspace `allComposers`
+* array instead. Both shapes are handled below.
+* - Reading SQLite needs a driver. `node:sqlite` only exists from Node 22.5,
+* and this package supports Node >=20. better-sqlite3 is an optional
+* dependency of the daemon, not something a hook can count on.
+*
+* So every failure path here returns null and the caller falls back to
+* inference. This module is an accuracy upgrade, never a requirement.
+*/
+const require = createRequire(import.meta.url);
+let driverCache;
+let warningFilterInstalled = false;
+function suppressSqliteExperimentalWarning() {
+ if (warningFilterInstalled) return;
+ warningFilterInstalled = true;
+ const previous = process.listeners("warning");
+ process.removeAllListeners("warning");
+ process.on("warning", (warning) => {
+ if (warning.name === "ExperimentalWarning" && /sqlite/i.test(warning.message)) return;
+ for (const listener of previous) listener(warning);
+ });
+}
+function requireQuietly(id) {
+ suppressSqliteExperimentalWarning();
+ try {
+ return require(id);
+ } catch {
+ return null;
+ }
+}
+function loadDriver() {
+ if (driverCache !== void 0) return driverCache;
+ const nodeSqlite = requireQuietly("node:sqlite");
+ if (nodeSqlite?.DatabaseSync) {
+ driverCache = { open: (path) => new nodeSqlite.DatabaseSync(path, { readOnly: true }) };
+ return driverCache;
+ }
+ const better = requireQuietly("better-sqlite3");
+ if (better) {
+ driverCache = { open: (path) => new better(path, {
+ readonly: true,
+ fileMustExist: true
+ }) };
+ return driverCache;
+ }
+ driverCache = null;
+ return driverCache;
+}
+/** Read one ItemTable value. Returns null for any failure, including a locked DB. */
+function readItemTableValue(dbPath, key) {
+ if (!existsSync(dbPath)) return null;
+ const driver = loadDriver();
+ if (!driver) return null;
+ let db = null;
+ try {
+ db = driver.open(dbPath);
+ const value = db.prepare("SELECT value FROM ItemTable WHERE key = ?").get(key)?.value;
+ if (typeof value === "string") return value;
+ if (value instanceof Uint8Array) return Buffer.from(value).toString("utf-8");
+ return null;
+ } catch {
+ return null;
+ } finally {
+ try {
+ db?.close();
+ } catch {}
+ }
+}
+function cursorStorageRoots() {
+ const home = homedir();
+ const bases = [];
+ if (process.platform === "win32") {
+ const appData = process.env["APPDATA"];
+ if (appData) bases.push(join(appData, "Cursor", "User"));
+ bases.push(join(home, "AppData", "Roaming", "Cursor", "User"));
+ } else if (process.platform === "darwin") bases.push(join(home, "Library", "Application Support", "Cursor", "User"));
+ else {
+ const configHome = process.env["XDG_CONFIG_HOME"];
+ if (configHome) bases.push(join(configHome, "Cursor", "User"));
+ bases.push(join(home, ".config", "Cursor", "User"));
+ }
+ for (const base of bases) {
+ const globalStorage = join(base, "globalStorage");
+ if (existsSync(globalStorage)) return {
+ globalStorage,
+ workspaceStorage: join(base, "workspaceStorage")
+ };
+ }
+ return null;
+}
+function fsPathFromHeader(header) {
+ const uri = header?.workspaceIdentifier?.uri;
+ const value = uri?.fsPath ?? uri?.path;
+ return typeof value === "string" && value.trim() ? value : null;
+}
+/** Cursor 3.0+: one central index in the global database. */
+function fromGlobalIndex(sessionId, roots) {
+ const raw = readItemTableValue(join(roots.globalStorage, "state.vscdb"), "composer.composerHeaders");
+ if (!raw) return null;
+ try {
+ const hit = JSON.parse(raw).allComposers?.find((c) => c?.composerId === sessionId);
+ return fsPathFromHeader(hit);
+ } catch {
+ return null;
+ }
+}
+/** `{"folder":"file:///d%3A/repo"}`, or a vscode-remote:// URI we cannot map. */
+function folderFromWorkspaceJson(workspaceDir) {
+ const file = join(workspaceDir, "workspace.json");
+ if (!existsSync(file)) return null;
+ try {
+ const folder = JSON.parse(readFileSync(file, "utf-8")).folder;
+ if (typeof folder !== "string" || !folder.startsWith("file://")) return null;
+ return fileURLToPath(folder);
+ } catch {
+ return null;
+ }
+}
+const LEGACY_SCAN_LIMIT = 40;
+function fromLegacyWorkspaceDbs(sessionId, roots) {
+ if (!existsSync(roots.workspaceStorage)) return null;
+ let dirs;
+ try {
+ dirs = readdirSync(roots.workspaceStorage).map((dir) => {
+ try {
+ return {
+ dir,
+ mtime: statSync(join(roots.workspaceStorage, dir, "state.vscdb")).mtimeMs
+ };
+ } catch {
+ return null;
+ }
+ }).filter((x) => x !== null).sort((a, b) => b.mtime - a.mtime).slice(0, LEGACY_SCAN_LIMIT);
+ } catch {
+ return null;
+ }
+ for (const { dir } of dirs) {
+ const raw = readItemTableValue(join(roots.workspaceStorage, dir, "state.vscdb"), "composer.composerData");
+ if (!raw) continue;
+ try {
+ const parsed = JSON.parse(raw);
+ if (!Array.isArray(parsed.allComposers)) continue;
+ if (!parsed.allComposers.some((c) => c?.composerId === sessionId)) continue;
+ return folderFromWorkspaceJson(join(roots.workspaceStorage, dir));
+ } catch {
+ continue;
+ }
+ }
+ return null;
+}
+/**
+* The workspace directory Cursor recorded for this session, or null when it
+* cannot be determined (no driver, no storage, workspace-less window, or a
+* remote URI that does not map to a local path).
+*/
+function workspaceFromCursorDb(sessionId) {
+ if (!sessionId) return null;
+ const roots = cursorStorageRoots();
+ if (!roots) return null;
+ return fromGlobalIndex(sessionId, roots) ?? fromLegacyWorkspaceDbs(sessionId, roots);
+}
+//#endregion
+//#region src/hooks/cursor/workspace.ts
+const HOME = homedir();
+const CURSOR_PROJECTS_DIR = join(HOME, ".cursor", "projects");
+const SESSION_CACHE_PATH = join(HOME, ".cursor", "hooks", ".agentmemory-session-cache.json");
+const HOOK_PAYLOAD_DIR = join(HOME, ".cursor", "hooks", ".am-hook-payloads");
+const SESSION_CACHE_MAX_AGE_MS = 10080 * 60 * 1e3;
+const SESSION_CACHE_MAX_ENTRIES = 200;
+function normalizePathSlashes(value) {
+ return String(value).replace(/\\/g, "/");
+}
+function isCursorMetadataPath(value) {
+ if (!value || typeof value !== "string") return false;
+ const trimmed = normalizePathSlashes(value.trim());
+ if (trimmed === ".cursor") return true;
+ if (/(^|\/)\.cursor\/worktrees\/[^/]/.test(trimmed)) return false;
+ return /(^|\/)\.cursor(\/|$)/.test(trimmed);
+}
+function pathUnderHome(value) {
+ if (typeof value !== "string") return false;
+ const homeNorm = normalizePathSlashes(HOME);
+ const valueNorm = normalizePathSlashes(value);
+ return valueNorm === homeNorm || valueNorm.startsWith(`${homeNorm}/`);
+}
+function isIdeInstallPath(value) {
+ if (!value || typeof value !== "string") return false;
+ const norm = normalizePathSlashes(value).toLowerCase();
+ return /(^|[\\/])(programs|program files|program files \(x86\))[\\/]cursor([\\/]|$)/i.test(norm) || /cursor\.app[\\/]contents/i.test(norm) || /(^|[\\/])microsoft vs code[\\/]resources[\\/]app([\\/]|$)/i.test(norm);
+}
+function isBadPath(value) {
+ if (!value || typeof value !== "string") return true;
+ const trimmed = normalizePathSlashes(value.trim());
+ if (!trimmed || trimmed === "/" || trimmed === ".") return true;
+ if (/^[a-zA-Z]:\/?$/.test(trimmed)) return true;
+ if (isCursorMetadataPath(trimmed)) return true;
+ if (isIdeInstallPath(trimmed)) return true;
+ return false;
+}
+function sleepMs(ms) {
+ const end = Date.now() + ms;
+ while (Date.now() < end);
+}
+function withSessionCacheLock(fn) {
+ const lockPath = `${SESSION_CACHE_PATH}.lock`;
+ mkdirSync(dirname(SESSION_CACHE_PATH), { recursive: true });
+ let fd;
+ for (let i = 0; i < 50; i++) try {
+ fd = openSync(lockPath, "wx");
+ break;
+ } catch {
+ sleepMs(10);
+ }
+ if (fd === void 0) return void 0;
+ try {
+ return fn();
+ } finally {
+ closeSync(fd);
+ try {
+ unlinkSync(lockPath);
+ } catch {}
+ }
+}
+function loadSessionCache() {
+ try {
+ const value = JSON.parse(readFileSync(SESSION_CACHE_PATH, "utf-8"));
+ return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+ } catch {
+ return {};
+ }
+}
+function pruneSessionCache(cache, now) {
+ const fresh = Object.entries(cache).filter(([, entry]) => {
+ const updated = Date.parse(entry?.updatedAt ?? "");
+ return typeof entry?.project === "string" && typeof entry?.cwd === "string" && Number.isFinite(updated) && now - updated < SESSION_CACHE_MAX_AGE_MS;
+ });
+ fresh.sort((a, b) => Date.parse(b[1].updatedAt) - Date.parse(a[1].updatedAt));
+ return Object.fromEntries(fresh.slice(0, SESSION_CACHE_MAX_ENTRIES));
+}
+function rememberSession(sessionId, project, cwd) {
+ if (!sessionId || !project || project === ".cursor") return;
+ withSessionCacheLock(() => {
+ try {
+ const now = Date.now();
+ const previous = loadSessionCache();
+ delete previous[sessionId];
+ const cache = pruneSessionCache({
+ [sessionId]: {
+ project,
+ cwd,
+ updatedAt: new Date(now).toISOString()
+ },
+ ...previous
+ }, now);
+ const tmp = `${SESSION_CACHE_PATH}.${process.pid}.${Date.now()}.tmp`;
+ writeFileSync(tmp, JSON.stringify(cache, null, 2));
+ renameSync(tmp, SESSION_CACHE_PATH);
+ } catch {}
+ });
+}
+function recallSession(sessionId) {
+ if (!sessionId) return null;
+ const cache = pruneSessionCache(loadSessionCache(), Date.now());
+ return Object.hasOwn(cache, sessionId) ? cache[sessionId] : null;
+}
+const SYSTEM_PATH_PREFIXES = [
+ "/usr/",
+ "/etc/",
+ "/bin/",
+ "/sbin/",
+ "/lib/",
+ "/lib64/",
+ "/opt/",
+ "/var/",
+ "/proc/",
+ "/sys/",
+ "/dev/",
+ "/run/",
+ "/boot/",
+ "/snap/",
+ "/nix/"
+];
+function isSystemPath(value) {
+ const norm = normalizePathSlashes(value);
+ const temp = normalizePathSlashes(tmpdir()).replace(/\/$/, "");
+ if (norm.startsWith(`${temp}/`)) return false;
+ return SYSTEM_PATH_PREFIXES.some((prefix) => norm.startsWith(prefix));
+}
+function isCollectablePath(value) {
+ if (typeof value !== "string" || isCursorMetadataPath(value)) return false;
+ if (pathUnderHome(value)) return true;
+ if (/^[a-zA-Z]:[\\/]/.test(value)) return true;
+ if (value.startsWith("/")) return !isSystemPath(value);
+ return false;
+}
+function collectPathStrings(value, out = []) {
+ if (typeof value === "string") {
+ if (isCollectablePath(value)) out.push(value);
+ return out;
+ }
+ if (Array.isArray(value)) {
+ for (const item of value) collectPathStrings(item, out);
+ return out;
+ }
+ if (value && typeof value === "object") for (const v of Object.values(value)) collectPathStrings(v, out);
+ return out;
+}
+function pathExists(pathValue) {
+ if (existsSync(pathValue)) return true;
+ if (process.platform === "win32") {
+ const native = pathValue.replace(/\//g, "\\");
+ if (native !== pathValue && existsSync(native)) return true;
+ }
+ return false;
+}
+const MAX_ANCESTOR_STEPS = 64;
+function existingAncestor(pathValue) {
+ let current = pathValue;
+ for (let step = 0; step < MAX_ANCESTOR_STEPS; step++) {
+ if (!current || current === HOME || current === "/") return null;
+ if (pathExists(current)) {
+ const resolved = process.platform === "win32" ? current.replace(/\//g, "\\") : current;
+ try {
+ if (statSync(resolved).isFile()) return dirname(resolved);
+ } catch {}
+ return resolved;
+ }
+ const parent = dirname(current);
+ if (parent === current) return null;
+ current = parent;
+ }
+ return null;
+}
+function gitRootFromPath(targetPath) {
+ return execSync("git rev-parse --show-toplevel", {
+ cwd: targetPath,
+ encoding: "utf-8",
+ stdio: [
+ "ignore",
+ "pipe",
+ "ignore"
+ ],
+ timeout: 500
+ }).trim();
+}
+function gitRootNearby(startPath) {
+ let current = startPath;
+ for (let step = 0; step < MAX_ANCESTOR_STEPS; step++) {
+ if (!current || current === "/") return null;
+ if (pathExists(join(current, ".git"))) return current;
+ const parent = dirname(current);
+ if (parent === current) return null;
+ current = parent;
+ }
+ return null;
+}
+function projectFromPath(targetPath) {
+ try {
+ return {
+ name: resolveProject(gitRootFromPath(targetPath)),
+ fromGitRoot: true
+ };
+ } catch {
+ return {
+ name: resolveProject(targetPath),
+ fromGitRoot: false
+ };
+ }
+}
+function decodeSlugCandidates(slug) {
+ if (!slug || slug === "empty-window") return [];
+ if (/^\d{10,}$/.test(slug)) return [];
+ const parts = slug.split("-");
+ if (!parts.length) return [];
+ const results = /* @__PURE__ */ new Set();
+ function walk(index, currentPath) {
+ if (index >= parts.length) {
+ results.add(currentPath);
+ return;
+ }
+ for (let take = 1; index + take <= parts.length; take++) {
+ const next = `${currentPath}/${parts.slice(index, index + take).join("-")}`;
+ if (!pathExists(next)) continue;
+ walk(index + take, next);
+ }
+ }
+ const first = parts[0];
+ if (first && /^[a-zA-Z]$/.test(first)) walk(1, `${first.toUpperCase()}:`);
+ walk(0, "");
+ return [...results];
+}
+function pickBestCandidate(candidates, preferredLabel) {
+ if (!candidates.length) return null;
+ if (preferredLabel) {
+ const labelMatch = candidates.find((p) => basename(p) === preferredLabel);
+ if (labelMatch) return labelMatch;
+ }
+ const gitRoots = [];
+ for (const candidate of candidates) try {
+ gitRoots.push(gitRootFromPath(candidate));
+ } catch {}
+ const uniqueGitRoots = [...new Set(gitRoots)];
+ if (uniqueGitRoots.length === 1) return uniqueGitRoots[0] ?? null;
+ return candidates.sort((a, b) => b.length - a.length)[0] ?? null;
+}
+function findSessionTranscript(sessionId) {
+ if (!sessionId || !existsSync(CURSOR_PROJECTS_DIR)) return null;
+ for (const slug of readdirSync(CURSOR_PROJECTS_DIR)) {
+ const transcriptsRoot = join(CURSOR_PROJECTS_DIR, slug, "agent-transcripts");
+ if (!existsSync(transcriptsRoot)) continue;
+ for (const entry of readdirSync(transcriptsRoot)) if (entry === sessionId || entry.startsWith(`${sessionId}-`)) {
+ const transcriptFile = join(transcriptsRoot, entry, `${entry}.jsonl`);
+ return {
+ slug,
+ transcriptFile: existsSync(transcriptFile) ? transcriptFile : null
+ };
+ }
+ }
+ return null;
+}
+const TRANSCRIPT_SCAN_BYTES = 25e4;
+const TRANSCRIPT_CANDIDATE_LIMIT = 120;
+const TRANSCRIPT_MATCH_LIMIT = 4e3;
+const TRANSCRIPT_MIN_VOTES = 3;
+const TRANSCRIPT_PATH_PATTERNS = [/[a-zA-Z]:[A-Za-z0-9._@+\-/]{3,240}/g, /\/[A-Za-z0-9._@+\-/]{3,240}/g];
+function workspaceFromTranscriptFile(transcriptFile) {
+ if (!transcriptFile || !existsSync(transcriptFile)) return null;
+ let chunk;
+ const fd = openSync(transcriptFile, "r");
+ try {
+ const buffer = Buffer.alloc(TRANSCRIPT_SCAN_BYTES);
+ const bytes = readSync(fd, buffer, 0, buffer.length, 0);
+ chunk = normalizePathSlashes(buffer.subarray(0, bytes).toString("utf8"));
+ } finally {
+ closeSync(fd);
+ }
+ const counts = /* @__PURE__ */ new Map();
+ const seen = /* @__PURE__ */ new Set();
+ for (const pattern of TRANSCRIPT_PATH_PATTERNS) {
+ pattern.lastIndex = 0;
+ let match;
+ let scanned = 0;
+ while ((match = pattern.exec(chunk)) !== null) {
+ if (++scanned > TRANSCRIPT_MATCH_LIMIT) break;
+ if (seen.size >= TRANSCRIPT_CANDIDATE_LIMIT) break;
+ const value = match[0];
+ if (seen.has(value)) continue;
+ seen.add(value);
+ if (value.startsWith("//")) continue;
+ if (isCursorMetadataPath(value) || isIdeInstallPath(value) || isSystemPath(value)) continue;
+ const existing = existingDirectory(value);
+ if (!existing || existing === HOME || isBadPath(existing)) continue;
+ const root = gitRootNearby(existing);
+ if (!root || root === HOME || isBadPath(root)) continue;
+ counts.set(root, (counts.get(root) || 0) + 1);
+ }
+ }
+ let best = null;
+ let bestCount = 0;
+ for (const [pathValue, count] of counts) if (count > bestCount) {
+ best = pathValue;
+ bestCount = count;
+ }
+ return bestCount >= TRANSCRIPT_MIN_VOTES ? best : null;
+}
+function workspaceFromSessionId(sessionId) {
+ const hit = findSessionTranscript(sessionId);
+ if (!hit) return null;
+ const preferredLabel = process.env["CURSOR_WORKSPACE_LABEL"] || "";
+ const fromSlug = pickBestCandidate(decodeSlugCandidates(hit.slug), preferredLabel);
+ if (fromSlug) return fromSlug;
+ return workspaceFromTranscriptFile(hit.transcriptFile);
+}
+function readHookStdinComplete(maxWaitMs = 3e4) {
+ return new Promise((resolve) => {
+ let input = "";
+ let done = false;
+ const finish = () => {
+ if (done) return;
+ done = true;
+ try {
+ process.stdin.destroy();
+ } catch {}
+ resolve(input);
+ };
+ const t = setTimeout(finish, maxWaitMs);
+ if (t.unref) t.unref();
+ process.stdin.on("data", (c) => {
+ input += c;
+ });
+ process.stdin.on("end", () => {
+ clearTimeout(t);
+ finish();
+ });
+ process.stdin.on("error", () => {
+ clearTimeout(t);
+ finish();
+ });
+ });
+}
+function writeHookPayloadTemp(input) {
+ mkdirSync(HOOK_PAYLOAD_DIR, { recursive: true });
+ try {
+ chmodSync(HOOK_PAYLOAD_DIR, 448);
+ } catch {}
+ const path = join(HOOK_PAYLOAD_DIR, `am-hook-${process.pid}-${Date.now()}.json`);
+ writeFileSync(path, input, {
+ encoding: "utf-8",
+ mode: 384
+ });
+ return path;
+}
+function readWorkerHookPayload() {
+ const file = process.env["AM_HOOK_INPUT_FILE"];
+ if (!file) {
+ console.error("[agentmemory] missing AM_HOOK_INPUT_FILE in worker");
+ return null;
+ }
+ try {
+ const raw = readFileSync(file, "utf-8");
+ const value = JSON.parse(raw);
+ return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+ } catch (err) {
+ console.error("[agentmemory] failed to parse hook payload:", err.message);
+ return null;
+ } finally {
+ try {
+ unlinkSync(file);
+ } catch {}
+ }
+}
+function isMetadataProject(project) {
+ return project.name.startsWith(".") && !project.fromGitRoot;
+}
+function isHomeDirectory(pathValue) {
+ return normalizePathSlashes(pathValue) === normalizePathSlashes(HOME);
+}
+function existingDirectory(pathValue) {
+ if (!pathExists(pathValue)) return null;
+ const resolved = process.platform === "win32" ? pathValue.replace(/\//g, "\\") : pathValue;
+ try {
+ return statSync(resolved).isFile() ? dirname(resolved) : resolved;
+ } catch {
+ return null;
+ }
+}
+function resolveFromPathCandidates(candidates, sessionId, options = {}) {
+ for (const candidate of candidates) {
+ if (typeof candidate !== "string" || isBadPath(candidate)) continue;
+ const existing = options.exact ? existingDirectory(candidate) : existingAncestor(candidate);
+ if (!existing || isBadPath(existing)) continue;
+ const project = projectFromPath(existing);
+ if (isHomeDirectory(existing) && !project.fromGitRoot) continue;
+ if (!isMetadataProject(project)) {
+ if (options.remember !== false) rememberSession(sessionId, project.name, existing);
+ return {
+ project: project.name,
+ cwd: existing
+ };
+ }
+ }
+ return null;
+}
+function debugLayer(layer, result) {
+ if (result && process.env["AM_CURSOR_DEBUG"] === "1") console.error(`[agentmemory] workspace resolved by ${layer}: ${result.project} (${result.cwd})`);
+ return result;
+}
+function resolveWorkspace(data) {
+ const sessionId = [
+ data?.["session_id"],
+ data?.["sessionId"],
+ data?.["conversation_id"]
+ ].find((value) => typeof value === "string" && Boolean(value.trim()));
+ const cached = recallSession(sessionId);
+ if (cached?.cwd && !isBadPath(cached.cwd) && existingDirectory(cached.cwd)) return {
+ project: resolveProject(cached.cwd),
+ cwd: cached.cwd
+ };
+ const fromPayload = debugLayer("payload", resolveFromPathCandidates([
+ ...Array.isArray(data?.["workspace_roots"]) ? data["workspace_roots"] : [],
+ ...Array.isArray(data?.["workspace_folders"]) ? data["workspace_folders"] : [],
+ data?.["workspace_folder"],
+ data?.["workspaceFolder"],
+ data?.["workspace"],
+ data?.["cwd"],
+ data?.["root_path"],
+ data?.["project_path"]
+ ], sessionId));
+ if (fromPayload) return fromPayload;
+ const fromTools = debugLayer("tool_input", resolveFromPathCandidates(collectPathStrings(data?.["tool_input"] ?? data?.["toolArgs"]).map(existingDirectory).filter((p) => Boolean(p) && !isIdeInstallPath(p)), sessionId));
+ if (fromTools) return fromTools;
+ if (sessionId) {
+ const fromDb = debugLayer("cursor-db", resolveFromPathCandidates([workspaceFromCursorDb(sessionId)], sessionId, { exact: true }));
+ if (fromDb) return fromDb;
+ const fromSession = debugLayer("transcript-dir", resolveFromPathCandidates([workspaceFromSessionId(sessionId)], sessionId, { exact: true }));
+ if (fromSession) return fromSession;
+ }
+ const fromEnv = debugLayer("env", resolveFromPathCandidates([
+ process.env["CURSOR_PROJECT_DIR"],
+ process.env["CURSOR_WORKSPACE_ROOT"],
+ process.env["CURSOR_WORKSPACE_FOLDER"]
+ ], sessionId));
+ if (fromEnv) return fromEnv;
+ const fromLaunch = debugLayer("launch-env", resolveFromPathCandidates([process.env["PWD"], process.env["VSCODE_CWD"]], sessionId, { remember: false }));
+ if (fromLaunch) return fromLaunch;
+ const label = process.env["CURSOR_WORKSPACE_LABEL"];
+ if (label) return {
+ project: label,
+ cwd: label
+ };
+ return {
+ project: "unknown-project",
+ cwd: "unknown-project"
+ };
+}
+//#endregion
+//#region src/hooks/cursor/delegate.ts
+const HOOK_MAP = {
+ sessionStart: "session-start.mjs",
+ beforeSubmitPrompt: "prompt-submit.mjs",
+ preToolUse: "pre-tool-use.mjs",
+ postToolUse: "post-tool-use.mjs",
+ postToolUseFailure: "post-tool-failure.mjs",
+ preCompact: "pre-compact.mjs",
+ subagentStart: "subagent-start.mjs",
+ subagentStop: "subagent-stop.mjs",
+ stop: "stop.mjs",
+ sessionEnd: "session-end.mjs"
+};
+function isCursorHookKey(value) {
+ return typeof value === "string" && Object.hasOwn(HOOK_MAP, value);
+}
+const SLOW_HOOKS = new Set(["stop", "sessionEnd"]);
+function defaultOfficialDir() {
+ return join(dirname(fileURLToPath(import.meta.url)), "..");
+}
+function enrichPayload(data) {
+ const { project: resolvedProject, cwd } = resolveWorkspace(data);
+ const project = process.env["AGENTMEMORY_PROJECT_NAME"]?.trim() || resolvedProject;
+ return {
+ project,
+ payload: {
+ ...data,
+ session_id: data["session_id"] ?? data["sessionId"] ?? data["conversation_id"],
+ cwd,
+ project
+ }
+ };
+}
+function delegateHook(hookKey, data, options = {}) {
+ const script = HOOK_MAP[hookKey];
+ const scriptPath = join(options.officialDir ?? defaultOfficialDir(), script);
+ if (!existsSync(scriptPath)) {
+ console.error(`[agentmemory] cursor hook "${hookKey}": canonical hook not found at ${scriptPath}. Run \`npm run build\` in the agentmemory checkout.`);
+ return 0;
+ }
+ const { project, payload } = enrichPayload(data);
+ const child = spawnSync(process.execPath, [scriptPath], {
+ input: JSON.stringify(payload),
+ env: {
+ ...process.env,
+ AGENTMEMORY_PROJECT_NAME: project
+ },
+ encoding: "utf-8",
+ maxBuffer: 10 * 1024 * 1024,
+ timeout: SLOW_HOOKS.has(hookKey) ? 18e4 : 3e4
+ });
+ if (child.stdout) process.stdout.write(child.stdout);
+ if (child.stderr) process.stderr.write(child.stderr);
+ if (child.error) {
+ console.error(`[agentmemory] cursor hook "${hookKey}" could not run ${script}: ${child.error.message}`);
+ return 0;
+ }
+ if (child.signal) {
+ console.error(`[agentmemory] cursor hook "${hookKey}" (${script}) was killed by ${child.signal} -- treating as no-op`);
+ return 0;
+ }
+ return child.status ?? 0;
+}
+//#endregion
+//#region src/hooks/cursor/run-detached.ts
+const IS_WORKER = process.env["AM_HOOK_WORKER"] === "1";
+const hookKey = process.argv[2];
+function runWorker() {
+ const watchdog = setTimeout(() => process.exit(0), hookKey === "sessionEnd" ? 25e4 : 13e4);
+ try {
+ const data = readWorkerHookPayload();
+ if (!data || !isCursorHookKey(hookKey)) return;
+ delegateHook(hookKey, data);
+ } finally {
+ clearTimeout(watchdog);
+ process.exit(0);
+ }
+}
+async function runParent() {
+ if (!isCursorHookKey(hookKey)) process.exit(0);
+ const payloadFile = writeHookPayloadTemp(await readHookStdinComplete());
+ const child = spawn(process.execPath, [fileURLToPath(import.meta.url), hookKey], {
+ detached: true,
+ stdio: "ignore",
+ windowsHide: true,
+ env: {
+ ...process.env,
+ AM_HOOK_WORKER: "1",
+ AM_HOOK_INPUT_FILE: payloadFile
+ }
+ });
+ child.unref();
+ const bail = setTimeout(() => process.exit(0), 2e3);
+ if (bail.unref) bail.unref();
+ child.on("spawn", () => process.exit(0));
+ child.on("error", (err) => {
+ console.error("[agentmemory] failed to spawn detached hook worker:", err.message);
+ try {
+ unlinkSync(payloadFile);
+ } catch {}
+ process.exit(0);
+ });
+}
+if (IS_WORKER) runWorker();
+else runParent().catch(() => process.exit(0));
+//#endregion
+export {};
+
+//# sourceMappingURL=run-detached.mjs.map
\ No newline at end of file
diff --git a/plugin/scripts/cursor/run-hook.mjs b/plugin/scripts/cursor/run-hook.mjs
new file mode 100755
index 00000000..cad1c049
--- /dev/null
+++ b/plugin/scripts/cursor/run-hook.mjs
@@ -0,0 +1,704 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { execSync, spawnSync } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir, tmpdir } from "node:os";
+//#region src/hooks/_project.ts
+function resolveProject(cwd) {
+ const explicit = process.env["AGENTMEMORY_PROJECT_NAME"];
+ if (explicit && explicit.trim()) return explicit.trim();
+ const dir = cwd && cwd.trim() ? cwd : process.cwd();
+ try {
+ const [top, gitDir, commonDir] = execSync("git rev-parse --show-toplevel --git-dir --git-common-dir", {
+ cwd: dir,
+ stdio: [
+ "ignore",
+ "pipe",
+ "ignore"
+ ],
+ timeout: 500
+ }).toString().trim().split(/\r?\n/);
+ if (top) return basename(repositoryRoot(dir, top, gitDir, commonDir));
+ } catch {}
+ return basename(dir);
+}
+function repositoryRoot(dir, top, gitDir, commonDir) {
+ if (!gitDir || !commonDir) return top;
+ const physical = realpathSync(dir);
+ const common = resolve(physical, commonDir);
+ if (resolve(physical, gitDir) === common || basename(common) !== ".git") return top;
+ return dirname(common);
+}
+//#endregion
+//#region src/hooks/cursor/cursor-db.ts
+/**
+* Exact session -> workspace lookup from Cursor's own SQLite storage.
+*
+* Everything else in the resolver infers the workspace: from payload fields
+* Cursor may or may not send, from paths that happen to appear in tool
+* arguments, from a transcript directory name whose path separators have been
+* flattened into hyphens. Those work, but they are inference, and inference
+* that lands on the wrong project writes a user's memories into the wrong
+* place without ever reporting an error.
+*
+* Cursor knows the answer exactly, and stores it. The layout (reverse
+* engineered; see integrations/cursor/README.md for the full picture):
+*
+* <userdir>/globalStorage/state.vscdb
+* ItemTable["composer.composerHeaders"]
+* -> { allComposers: [ { composerId, workspaceIdentifier: {
+* id, uri: { fsPath, ... } } } ] }
+*
+* A Cursor hook's `session_id` is the `composerId`, so one indexed lookup
+* gives the workspace path with no guessing.
+*
+* Two things stop this from being the only strategy:
+*
+* - Cursor 3.0 (April 2026) moved this index from per-workspace databases
+* into the global one, and the migration is lazy: a workspace migrates
+* when it is next opened. Machines still on <=2.6, or with workspaces not
+* opened since the upgrade, keep the old per-workspace `allComposers`
+* array instead. Both shapes are handled below.
+* - Reading SQLite needs a driver. `node:sqlite` only exists from Node 22.5,
+* and this package supports Node >=20. better-sqlite3 is an optional
+* dependency of the daemon, not something a hook can count on.
+*
+* So every failure path here returns null and the caller falls back to
+* inference. This module is an accuracy upgrade, never a requirement.
+*/
+const require = createRequire(import.meta.url);
+let driverCache;
+let warningFilterInstalled = false;
+function suppressSqliteExperimentalWarning() {
+ if (warningFilterInstalled) return;
+ warningFilterInstalled = true;
+ const previous = process.listeners("warning");
+ process.removeAllListeners("warning");
+ process.on("warning", (warning) => {
+ if (warning.name === "ExperimentalWarning" && /sqlite/i.test(warning.message)) return;
+ for (const listener of previous) listener(warning);
+ });
+}
+function requireQuietly(id) {
+ suppressSqliteExperimentalWarning();
+ try {
+ return require(id);
+ } catch {
+ return null;
+ }
+}
+function loadDriver() {
+ if (driverCache !== void 0) return driverCache;
+ const nodeSqlite = requireQuietly("node:sqlite");
+ if (nodeSqlite?.DatabaseSync) {
+ driverCache = { open: (path) => new nodeSqlite.DatabaseSync(path, { readOnly: true }) };
+ return driverCache;
+ }
+ const better = requireQuietly("better-sqlite3");
+ if (better) {
+ driverCache = { open: (path) => new better(path, {
+ readonly: true,
+ fileMustExist: true
+ }) };
+ return driverCache;
+ }
+ driverCache = null;
+ return driverCache;
+}
+/** Read one ItemTable value. Returns null for any failure, including a locked DB. */
+function readItemTableValue(dbPath, key) {
+ if (!existsSync(dbPath)) return null;
+ const driver = loadDriver();
+ if (!driver) return null;
+ let db = null;
+ try {
+ db = driver.open(dbPath);
+ const value = db.prepare("SELECT value FROM ItemTable WHERE key = ?").get(key)?.value;
+ if (typeof value === "string") return value;
+ if (value instanceof Uint8Array) return Buffer.from(value).toString("utf-8");
+ return null;
+ } catch {
+ return null;
+ } finally {
+ try {
+ db?.close();
+ } catch {}
+ }
+}
+function cursorStorageRoots() {
+ const home = homedir();
+ const bases = [];
+ if (process.platform === "win32") {
+ const appData = process.env["APPDATA"];
+ if (appData) bases.push(join(appData, "Cursor", "User"));
+ bases.push(join(home, "AppData", "Roaming", "Cursor", "User"));
+ } else if (process.platform === "darwin") bases.push(join(home, "Library", "Application Support", "Cursor", "User"));
+ else {
+ const configHome = process.env["XDG_CONFIG_HOME"];
+ if (configHome) bases.push(join(configHome, "Cursor", "User"));
+ bases.push(join(home, ".config", "Cursor", "User"));
+ }
+ for (const base of bases) {
+ const globalStorage = join(base, "globalStorage");
+ if (existsSync(globalStorage)) return {
+ globalStorage,
+ workspaceStorage: join(base, "workspaceStorage")
+ };
+ }
+ return null;
+}
+function fsPathFromHeader(header) {
+ const uri = header?.workspaceIdentifier?.uri;
+ const value = uri?.fsPath ?? uri?.path;
+ return typeof value === "string" && value.trim() ? value : null;
+}
+/** Cursor 3.0+: one central index in the global database. */
+function fromGlobalIndex(sessionId, roots) {
+ const raw = readItemTableValue(join(roots.globalStorage, "state.vscdb"), "composer.composerHeaders");
+ if (!raw) return null;
+ try {
+ const hit = JSON.parse(raw).allComposers?.find((c) => c?.composerId === sessionId);
+ return fsPathFromHeader(hit);
+ } catch {
+ return null;
+ }
+}
+/** `{"folder":"file:///d%3A/repo"}`, or a vscode-remote:// URI we cannot map. */
+function folderFromWorkspaceJson(workspaceDir) {
+ const file = join(workspaceDir, "workspace.json");
+ if (!existsSync(file)) return null;
+ try {
+ const folder = JSON.parse(readFileSync(file, "utf-8")).folder;
+ if (typeof folder !== "string" || !folder.startsWith("file://")) return null;
+ return fileURLToPath(folder);
+ } catch {
+ return null;
+ }
+}
+const LEGACY_SCAN_LIMIT = 40;
+function fromLegacyWorkspaceDbs(sessionId, roots) {
+ if (!existsSync(roots.workspaceStorage)) return null;
+ let dirs;
+ try {
+ dirs = readdirSync(roots.workspaceStorage).map((dir) => {
+ try {
+ return {
+ dir,
+ mtime: statSync(join(roots.workspaceStorage, dir, "state.vscdb")).mtimeMs
+ };
+ } catch {
+ return null;
+ }
+ }).filter((x) => x !== null).sort((a, b) => b.mtime - a.mtime).slice(0, LEGACY_SCAN_LIMIT);
+ } catch {
+ return null;
+ }
+ for (const { dir } of dirs) {
+ const raw = readItemTableValue(join(roots.workspaceStorage, dir, "state.vscdb"), "composer.composerData");
+ if (!raw) continue;
+ try {
+ const parsed = JSON.parse(raw);
+ if (!Array.isArray(parsed.allComposers)) continue;
+ if (!parsed.allComposers.some((c) => c?.composerId === sessionId)) continue;
+ return folderFromWorkspaceJson(join(roots.workspaceStorage, dir));
+ } catch {
+ continue;
+ }
+ }
+ return null;
+}
+/**
+* The workspace directory Cursor recorded for this session, or null when it
+* cannot be determined (no driver, no storage, workspace-less window, or a
+* remote URI that does not map to a local path).
+*/
+function workspaceFromCursorDb(sessionId) {
+ if (!sessionId) return null;
+ const roots = cursorStorageRoots();
+ if (!roots) return null;
+ return fromGlobalIndex(sessionId, roots) ?? fromLegacyWorkspaceDbs(sessionId, roots);
+}
+//#endregion
+//#region src/hooks/cursor/workspace.ts
+const HOME = homedir();
+const CURSOR_PROJECTS_DIR = join(HOME, ".cursor", "projects");
+const SESSION_CACHE_PATH = join(HOME, ".cursor", "hooks", ".agentmemory-session-cache.json");
+join(HOME, ".cursor", "hooks", ".am-hook-payloads");
+const SESSION_CACHE_MAX_AGE_MS = 10080 * 60 * 1e3;
+const SESSION_CACHE_MAX_ENTRIES = 200;
+function normalizePathSlashes(value) {
+ return String(value).replace(/\\/g, "/");
+}
+function isCursorMetadataPath(value) {
+ if (!value || typeof value !== "string") return false;
+ const trimmed = normalizePathSlashes(value.trim());
+ if (trimmed === ".cursor") return true;
+ if (/(^|\/)\.cursor\/worktrees\/[^/]/.test(trimmed)) return false;
+ return /(^|\/)\.cursor(\/|$)/.test(trimmed);
+}
+function pathUnderHome(value) {
+ if (typeof value !== "string") return false;
+ const homeNorm = normalizePathSlashes(HOME);
+ const valueNorm = normalizePathSlashes(value);
+ return valueNorm === homeNorm || valueNorm.startsWith(`${homeNorm}/`);
+}
+function isIdeInstallPath(value) {
+ if (!value || typeof value !== "string") return false;
+ const norm = normalizePathSlashes(value).toLowerCase();
+ return /(^|[\\/])(programs|program files|program files \(x86\))[\\/]cursor([\\/]|$)/i.test(norm) || /cursor\.app[\\/]contents/i.test(norm) || /(^|[\\/])microsoft vs code[\\/]resources[\\/]app([\\/]|$)/i.test(norm);
+}
+function isBadPath(value) {
+ if (!value || typeof value !== "string") return true;
+ const trimmed = normalizePathSlashes(value.trim());
+ if (!trimmed || trimmed === "/" || trimmed === ".") return true;
+ if (/^[a-zA-Z]:\/?$/.test(trimmed)) return true;
+ if (isCursorMetadataPath(trimmed)) return true;
+ if (isIdeInstallPath(trimmed)) return true;
+ return false;
+}
+function sleepMs(ms) {
+ const end = Date.now() + ms;
+ while (Date.now() < end);
+}
+function withSessionCacheLock(fn) {
+ const lockPath = `${SESSION_CACHE_PATH}.lock`;
+ mkdirSync(dirname(SESSION_CACHE_PATH), { recursive: true });
+ let fd;
+ for (let i = 0; i < 50; i++) try {
+ fd = openSync(lockPath, "wx");
+ break;
+ } catch {
+ sleepMs(10);
+ }
+ if (fd === void 0) return void 0;
+ try {
+ return fn();
+ } finally {
+ closeSync(fd);
+ try {
+ unlinkSync(lockPath);
+ } catch {}
+ }
+}
+function loadSessionCache() {
+ try {
+ const value = JSON.parse(readFileSync(SESSION_CACHE_PATH, "utf-8"));
+ return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+ } catch {
+ return {};
+ }
+}
+function pruneSessionCache(cache, now) {
+ const fresh = Object.entries(cache).filter(([, entry]) => {
+ const updated = Date.parse(entry?.updatedAt ?? "");
+ return typeof entry?.project === "string" && typeof entry?.cwd === "string" && Number.isFinite(updated) && now - updated < SESSION_CACHE_MAX_AGE_MS;
+ });
+ fresh.sort((a, b) => Date.parse(b[1].updatedAt) - Date.parse(a[1].updatedAt));
+ return Object.fromEntries(fresh.slice(0, SESSION_CACHE_MAX_ENTRIES));
+}
+function rememberSession(sessionId, project, cwd) {
+ if (!sessionId || !project || project === ".cursor") return;
+ withSessionCacheLock(() => {
+ try {
+ const now = Date.now();
+ const previous = loadSessionCache();
+ delete previous[sessionId];
+ const cache = pruneSessionCache({
+ [sessionId]: {
+ project,
+ cwd,
+ updatedAt: new Date(now).toISOString()
+ },
+ ...previous
+ }, now);
+ const tmp = `${SESSION_CACHE_PATH}.${process.pid}.${Date.now()}.tmp`;
+ writeFileSync(tmp, JSON.stringify(cache, null, 2));
+ renameSync(tmp, SESSION_CACHE_PATH);
+ } catch {}
+ });
+}
+function recallSession(sessionId) {
+ if (!sessionId) return null;
+ const cache = pruneSessionCache(loadSessionCache(), Date.now());
+ return Object.hasOwn(cache, sessionId) ? cache[sessionId] : null;
+}
+const SYSTEM_PATH_PREFIXES = [
+ "/usr/",
+ "/etc/",
+ "/bin/",
+ "/sbin/",
+ "/lib/",
+ "/lib64/",
+ "/opt/",
+ "/var/",
+ "/proc/",
+ "/sys/",
+ "/dev/",
+ "/run/",
+ "/boot/",
+ "/snap/",
+ "/nix/"
+];
+function isSystemPath(value) {
+ const norm = normalizePathSlashes(value);
+ const temp = normalizePathSlashes(tmpdir()).replace(/\/$/, "");
+ if (norm.startsWith(`${temp}/`)) return false;
+ return SYSTEM_PATH_PREFIXES.some((prefix) => norm.startsWith(prefix));
+}
+function isCollectablePath(value) {
+ if (typeof value !== "string" || isCursorMetadataPath(value)) return false;
+ if (pathUnderHome(value)) return true;
+ if (/^[a-zA-Z]:[\\/]/.test(value)) return true;
+ if (value.startsWith("/")) return !isSystemPath(value);
+ return false;
+}
+function collectPathStrings(value, out = []) {
+ if (typeof value === "string") {
+ if (isCollectablePath(value)) out.push(value);
+ return out;
+ }
+ if (Array.isArray(value)) {
+ for (const item of value) collectPathStrings(item, out);
+ return out;
+ }
+ if (value && typeof value === "object") for (const v of Object.values(value)) collectPathStrings(v, out);
+ return out;
+}
+function pathExists(pathValue) {
+ if (existsSync(pathValue)) return true;
+ if (process.platform === "win32") {
+ const native = pathValue.replace(/\//g, "\\");
+ if (native !== pathValue && existsSync(native)) return true;
+ }
+ return false;
+}
+const MAX_ANCESTOR_STEPS = 64;
+function existingAncestor(pathValue) {
+ let current = pathValue;
+ for (let step = 0; step < MAX_ANCESTOR_STEPS; step++) {
+ if (!current || current === HOME || current === "/") return null;
+ if (pathExists(current)) {
+ const resolved = process.platform === "win32" ? current.replace(/\//g, "\\") : current;
+ try {
+ if (statSync(resolved).isFile()) return dirname(resolved);
+ } catch {}
+ return resolved;
+ }
+ const parent = dirname(current);
+ if (parent === current) return null;
+ current = parent;
+ }
+ return null;
+}
+function gitRootFromPath(targetPath) {
+ return execSync("git rev-parse --show-toplevel", {
+ cwd: targetPath,
+ encoding: "utf-8",
+ stdio: [
+ "ignore",
+ "pipe",
+ "ignore"
+ ],
+ timeout: 500
+ }).trim();
+}
+function gitRootNearby(startPath) {
+ let current = startPath;
+ for (let step = 0; step < MAX_ANCESTOR_STEPS; step++) {
+ if (!current || current === "/") return null;
+ if (pathExists(join(current, ".git"))) return current;
+ const parent = dirname(current);
+ if (parent === current) return null;
+ current = parent;
+ }
+ return null;
+}
+function projectFromPath(targetPath) {
+ try {
+ return {
+ name: resolveProject(gitRootFromPath(targetPath)),
+ fromGitRoot: true
+ };
+ } catch {
+ return {
+ name: resolveProject(targetPath),
+ fromGitRoot: false
+ };
+ }
+}
+function decodeSlugCandidates(slug) {
+ if (!slug || slug === "empty-window") return [];
+ if (/^\d{10,}$/.test(slug)) return [];
+ const parts = slug.split("-");
+ if (!parts.length) return [];
+ const results = /* @__PURE__ */ new Set();
+ function walk(index, currentPath) {
+ if (index >= parts.length) {
+ results.add(currentPath);
+ return;
+ }
+ for (let take = 1; index + take <= parts.length; take++) {
+ const next = `${currentPath}/${parts.slice(index, index + take).join("-")}`;
+ if (!pathExists(next)) continue;
+ walk(index + take, next);
+ }
+ }
+ const first = parts[0];
+ if (first && /^[a-zA-Z]$/.test(first)) walk(1, `${first.toUpperCase()}:`);
+ walk(0, "");
+ return [...results];
+}
+function pickBestCandidate(candidates, preferredLabel) {
+ if (!candidates.length) return null;
+ if (preferredLabel) {
+ const labelMatch = candidates.find((p) => basename(p) === preferredLabel);
+ if (labelMatch) return labelMatch;
+ }
+ const gitRoots = [];
+ for (const candidate of candidates) try {
+ gitRoots.push(gitRootFromPath(candidate));
+ } catch {}
+ const uniqueGitRoots = [...new Set(gitRoots)];
+ if (uniqueGitRoots.length === 1) return uniqueGitRoots[0] ?? null;
+ return candidates.sort((a, b) => b.length - a.length)[0] ?? null;
+}
+function findSessionTranscript(sessionId) {
+ if (!sessionId || !existsSync(CURSOR_PROJECTS_DIR)) return null;
+ for (const slug of readdirSync(CURSOR_PROJECTS_DIR)) {
+ const transcriptsRoot = join(CURSOR_PROJECTS_DIR, slug, "agent-transcripts");
+ if (!existsSync(transcriptsRoot)) continue;
+ for (const entry of readdirSync(transcriptsRoot)) if (entry === sessionId || entry.startsWith(`${sessionId}-`)) {
+ const transcriptFile = join(transcriptsRoot, entry, `${entry}.jsonl`);
+ return {
+ slug,
+ transcriptFile: existsSync(transcriptFile) ? transcriptFile : null
+ };
+ }
+ }
+ return null;
+}
+const TRANSCRIPT_SCAN_BYTES = 25e4;
+const TRANSCRIPT_CANDIDATE_LIMIT = 120;
+const TRANSCRIPT_MATCH_LIMIT = 4e3;
+const TRANSCRIPT_MIN_VOTES = 3;
+const TRANSCRIPT_PATH_PATTERNS = [/[a-zA-Z]:[A-Za-z0-9._@+\-/]{3,240}/g, /\/[A-Za-z0-9._@+\-/]{3,240}/g];
+function workspaceFromTranscriptFile(transcriptFile) {
+ if (!transcriptFile || !existsSync(transcriptFile)) return null;
+ let chunk;
+ const fd = openSync(transcriptFile, "r");
+ try {
+ const buffer = Buffer.alloc(TRANSCRIPT_SCAN_BYTES);
+ const bytes = readSync(fd, buffer, 0, buffer.length, 0);
+ chunk = normalizePathSlashes(buffer.subarray(0, bytes).toString("utf8"));
+ } finally {
+ closeSync(fd);
+ }
+ const counts = /* @__PURE__ */ new Map();
+ const seen = /* @__PURE__ */ new Set();
+ for (const pattern of TRANSCRIPT_PATH_PATTERNS) {
+ pattern.lastIndex = 0;
+ let match;
+ let scanned = 0;
+ while ((match = pattern.exec(chunk)) !== null) {
+ if (++scanned > TRANSCRIPT_MATCH_LIMIT) break;
+ if (seen.size >= TRANSCRIPT_CANDIDATE_LIMIT) break;
+ const value = match[0];
+ if (seen.has(value)) continue;
+ seen.add(value);
+ if (value.startsWith("//")) continue;
+ if (isCursorMetadataPath(value) || isIdeInstallPath(value) || isSystemPath(value)) continue;
+ const existing = existingDirectory(value);
+ if (!existing || existing === HOME || isBadPath(existing)) continue;
+ const root = gitRootNearby(existing);
+ if (!root || root === HOME || isBadPath(root)) continue;
+ counts.set(root, (counts.get(root) || 0) + 1);
+ }
+ }
+ let best = null;
+ let bestCount = 0;
+ for (const [pathValue, count] of counts) if (count > bestCount) {
+ best = pathValue;
+ bestCount = count;
+ }
+ return bestCount >= TRANSCRIPT_MIN_VOTES ? best : null;
+}
+function workspaceFromSessionId(sessionId) {
+ const hit = findSessionTranscript(sessionId);
+ if (!hit) return null;
+ const preferredLabel = process.env["CURSOR_WORKSPACE_LABEL"] || "";
+ const fromSlug = pickBestCandidate(decodeSlugCandidates(hit.slug), preferredLabel);
+ if (fromSlug) return fromSlug;
+ return workspaceFromTranscriptFile(hit.transcriptFile);
+}
+function isMetadataProject(project) {
+ return project.name.startsWith(".") && !project.fromGitRoot;
+}
+function isHomeDirectory(pathValue) {
+ return normalizePathSlashes(pathValue) === normalizePathSlashes(HOME);
+}
+function existingDirectory(pathValue) {
+ if (!pathExists(pathValue)) return null;
+ const resolved = process.platform === "win32" ? pathValue.replace(/\//g, "\\") : pathValue;
+ try {
+ return statSync(resolved).isFile() ? dirname(resolved) : resolved;
+ } catch {
+ return null;
+ }
+}
+function resolveFromPathCandidates(candidates, sessionId, options = {}) {
+ for (const candidate of candidates) {
+ if (typeof candidate !== "string" || isBadPath(candidate)) continue;
+ const existing = options.exact ? existingDirectory(candidate) : existingAncestor(candidate);
+ if (!existing || isBadPath(existing)) continue;
+ const project = projectFromPath(existing);
+ if (isHomeDirectory(existing) && !project.fromGitRoot) continue;
+ if (!isMetadataProject(project)) {
+ if (options.remember !== false) rememberSession(sessionId, project.name, existing);
+ return {
+ project: project.name,
+ cwd: existing
+ };
+ }
+ }
+ return null;
+}
+function debugLayer(layer, result) {
+ if (result && process.env["AM_CURSOR_DEBUG"] === "1") console.error(`[agentmemory] workspace resolved by ${layer}: ${result.project} (${result.cwd})`);
+ return result;
+}
+function resolveWorkspace(data) {
+ const sessionId = [
+ data?.["session_id"],
+ data?.["sessionId"],
+ data?.["conversation_id"]
+ ].find((value) => typeof value === "string" && Boolean(value.trim()));
+ const cached = recallSession(sessionId);
+ if (cached?.cwd && !isBadPath(cached.cwd) && existingDirectory(cached.cwd)) return {
+ project: resolveProject(cached.cwd),
+ cwd: cached.cwd
+ };
+ const fromPayload = debugLayer("payload", resolveFromPathCandidates([
+ ...Array.isArray(data?.["workspace_roots"]) ? data["workspace_roots"] : [],
+ ...Array.isArray(data?.["workspace_folders"]) ? data["workspace_folders"] : [],
+ data?.["workspace_folder"],
+ data?.["workspaceFolder"],
+ data?.["workspace"],
+ data?.["cwd"],
+ data?.["root_path"],
+ data?.["project_path"]
+ ], sessionId));
+ if (fromPayload) return fromPayload;
+ const fromTools = debugLayer("tool_input", resolveFromPathCandidates(collectPathStrings(data?.["tool_input"] ?? data?.["toolArgs"]).map(existingDirectory).filter((p) => Boolean(p) && !isIdeInstallPath(p)), sessionId));
+ if (fromTools) return fromTools;
+ if (sessionId) {
+ const fromDb = debugLayer("cursor-db", resolveFromPathCandidates([workspaceFromCursorDb(sessionId)], sessionId, { exact: true }));
+ if (fromDb) return fromDb;
+ const fromSession = debugLayer("transcript-dir", resolveFromPathCandidates([workspaceFromSessionId(sessionId)], sessionId, { exact: true }));
+ if (fromSession) return fromSession;
+ }
+ const fromEnv = debugLayer("env", resolveFromPathCandidates([
+ process.env["CURSOR_PROJECT_DIR"],
+ process.env["CURSOR_WORKSPACE_ROOT"],
+ process.env["CURSOR_WORKSPACE_FOLDER"]
+ ], sessionId));
+ if (fromEnv) return fromEnv;
+ const fromLaunch = debugLayer("launch-env", resolveFromPathCandidates([process.env["PWD"], process.env["VSCODE_CWD"]], sessionId, { remember: false }));
+ if (fromLaunch) return fromLaunch;
+ const label = process.env["CURSOR_WORKSPACE_LABEL"];
+ if (label) return {
+ project: label,
+ cwd: label
+ };
+ return {
+ project: "unknown-project",
+ cwd: "unknown-project"
+ };
+}
+//#endregion
+//#region src/hooks/cursor/delegate.ts
+const HOOK_MAP = {
+ sessionStart: "session-start.mjs",
+ beforeSubmitPrompt: "prompt-submit.mjs",
+ preToolUse: "pre-tool-use.mjs",
+ postToolUse: "post-tool-use.mjs",
+ postToolUseFailure: "post-tool-failure.mjs",
+ preCompact: "pre-compact.mjs",
+ subagentStart: "subagent-start.mjs",
+ subagentStop: "subagent-stop.mjs",
+ stop: "stop.mjs",
+ sessionEnd: "session-end.mjs"
+};
+function isCursorHookKey(value) {
+ return typeof value === "string" && Object.hasOwn(HOOK_MAP, value);
+}
+const SLOW_HOOKS = new Set(["stop", "sessionEnd"]);
+function defaultOfficialDir() {
+ return join(dirname(fileURLToPath(import.meta.url)), "..");
+}
+function enrichPayload(data) {
+ const { project: resolvedProject, cwd } = resolveWorkspace(data);
+ const project = process.env["AGENTMEMORY_PROJECT_NAME"]?.trim() || resolvedProject;
+ return {
+ project,
+ payload: {
+ ...data,
+ session_id: data["session_id"] ?? data["sessionId"] ?? data["conversation_id"],
+ cwd,
+ project
+ }
+ };
+}
+function delegateHook(hookKey, data, options = {}) {
+ const script = HOOK_MAP[hookKey];
+ const scriptPath = join(options.officialDir ?? defaultOfficialDir(), script);
+ if (!existsSync(scriptPath)) {
+ console.error(`[agentmemory] cursor hook "${hookKey}": canonical hook not found at ${scriptPath}. Run \`npm run build\` in the agentmemory checkout.`);
+ return 0;
+ }
+ const { project, payload } = enrichPayload(data);
+ const child = spawnSync(process.execPath, [scriptPath], {
+ input: JSON.stringify(payload),
+ env: {
+ ...process.env,
+ AGENTMEMORY_PROJECT_NAME: project
+ },
+ encoding: "utf-8",
+ maxBuffer: 10 * 1024 * 1024,
+ timeout: SLOW_HOOKS.has(hookKey) ? 18e4 : 3e4
+ });
+ if (child.stdout) process.stdout.write(child.stdout);
+ if (child.stderr) process.stderr.write(child.stderr);
+ if (child.error) {
+ console.error(`[agentmemory] cursor hook "${hookKey}" could not run ${script}: ${child.error.message}`);
+ return 0;
+ }
+ if (child.signal) {
+ console.error(`[agentmemory] cursor hook "${hookKey}" (${script}) was killed by ${child.signal} -- treating as no-op`);
+ return 0;
+ }
+ return child.status ?? 0;
+}
+//#endregion
+//#region src/hooks/cursor/run-hook.ts
+async function main() {
+ const hookKey = process.argv[2];
+ if (!isCursorHookKey(hookKey)) process.exit(0);
+ let input = "";
+ for await (const chunk of process.stdin) input += chunk;
+ if (!input.trim()) process.exit(0);
+ let data;
+ try {
+ data = JSON.parse(input);
+ } catch {
+ process.exit(0);
+ }
+ if (!data || typeof data !== "object" || Array.isArray(data)) process.exit(0);
+ process.exit(delegateHook(hookKey, data));
+}
+main().catch(() => process.exit(0));
+//#endregion
+export {};
+
+//# sourceMappingURL=run-hook.mjs.map
\ No newline at end of file
diff --git a/plugin/skills/agentmemory-agents/REFERENCE.md b/plugin/skills/agentmemory-agents/REFERENCE.md
index 9d1a9357..35075b14 100644
--- a/plugin/skills/agentmemory-agents/REFERENCE.md
+++ b/plugin/skills/agentmemory-agents/REFERENCE.md
@@ -14,7 +14,7 @@ Generated from `src/cli/connect/index.ts`. Do not edit the block below by hand;
| Codex CLI | `codex` | Using MCP. Hooks ship via the Codex plugin; on Codex Desktop, also pass --with-hooks to install the global hooks.json workaround. |
| Continue | `continue` | Using MCP via ~/.continue/config.yaml (preferred) or config.json (legacy, only when no yaml). |
| GitHub Copilot CLI | `copilot-cli` | Using MCP. Install the plugin too for full hooks/skills coverage. |
-| Cursor | `cursor` | Using MCP (the only protocol Cursor speaks). Memory bridge runs at :3111 underneath. |
+| Cursor | `cursor` | Using MCP. Lifecycle hooks ship in the Cursor plugin: Settings → Plugins → Add marketplace → this repo, then enable agentmemory. |
| Devin CLI | `devin` | Using MCP via the user config. Devin CLI migrates mcpServers into mcp_config.json on newer builds. Pass --with-hooks for native auto-capture. |
| Droid (Factory.ai) | `droid` | Using MCP via ~/.factory/mcp.json. The `/mcp` slash command inside droid lists configured servers. Pass --with-hooks to also install the native ~/.factory/hooks.json auto-capture hooks. |
| DeepSeek Harness | `dsh` | Using MCP via $DSH_HOME/cordis.patch.yml (the home-level patch layer every profile loads). Tools appear as mcp__agentmemory__*. Pass --with-hooks to also wire auto-capture with the bundled native DSH plugin. |
diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.json
index 2e5c35e5..1d459a31 100644
--- a/scripts/docs-sync.state.json
+++ b/scripts/docs-sync.state.json
@@ -20,16 +20,16 @@
"12"
],
"tests": [
- "3900+"
+ "4000+"
],
"functions": [
"324"
],
"sourceFiles": [
- "245"
+ "250"
],
"loc": [
- "57000"
+ "59000"
],
"kvScopes": [
"67"
diff --git a/src/cli/connect/cursor.ts b/src/cli/connect/cursor.ts
index fb4c5afb..642add4e 100644
--- a/src/cli/connect/cursor.ts
+++ b/src/cli/connect/cursor.ts
@@ -5,9 +5,17 @@ import { createJsonMcpAdapter } from "./json-mcp-adapter.js";
export const adapter = createJsonMcpAdapter({
name: "cursor",
displayName: "Cursor",
+ // Cursor speaks lifecycle hooks as well as MCP, so it groups with the
+ // native hosts rather than the MCP-only ones.
+ category: "native",
detectDir: join(homedir(), ".cursor"),
configPath: join(homedir(), ".cursor", "mcp.json"),
- docs: "https://github.com/rohitg00/agentmemory#other-agents",
+ docs: "https://github.com/rohitg00/agentmemory#cursor",
+ // Deliberately no --with-hooks here, unlike Codex and Claude Code. Theirs
+ // mirror the plugin's hooks into a user-scope file to work around hosts
+ // that fail to dispatch plugin-scope hooks; Cursor dispatches them fine.
+ // Writing ~/.cursor/hooks.json as well would just make both copies fire and
+ // record every observation twice.
protocolNote:
- "→ Using MCP (the only protocol Cursor speaks). Memory bridge runs at :3111 underneath.",
+ "→ Using MCP. Lifecycle hooks ship in the Cursor plugin: Settings → Plugins → Add marketplace → this repo, then enable agentmemory.",
});
diff --git a/src/hooks/cursor/cursor-db.ts b/src/hooks/cursor/cursor-db.ts
new file mode 100644
index 00000000..538886e4
--- /dev/null
+++ b/src/hooks/cursor/cursor-db.ts
@@ -0,0 +1,273 @@
+/**
+ * Exact session -> workspace lookup from Cursor's own SQLite storage.
+ *
+ * Everything else in the resolver infers the workspace: from payload fields
+ * Cursor may or may not send, from paths that happen to appear in tool
+ * arguments, from a transcript directory name whose path separators have been
+ * flattened into hyphens. Those work, but they are inference, and inference
+ * that lands on the wrong project writes a user's memories into the wrong
+ * place without ever reporting an error.
+ *
+ * Cursor knows the answer exactly, and stores it. The layout (reverse
+ * engineered; see integrations/cursor/README.md for the full picture):
+ *
+ * <userdir>/globalStorage/state.vscdb
+ * ItemTable["composer.composerHeaders"]
+ * -> { allComposers: [ { composerId, workspaceIdentifier: {
+ * id, uri: { fsPath, ... } } } ] }
+ *
+ * A Cursor hook's `session_id` is the `composerId`, so one indexed lookup
+ * gives the workspace path with no guessing.
+ *
+ * Two things stop this from being the only strategy:
+ *
+ * - Cursor 3.0 (April 2026) moved this index from per-workspace databases
+ * into the global one, and the migration is lazy: a workspace migrates
+ * when it is next opened. Machines still on <=2.6, or with workspaces not
+ * opened since the upgrade, keep the old per-workspace `allComposers`
+ * array instead. Both shapes are handled below.
+ * - Reading SQLite needs a driver. `node:sqlite` only exists from Node 22.5,
+ * and this package supports Node >=20. better-sqlite3 is an optional
+ * dependency of the daemon, not something a hook can count on.
+ *
+ * So every failure path here returns null and the caller falls back to
+ * inference. This module is an accuracy upgrade, never a requirement.
+ */
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+
+interface Statement {
+ get(...params: unknown[]): unknown;
+}
+interface DbHandle {
+ prepare(sql: string): Statement;
+ close(): void;
+}
+interface Driver {
+ open(path: string): DbHandle;
+}
+
+// `undefined` = not probed yet, `null` = probed and unavailable.
+let driverCache: Driver | null | undefined;
+
+// node:sqlite is still flagged experimental and emits a process warning on
+// load. Hook stderr is surfaced in Cursor's hook log, so that would put a
+// paragraph about an implementation detail in front of the user on every
+// session that reaches this module.
+//
+// The filter is installed once and left in place, rather than wrapped around
+// the require, because process.emitWarning defers the actual emission to the
+// next tick: restoring the original listeners in a `finally` happens before
+// the warning is ever emitted, so the wrapping approach silences nothing. It
+// is scoped as tightly as it can be -- only this one warning is dropped, and
+// everything else is re-emitted untouched.
+let warningFilterInstalled = false;
+
+function suppressSqliteExperimentalWarning(): void {
+ if (warningFilterInstalled) return;
+ warningFilterInstalled = true;
+ const previous = process.listeners("warning");
+ process.removeAllListeners("warning");
+ process.on("warning", (warning: Error) => {
+ if (warning.name === "ExperimentalWarning" && /sqlite/i.test(warning.message)) return;
+ for (const listener of previous) listener(warning);
+ });
+}
+
+function requireQuietly<T>(id: string): T | null {
+ suppressSqliteExperimentalWarning();
+ try {
+ return require(id) as T;
+ } catch {
+ return null;
+ }
+}
+
+function loadDriver(): Driver | null {
+ if (driverCache !== undefined) return driverCache;
+
+ const nodeSqlite = requireQuietly<{ DatabaseSync: new (p: string, o?: object) => DbHandle }>(
+ "node:sqlite",
+ );
+ if (nodeSqlite?.DatabaseSync) {
+ driverCache = {
+ open: (path) => new nodeSqlite.DatabaseSync(path, { readOnly: true }),
+ };
+ return driverCache;
+ }
+
+ // Same lazy-optional pattern the daemon uses for better-sqlite3 in
+ // src/functions/migrate.ts -- used when installed, never required.
+ const better = requireQuietly<new (p: string, o?: object) => DbHandle>("better-sqlite3");
+ if (better) {
+ driverCache = {
+ open: (path) => new better(path, { readonly: true, fileMustExist: true }),
+ };
+ return driverCache;
+ }
+
+ driverCache = null;
+ return driverCache;
+}
+
+/** Read one ItemTable value. Returns null for any failure, including a locked DB. */
+function readItemTableValue(dbPath: string, key: string): string | null {
+ if (!existsSync(dbPath)) return null;
+ const driver = loadDriver();
+ if (!driver) return null;
+
+ let db: DbHandle | null = null;
+ try {
+ db = driver.open(dbPath);
+ const row = db.prepare("SELECT value FROM ItemTable WHERE key = ?").get(key) as
+ | { value?: unknown }
+ | undefined;
+ const value = row?.value;
+ if (typeof value === "string") return value;
+ if (value instanceof Uint8Array) return Buffer.from(value).toString("utf-8");
+ return null;
+ } catch {
+ // Cursor holds the database open while running. Readers normally coexist
+ // fine, but a locked or half-migrated file must not break the hook.
+ return null;
+ } finally {
+ try {
+ db?.close();
+ } catch {}
+ }
+}
+
+export interface CursorStorageRoots {
+ globalStorage: string;
+ workspaceStorage: string;
+}
+
+export function cursorStorageRoots(): CursorStorageRoots | null {
+ const home = homedir();
+ const bases: string[] = [];
+ if (process.platform === "win32") {
+ const appData = process.env["APPDATA"];
+ if (appData) bases.push(join(appData, "Cursor", "User"));
+ bases.push(join(home, "AppData", "Roaming", "Cursor", "User"));
+ } else if (process.platform === "darwin") {
+ bases.push(join(home, "Library", "Application Support", "Cursor", "User"));
+ } else {
+ const configHome = process.env["XDG_CONFIG_HOME"];
+ if (configHome) bases.push(join(configHome, "Cursor", "User"));
+ bases.push(join(home, ".config", "Cursor", "User"));
+ }
+
+ for (const base of bases) {
+ const globalStorage = join(base, "globalStorage");
+ if (existsSync(globalStorage)) {
+ return { globalStorage, workspaceStorage: join(base, "workspaceStorage") };
+ }
+ }
+ return null;
+}
+
+interface ComposerHeader {
+ composerId?: unknown;
+ workspaceIdentifier?: { uri?: { fsPath?: unknown; path?: unknown } };
+}
+
+function fsPathFromHeader(header: ComposerHeader | undefined): string | null {
+ const uri = header?.workspaceIdentifier?.uri;
+ const value = uri?.fsPath ?? uri?.path;
+ return typeof value === "string" && value.trim() ? value : null;
+}
+
+/** Cursor 3.0+: one central index in the global database. */
+function fromGlobalIndex(sessionId: string, roots: CursorStorageRoots): string | null {
+ const raw = readItemTableValue(
+ join(roots.globalStorage, "state.vscdb"),
+ "composer.composerHeaders",
+ );
+ if (!raw) return null;
+ try {
+ const parsed = JSON.parse(raw) as { allComposers?: ComposerHeader[] };
+ const hit = parsed.allComposers?.find((c) => c?.composerId === sessionId);
+ // A hit with no uri is a workspace-less "empty window" chat -- Cursor
+ // genuinely has no path for it, so neither do we.
+ return fsPathFromHeader(hit);
+ } catch {
+ return null;
+ }
+}
+
+/** `{"folder":"file:///d%3A/repo"}`, or a vscode-remote:// URI we cannot map. */
+function folderFromWorkspaceJson(workspaceDir: string): string | null {
+ const file = join(workspaceDir, "workspace.json");
+ if (!existsSync(file)) return null;
+ try {
+ const parsed = JSON.parse(readFileSync(file, "utf-8")) as { folder?: unknown };
+ const folder = parsed.folder;
+ if (typeof folder !== "string" || !folder.startsWith("file://")) return null;
+ return fileURLToPath(folder);
+ } catch {
+ return null;
+ }
+}
+
+// Pre-3.0 lookup means opening one database per workspace, so it is ordered
+// by recency and capped: the workspace a live session belongs to was touched
+// moments ago and sits at the top. A full scan of ~120 workspaces measures
+// around 200ms; this ordering turns the common case into one or two opens.
+const LEGACY_SCAN_LIMIT = 40;
+
+function fromLegacyWorkspaceDbs(sessionId: string, roots: CursorStorageRoots): string | null {
+ if (!existsSync(roots.workspaceStorage)) return null;
+
+ let dirs: Array<{ dir: string; mtime: number }>;
+ try {
+ dirs = readdirSync(roots.workspaceStorage)
+ .map((dir) => {
+ try {
+ return { dir, mtime: statSync(join(roots.workspaceStorage, dir, "state.vscdb")).mtimeMs };
+ } catch {
+ return null;
+ }
+ })
+ .filter((x): x is { dir: string; mtime: number } => x !== null)
+ .sort((a, b) => b.mtime - a.mtime)
+ .slice(0, LEGACY_SCAN_LIMIT);
+ } catch {
+ return null;
+ }
+
+ for (const { dir } of dirs) {
+ const raw = readItemTableValue(
+ join(roots.workspaceStorage, dir, "state.vscdb"),
+ "composer.composerData",
+ );
+ if (!raw) continue;
+ try {
+ const parsed = JSON.parse(raw) as { allComposers?: Array<{ composerId?: unknown }> };
+ // Migrated workspaces no longer carry allComposers; their sessions are
+ // in the global index handled above.
+ if (!Array.isArray(parsed.allComposers)) continue;
+ if (!parsed.allComposers.some((c) => c?.composerId === sessionId)) continue;
+ return folderFromWorkspaceJson(join(roots.workspaceStorage, dir));
+ } catch {
+ continue;
+ }
+ }
+ return null;
+}
+
+/**
+ * The workspace directory Cursor recorded for this session, or null when it
+ * cannot be determined (no driver, no storage, workspace-less window, or a
+ * remote URI that does not map to a local path).
+ */
+export function workspaceFromCursorDb(sessionId: string): string | null {
+ if (!sessionId) return null;
+ const roots = cursorStorageRoots();
+ if (!roots) return null;
+ return fromGlobalIndex(sessionId, roots) ?? fromLegacyWorkspaceDbs(sessionId, roots);
+}
diff --git a/src/hooks/cursor/delegate.ts b/src/hooks/cursor/delegate.ts
new file mode 100644
index 00000000..c07020d6
--- /dev/null
+++ b/src/hooks/cursor/delegate.ts
@@ -0,0 +1,122 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveWorkspace } from "./workspace.js";
+
+// Cursor fires camelCase lifecycle events; each one maps to the canonical
+// hook compiled from src/hooks/*.ts. Keep this table the only place that
+// knows Cursor's naming — everything downstream is the shared hook.
+export const HOOK_MAP = {
+ sessionStart: "session-start.mjs",
+ beforeSubmitPrompt: "prompt-submit.mjs",
+ preToolUse: "pre-tool-use.mjs",
+ postToolUse: "post-tool-use.mjs",
+ postToolUseFailure: "post-tool-failure.mjs",
+ preCompact: "pre-compact.mjs",
+ subagentStart: "subagent-start.mjs",
+ subagentStop: "subagent-stop.mjs",
+ stop: "stop.mjs",
+ sessionEnd: "session-end.mjs",
+} as const;
+
+export type CursorHookKey = keyof typeof HOOK_MAP;
+
+export function isCursorHookKey(value: unknown): value is CursorHookKey {
+ return typeof value === "string" && Object.hasOwn(HOOK_MAP, value);
+}
+
+// stop/sessionEnd fan out to summarize + consolidate on the daemon side, so
+// they get a longer leash than the interactive hooks.
+const SLOW_HOOKS = new Set<CursorHookKey>(["stop", "sessionEnd"]);
+
+export type HookPayload = Record<string, unknown>;
+
+export interface DelegateOptions {
+ // Tests run against src/, where the canonical .mjs files do not sit one
+ // level up. Bundled output resolves it correctly on its own.
+ officialDir?: string;
+}
+
+// Bundled to plugin/scripts/cursor/<entry>.mjs, so the canonical hooks are
+// exactly one directory up.
+function defaultOfficialDir(): string {
+ return join(dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+export function enrichPayload(data: HookPayload): {
+ project: string;
+ payload: HookPayload;
+} {
+ const { project: resolvedProject, cwd } = resolveWorkspace(data);
+ const project = process.env["AGENTMEMORY_PROJECT_NAME"]?.trim() || resolvedProject;
+ return {
+ project,
+ payload: {
+ ...data,
+ session_id: data["session_id"] ?? data["sessionId"] ?? data["conversation_id"],
+ cwd,
+ project,
+ },
+ };
+}
+
+export function delegateHook(
+ hookKey: CursorHookKey,
+ data: HookPayload,
+ options: DelegateOptions = {},
+): number {
+ const script = HOOK_MAP[hookKey];
+ const scriptPath = join(options.officialDir ?? defaultOfficialDir(), script);
+
+ // Checked explicitly rather than left to the spawn: node starts fine and
+ // then exits 1 with a module-not-found stack, which the block below would
+ // forward as a deliberate non-zero decision from the hook, and which lands
+ // a Node stack trace in Cursor's hook log. This is a real installation
+ // state -- the plugin ships built .mjs, so a source checkout that has not
+ // run `npm run build` hits it -- and it deserves an answer the user can act
+ // on rather than a stack trace.
+ if (!existsSync(scriptPath)) {
+ console.error(
+ `[agentmemory] cursor hook "${hookKey}": canonical hook not found at ${scriptPath}.` +
+ ` Run \`npm run build\` in the agentmemory checkout.`,
+ );
+ return 0;
+ }
+
+ const { project, payload } = enrichPayload(data);
+
+ const child = spawnSync(process.execPath, [scriptPath], {
+ input: JSON.stringify(payload),
+ // resolveProject() in the canonical hooks reads this before falling back
+ // to git/cwd, which is how the Cursor-specific resolution wins.
+ env: { ...process.env, AGENTMEMORY_PROJECT_NAME: project },
+ encoding: "utf-8",
+ maxBuffer: 10 * 1024 * 1024,
+ timeout: SLOW_HOOKS.has(hookKey) ? 180000 : 30000,
+ });
+
+ if (child.stdout) process.stdout.write(child.stdout);
+ if (child.stderr) process.stderr.write(child.stderr);
+
+ // spawnSync reports a failure to launch (missing script, timeout kill) as
+ // status === null, so `status ?? 0` would announce success and lose the
+ // observation silently -- the exact failure mode that makes a memory hook
+ // untrustworthy. Say so on stderr, but still exit 0: agentmemory is a
+ // passive recorder and must never block the editor. A genuine non-zero
+ // exit from the canonical hook is a real decision and is passed through.
+ if (child.error) {
+ console.error(
+ `[agentmemory] cursor hook "${hookKey}" could not run ${script}: ${child.error.message}`,
+ );
+ return 0;
+ }
+ if (child.signal) {
+ console.error(
+ `[agentmemory] cursor hook "${hookKey}" (${script}) was killed by ${child.signal}` +
+ ` -- treating as no-op`,
+ );
+ return 0;
+ }
+ return child.status ?? 0;
+}
diff --git a/src/hooks/cursor/run-detached.ts b/src/hooks/cursor/run-detached.ts
new file mode 100644
index 00000000..79fd6be0
--- /dev/null
+++ b/src/hooks/cursor/run-detached.ts
@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { unlinkSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { delegateHook, isCursorHookKey } from "./delegate.js";
+import {
+ readHookStdinComplete,
+ readWorkerHookPayload,
+ writeHookPayloadTemp,
+} from "./workspace.js";
+
+// stop/sessionEnd trigger summarize + consolidate on the daemon. Cursor
+// kills its hook process tree when the window closes, so the real work runs
+// in a detached worker that outlives the window; the parent only hands off
+// the payload and returns control immediately.
+const IS_WORKER = process.env["AM_HOOK_WORKER"] === "1";
+const hookKey = process.argv[2];
+
+function runWorker(): void {
+ const hardLimitMs = hookKey === "sessionEnd" ? 250000 : 130000;
+ const watchdog = setTimeout(() => process.exit(0), hardLimitMs);
+
+ try {
+ const data = readWorkerHookPayload();
+ if (!data || !isCursorHookKey(hookKey)) return;
+ delegateHook(hookKey, data);
+ } finally {
+ clearTimeout(watchdog);
+ process.exit(0);
+ }
+}
+
+async function runParent(): Promise<void> {
+ if (!isCursorHookKey(hookKey)) process.exit(0);
+
+ const input = await readHookStdinComplete();
+ const payloadFile = writeHookPayloadTemp(input);
+
+ const child = spawn(process.execPath, [fileURLToPath(import.meta.url), hookKey], {
+ detached: true,
+ stdio: "ignore",
+ windowsHide: true,
+ env: {
+ ...process.env,
+ AM_HOOK_WORKER: "1",
+ AM_HOOK_INPUT_FILE: payloadFile,
+ },
+ });
+ child.unref();
+
+ const bail = setTimeout(() => process.exit(0), 2000);
+ if (bail.unref) bail.unref();
+ child.on("spawn", () => process.exit(0));
+ child.on("error", (err: Error) => {
+ console.error("[agentmemory] failed to spawn detached hook worker:", err.message);
+ try {
+ unlinkSync(payloadFile);
+ } catch {}
+ process.exit(0);
+ });
+}
+
+if (IS_WORKER) {
+ runWorker();
+} else {
+ void runParent().catch(() => process.exit(0));
+}
diff --git a/src/hooks/cursor/run-hook.ts b/src/hooks/cursor/run-hook.ts
new file mode 100644
index 00000000..5b4416fb
--- /dev/null
+++ b/src/hooks/cursor/run-hook.ts
@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { delegateHook, isCursorHookKey, type HookPayload } from "./delegate.js";
+
+// CLI entrypoint for Cursor's synchronous hooks. Kept separate from
+// delegate.ts so importing the dispatcher never starts a second stdin
+// reader in the same process (run-detached.ts depends on that).
+async function main(): Promise<void> {
+ const hookKey = process.argv[2];
+ if (!isCursorHookKey(hookKey)) process.exit(0);
+
+ let input = "";
+ for await (const chunk of process.stdin) input += chunk;
+ if (!input.trim()) process.exit(0);
+
+ let data: HookPayload;
+ try {
+ data = JSON.parse(input) as HookPayload;
+ } catch {
+ process.exit(0);
+ }
+ if (!data || typeof data !== "object" || Array.isArray(data)) process.exit(0);
+
+ process.exit(delegateHook(hookKey, data));
+}
+
+main().catch(() => process.exit(0));
diff --git a/src/hooks/cursor/workspace.ts b/src/hooks/cursor/workspace.ts
new file mode 100644
index 00000000..29a2c38d
--- /dev/null
+++ b/src/hooks/cursor/workspace.ts
@@ -0,0 +1,711 @@
+import {
+ chmodSync,
+ closeSync,
+ existsSync,
+ mkdirSync,
+ openSync,
+ readFileSync,
+ readSync,
+ renameSync,
+ readdirSync,
+ statSync,
+ unlinkSync,
+ writeFileSync,
+} from "node:fs";
+import { execSync } from "node:child_process";
+import { dirname, join, basename } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { resolveProject as canonicalProject } from "../_project.js";
+import { workspaceFromCursorDb } from "./cursor-db.js";
+
+// Cursor does not hand hooks a trustworthy working directory: `cwd` can be
+// `.cursor`, the IDE install path (via VSCODE_CWD), or absent entirely. This
+// module is the Cursor-specific piece of the adapter — everything it exists
+// to do is turn whatever Cursor sends into a real project directory, so the
+// canonical hooks in src/hooks/*.ts can stay unchanged.
+const HOME = homedir();
+const CURSOR_PROJECTS_DIR = join(HOME, ".cursor", "projects");
+const SESSION_CACHE_PATH = join(HOME, ".cursor", "hooks", ".agentmemory-session-cache.json");
+const HOOK_PAYLOAD_DIR = join(HOME, ".cursor", "hooks", ".am-hook-payloads");
+
+export interface Workspace {
+ project: string;
+ cwd: string;
+}
+
+export type HookData = Record<string, unknown> | null | undefined;
+
+interface SessionCacheEntry {
+ project: string;
+ cwd: string;
+ updatedAt: string;
+}
+
+type SessionCache = Record<string, SessionCacheEntry>;
+
+const SESSION_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const SESSION_CACHE_MAX_ENTRIES = 200;
+
+export function normalizePathSlashes(value: unknown): string {
+ return String(value).replace(/\\/g, "/");
+}
+
+export function isCursorMetadataPath(value: unknown): boolean {
+ if (!value || typeof value !== "string") return false;
+ const trimmed = normalizePathSlashes(value.trim());
+ if (trimmed === ".cursor") return true;
+ // ~/.cursor/worktrees/<name> is the exception: Cursor puts real git
+ // checkouts there for its background agents. Treating those as metadata
+ // sends the session to whatever the transcript scan guesses instead of to
+ // the repository the agent is actually editing.
+ if (/(^|\/)\.cursor\/worktrees\/[^/]/.test(trimmed)) return false;
+ return /(^|\/)\.cursor(\/|$)/.test(trimmed);
+}
+
+export function pathUnderHome(value: unknown): boolean {
+ if (typeof value !== "string") return false;
+ const homeNorm = normalizePathSlashes(HOME);
+ const valueNorm = normalizePathSlashes(value);
+ return valueNorm === homeNorm || valueNorm.startsWith(`${homeNorm}/`);
+}
+
+// VSCODE_CWD points at the Cursor install directory, which resolves to a
+// project literally named "cursor" if it is allowed through.
+function isIdeInstallPath(value: unknown): boolean {
+ if (!value || typeof value !== "string") return false;
+ const norm = normalizePathSlashes(value).toLowerCase();
+ return (
+ /(^|[\\/])(programs|program files|program files \(x86\))[\\/]cursor([\\/]|$)/i.test(norm) ||
+ /cursor\.app[\\/]contents/i.test(norm) ||
+ /(^|[\\/])microsoft vs code[\\/]resources[\\/]app([\\/]|$)/i.test(norm)
+ );
+}
+
+function isBadPath(value: unknown): boolean {
+ if (!value || typeof value !== "string") return true;
+ const trimmed = normalizePathSlashes(value.trim());
+ if (!trimmed || trimmed === "/" || trimmed === ".") return true;
+ // A bare drive root is never a project. Cursor emits a single-letter
+ // transcript slug for some legacy windows ("c"), which decodes to "C:".
+ if (/^[a-zA-Z]:\/?$/.test(trimmed)) return true;
+ if (isCursorMetadataPath(trimmed)) return true;
+ if (isIdeInstallPath(trimmed)) return true;
+ return false;
+}
+
+function sleepMs(ms: number): void {
+ const end = Date.now() + ms;
+ while (Date.now() < end) {
+ // Busy wait: this runs inside a lock retry loop in a short-lived hook
+ // process, where blocking is cheaper than an async scheduler hop.
+ }
+}
+
+function withSessionCacheLock<T>(fn: () => T): T | undefined {
+ const lockPath = `${SESSION_CACHE_PATH}.lock`;
+ mkdirSync(dirname(SESSION_CACHE_PATH), { recursive: true });
+ let fd: number | undefined;
+ for (let i = 0; i < 50; i++) {
+ try {
+ fd = openSync(lockPath, "wx");
+ break;
+ } catch {
+ sleepMs(10);
+ }
+ }
+ if (fd === undefined) return undefined;
+ try {
+ return fn();
+ } finally {
+ closeSync(fd);
+ try {
+ unlinkSync(lockPath);
+ } catch {}
+ }
+}
+
+function loadSessionCache(): SessionCache {
+ try {
+ const value: unknown = JSON.parse(readFileSync(SESSION_CACHE_PATH, "utf-8"));
+ return value && typeof value === "object" && !Array.isArray(value) ? value as SessionCache : {};
+ } catch {
+ return {};
+ }
+}
+
+// Every hook is a fresh process that parses this file, so it is kept small:
+// stale sessions are dropped and only the most recent entries survive.
+function pruneSessionCache(cache: SessionCache, now: number): SessionCache {
+ const fresh = Object.entries(cache).filter(([, entry]) => {
+ const updated = Date.parse(entry?.updatedAt ?? "");
+ return typeof entry?.project === "string" && typeof entry?.cwd === "string" && Number.isFinite(updated) && now - updated < SESSION_CACHE_MAX_AGE_MS;
+ });
+ fresh.sort((a, b) => Date.parse(b[1].updatedAt) - Date.parse(a[1].updatedAt));
+ return Object.fromEntries(fresh.slice(0, SESSION_CACHE_MAX_ENTRIES));
+}
+
+function rememberSession(sessionId: string | undefined, project: string, cwd: string): void {
+ if (!sessionId || !project || project === ".cursor") return;
+ withSessionCacheLock(() => {
+ try {
+ const now = Date.now();
+ const previous = loadSessionCache();
+ delete previous[sessionId];
+ const cache = pruneSessionCache({ [sessionId]: { project, cwd, updatedAt: new Date(now).toISOString() }, ...previous }, now);
+ const tmp = `${SESSION_CACHE_PATH}.${process.pid}.${Date.now()}.tmp`;
+ writeFileSync(tmp, JSON.stringify(cache, null, 2));
+ renameSync(tmp, SESSION_CACHE_PATH);
+ } catch {}
+ });
+}
+
+function recallSession(sessionId: string | undefined): SessionCacheEntry | null {
+ if (!sessionId) return null;
+ const cache = pruneSessionCache(loadSessionCache(), Date.now());
+ return Object.hasOwn(cache, sessionId) ? cache[sessionId]! : null;
+}
+
+// Absolute paths that belong to the OS rather than to any user project. A
+// stray /usr/lib/... or /etc/... reference inside tool_input must not be
+// allowed to resolve to a project named "lib" or "etc".
+const SYSTEM_PATH_PREFIXES = [
+ "/usr/",
+ "/etc/",
+ "/bin/",
+ "/sbin/",
+ "/lib/",
+ "/lib64/",
+ "/opt/",
+ "/var/",
+ "/proc/",
+ "/sys/",
+ "/dev/",
+ "/run/",
+ "/boot/",
+ "/snap/",
+ "/nix/",
+];
+
+function isSystemPath(value: string): boolean {
+ const norm = normalizePathSlashes(value);
+ const temp = normalizePathSlashes(tmpdir()).replace(/\/$/, "");
+ if (norm.startsWith(`${temp}/`)) return false;
+ return SYSTEM_PATH_PREFIXES.some((prefix) => norm.startsWith(prefix));
+}
+
+// tool_input carries whatever shape the tool used, so paths are harvested by
+// walking the object. The filter has to be permissive enough to find the
+// project and strict enough not to invent one.
+function isCollectablePath(value: unknown): value is string {
+ if (typeof value !== "string" || isCursorMetadataPath(value)) return false;
+ if (pathUnderHome(value)) return true;
+ // Windows drive-absolute: HOME is regularly on C: while the checkout sits
+ // on D:, so a HOME-only rule loses every cross-drive project.
+ if (/^[a-zA-Z]:[\\/]/.test(value)) return true;
+ // POSIX-absolute outside $HOME: containers (Codespaces, devcontainers)
+ // check repos out at /workspaces/..., which a HOME-only rule silently
+ // rejects. existingDirectory() and the git lookup downstream validate it.
+ if (value.startsWith("/")) return !isSystemPath(value);
+ return false;
+}
+
+function collectPathStrings(value: unknown, out: string[] = []): string[] {
+ if (typeof value === "string") {
+ if (isCollectablePath(value)) out.push(value);
+ return out;
+ }
+ if (Array.isArray(value)) {
+ for (const item of value) collectPathStrings(item, out);
+ return out;
+ }
+ if (value && typeof value === "object") {
+ for (const v of Object.values(value)) collectPathStrings(v, out);
+ }
+ return out;
+}
+
+function pathExists(pathValue: string): boolean {
+ if (existsSync(pathValue)) return true;
+ if (process.platform === "win32") {
+ const native = pathValue.replace(/\//g, "\\");
+ if (native !== pathValue && existsSync(native)) return true;
+ }
+ return false;
+}
+
+const MAX_ANCESTOR_STEPS = 64;
+
+// Payloads often carry a file path (tool_input.path) rather than a
+// directory, and sometimes a path that no longer exists. Walk up until
+// something real is found, then normalise a file down to its directory.
+function existingAncestor(pathValue: string): string | null {
+ let current = pathValue;
+ for (let step = 0; step < MAX_ANCESTOR_STEPS; step++) {
+ if (!current || current === HOME || current === "/") return null;
+ if (pathExists(current)) {
+ const resolved = process.platform === "win32" ? current.replace(/\//g, "\\") : current;
+ try {
+ if (statSync(resolved).isFile()) {
+ return dirname(resolved);
+ }
+ } catch {}
+ return resolved;
+ }
+ // dirname() is a fixed point at every filesystem root -- dirname("//") is
+ // "//", dirname("C:") is "C:", dirname("D:/") is "D:/" -- so climbing
+ // without a progress check spins forever. Nothing produced such an input
+ // while this only ever saw $HOME-prefixed paths; a general path scan
+ // produces them constantly, because every "https://host/x" in a
+ // transcript contains a "//host/x".
+ const parent = dirname(current);
+ if (parent === current) return null;
+ current = parent;
+ }
+ return null;
+}
+
+function gitRootFromPath(targetPath: string): string {
+ return execSync("git rev-parse --show-toplevel", {
+ cwd: targetPath,
+ encoding: "utf-8",
+ stdio: ["ignore", "pipe", "ignore"],
+ timeout: 500,
+ }).trim();
+}
+
+// Filesystem-only equivalent of `git rev-parse --show-toplevel`, for hot
+// paths that would otherwise spawn a process per candidate. `.git` is a
+// directory in a normal clone and a file in a linked worktree, so a plain
+// existence check covers both.
+function gitRootNearby(startPath: string): string | null {
+ let current = startPath;
+ for (let step = 0; step < MAX_ANCESTOR_STEPS; step++) {
+ if (!current || current === "/") return null;
+ if (pathExists(join(current, ".git"))) return current;
+ const parent = dirname(current);
+ if (parent === current) return null;
+ current = parent;
+ }
+ return null;
+}
+
+
+interface ResolvedProject {
+ name: string;
+ /** Whether the name came from a git toplevel rather than a bare directory. */
+ fromGitRoot: boolean;
+}
+
+function projectFromPath(targetPath: string): ResolvedProject {
+ try {
+ return { name: canonicalProject(gitRootFromPath(targetPath)), fromGitRoot: true };
+ } catch {
+ return { name: canonicalProject(targetPath), fromGitRoot: false };
+ }
+}
+
+// Cursor names each directory under ~/.cursor/projects after the workspace
+// path with every separator flattened to "-", so the transcript directory for
+// a session already encodes where that session was running. Decoding it is
+// lossy in one direction only: a directory name may itself contain hyphens,
+// which makes "d-Andrew-Code-cc-router" mean D:/Andrew/Code/cc-router and,
+// just as validly on paper, D:/Andrew/Code/cc/router.
+//
+// The disambiguator is the filesystem. Try every way of grouping consecutive
+// segments into one directory name, but only descend into groupings that
+// actually exist -- pruning collapses what looks like a 2^segments search
+// into the handful of real directories on the machine.
+function decodeSlugCandidates(slug: string): string[] {
+ if (!slug || slug === "empty-window") return [];
+ // Cursor 3.x names workspace-less windows (started from the welcome screen)
+ // after a timestamp. Those never correspond to a path.
+ if (/^\d{10,}$/.test(slug)) return [];
+
+ const parts = slug.split("-");
+ if (!parts.length) return [];
+
+ const results = new Set<string>();
+
+ function walk(index: number, currentPath: string): void {
+ if (index >= parts.length) {
+ results.add(currentPath);
+ return;
+ }
+ for (let take = 1; index + take <= parts.length; take++) {
+ const next = `${currentPath}/${parts.slice(index, index + take).join("-")}`;
+ if (!pathExists(next)) continue;
+ walk(index + take, next);
+ }
+ }
+
+ // A single leading letter is a Windows drive: "d-Andrew-Code" -> D:/Andrew/Code.
+ // Without this branch the whole function returns nothing on Windows, which
+ // is where HOME and the checkout most often sit on different drives.
+ const first = parts[0];
+ if (first && /^[a-zA-Z]$/.test(first)) walk(1, `${first.toUpperCase()}:`);
+ // Otherwise the slug starts at the filesystem root: "Users-alice-src",
+ // "home-andrew-src", "workspaces-repo".
+ walk(0, "");
+
+ return [...results];
+}
+
+function pickBestCandidate(candidates: string[], preferredLabel: string): string | null {
+ if (!candidates.length) return null;
+ if (preferredLabel) {
+ const labelMatch = candidates.find((p) => basename(p) === preferredLabel);
+ if (labelMatch) return labelMatch;
+ }
+
+ const gitRoots: string[] = [];
+ for (const candidate of candidates) {
+ try {
+ gitRoots.push(gitRootFromPath(candidate));
+ } catch {}
+ }
+ const uniqueGitRoots = [...new Set(gitRoots)];
+ if (uniqueGitRoots.length === 1) return uniqueGitRoots[0] ?? null;
+
+ return candidates.sort((a, b) => b.length - a.length)[0] ?? null;
+}
+
+function findSessionTranscript(
+ sessionId: string,
+): { slug: string; transcriptFile: string | null } | null {
+ if (!sessionId || !existsSync(CURSOR_PROJECTS_DIR)) return null;
+
+ for (const slug of readdirSync(CURSOR_PROJECTS_DIR)) {
+ const transcriptsRoot = join(CURSOR_PROJECTS_DIR, slug, "agent-transcripts");
+ if (!existsSync(transcriptsRoot)) continue;
+
+ for (const entry of readdirSync(transcriptsRoot)) {
+ if (entry === sessionId || entry.startsWith(`${sessionId}-`)) {
+ const transcriptFile = join(transcriptsRoot, entry, `${entry}.jsonl`);
+ return {
+ slug,
+ transcriptFile: existsSync(transcriptFile) ? transcriptFile : null,
+ };
+ }
+ }
+ }
+ return null;
+}
+
+const TRANSCRIPT_SCAN_BYTES = 250000;
+const TRANSCRIPT_CANDIDATE_LIMIT = 120;
+const TRANSCRIPT_MATCH_LIMIT = 4000;
+const TRANSCRIPT_MIN_VOTES = 3;
+
+// Paths are normalised to forward slashes before matching, so a Windows path
+// looks like "D:/repo/src/a.ts" by the time these run.
+//
+// Both patterns are a single character class with one bounded quantifier, on
+// purpose. The obvious formulation -- /\/(?:[\w.-]+\/)+[\w.-]*/ -- nests a
+// quantifier inside a quantifier, and on a 250KB transcript full of
+// slash-bearing strings that backtracks badly enough to hang the hook for
+// minutes. There is no clever matching to do here anyway: grab anything
+// path-shaped and let the existence check below decide.
+const TRANSCRIPT_PATH_PATTERNS = [
+ /[a-zA-Z]:[A-Za-z0-9._@+\-/]{3,240}/g, // Windows drive-absolute
+ /\/[A-Za-z0-9._@+\-/]{3,240}/g, // POSIX absolute
+];
+
+// Last resort before environment variables: mine the session transcript for
+// paths and take the directory that shows up across the most of them.
+//
+// This used to anchor its regex on $HOME, which quietly made the whole layer
+// dead on the two most common non-trivial setups -- Windows with HOME on C:
+// and the checkout on D:, and containers that check out under /workspaces.
+// Match any absolute path shape instead and let existence plus the git lookup
+// downstream throw out the noise (URLs, log fragments, OS paths).
+function workspaceFromTranscriptFile(transcriptFile: string | null): string | null {
+ if (!transcriptFile || !existsSync(transcriptFile)) return null;
+
+ let chunk: string;
+ const fd = openSync(transcriptFile, "r");
+ try {
+ const buffer = Buffer.alloc(TRANSCRIPT_SCAN_BYTES);
+ const bytes = readSync(fd, buffer, 0, buffer.length, 0);
+ chunk = normalizePathSlashes(buffer.subarray(0, bytes).toString("utf8"));
+ } finally { closeSync(fd); }
+ const counts = new Map<string, number>();
+ const seen = new Set<string>();
+
+ // Bounded on both axes: every candidate costs filesystem walks, and a busy
+ // transcript can contain thousands of path-shaped strings.
+ for (const pattern of TRANSCRIPT_PATH_PATTERNS) {
+ pattern.lastIndex = 0;
+ let match: RegExpExecArray | null;
+ let scanned = 0;
+ while ((match = pattern.exec(chunk)) !== null) {
+ if (++scanned > TRANSCRIPT_MATCH_LIMIT) break;
+ if (seen.size >= TRANSCRIPT_CANDIDATE_LIMIT) break;
+ const value = match[0];
+ if (seen.has(value)) continue;
+ seen.add(value);
+ // "//host/path" is the tail of a URL, not a filesystem path.
+ if (value.startsWith("//")) continue;
+ if (isCursorMetadataPath(value) || isIdeInstallPath(value) || isSystemPath(value)) continue;
+ // Only paths that still exist vote, and they vote for their git root.
+ //
+ // Both halves matter. Letting a path climb to whatever ancestor still
+ // exists (existingAncestor) means a deleted D:/repo/pkg/src/a.ts votes
+ // for D:/repo, and a transcript is full of such paths, so the
+ // shallowest common directory always wins -- a session in
+ // D:/Andrew/Code/pkg resolves to the project "Code". Counting existing
+ // directories as themselves instead just moves the problem: the winner
+ // becomes whatever generic directory the conversation mentioned most,
+ // which in practice is "/bin" or "C:/Users". Requiring a repository
+ // root is what makes a vote mean "this is a project".
+ const existing = existingDirectory(value);
+ if (!existing || existing === HOME || isBadPath(existing)) continue;
+ const root = gitRootNearby(existing);
+ if (!root || root === HOME || isBadPath(root)) continue;
+ counts.set(root, (counts.get(root) || 0) + 1);
+ }
+ }
+
+ let best: string | null = null;
+ let bestCount = 0;
+ for (const [pathValue, count] of counts) {
+ if (count > bestCount) {
+ best = pathValue;
+ bestCount = count;
+ }
+ }
+
+ // One passing mention of a repository is not evidence that the session was
+ // running in it. This layer is a guess of last resort, and a wrong guess
+ // files a user's memories under someone else's project -- worse than
+ // admitting the workspace is unknown.
+ return bestCount >= TRANSCRIPT_MIN_VOTES ? best : null;
+}
+
+function workspaceFromSessionId(sessionId: string): string | null {
+ const hit = findSessionTranscript(sessionId);
+ if (!hit) return null;
+
+ // Slug first. It is a lossy encoding of the workspace path, but every
+ // candidate it produces is verified against the filesystem, so a result is
+ // a directory that really exists and really matches the name Cursor gave
+ // this session's transcript directory.
+ const preferredLabel = process.env["CURSOR_WORKSPACE_LABEL"] || "";
+ const fromSlug = pickBestCandidate(decodeSlugCandidates(hit.slug), preferredLabel);
+ if (fromSlug) return fromSlug;
+
+ // Transcript scan last: it answers "which directory is mentioned most in
+ // this conversation", which is a guess, not a fact. Asked first it will
+ // happily answer "agentmemory" for a session about agentmemory that was
+ // actually running somewhere else entirely. It stays because it is the only
+ // thing that can place a workspace-less window that was still working on
+ // real files.
+ return workspaceFromTranscriptFile(hit.transcriptFile);
+}
+
+export function readHookStdinComplete(maxWaitMs = 30000): Promise<string> {
+ return new Promise((resolve) => {
+ let input = "";
+ let done = false;
+ const finish = (): void => {
+ if (done) return;
+ done = true;
+ try {
+ process.stdin.destroy();
+ } catch {}
+ resolve(input);
+ };
+ const t = setTimeout(finish, maxWaitMs);
+ if (t.unref) t.unref();
+ process.stdin.on("data", (c) => {
+ input += c;
+ });
+ process.stdin.on("end", () => {
+ clearTimeout(t);
+ finish();
+ });
+ process.stdin.on("error", () => {
+ clearTimeout(t);
+ finish();
+ });
+ });
+}
+
+export function writeHookPayloadTemp(input: string): string {
+ mkdirSync(HOOK_PAYLOAD_DIR, { recursive: true });
+ try {
+ chmodSync(HOOK_PAYLOAD_DIR, 0o700);
+ } catch {}
+ const path = join(HOOK_PAYLOAD_DIR, `am-hook-${process.pid}-${Date.now()}.json`);
+ writeFileSync(path, input, { encoding: "utf-8", mode: 0o600 });
+ return path;
+}
+
+export function readWorkerHookPayload(): Record<string, unknown> | null {
+ const file = process.env["AM_HOOK_INPUT_FILE"];
+ if (!file) {
+ console.error("[agentmemory] missing AM_HOOK_INPUT_FILE in worker");
+ return null;
+ }
+ try {
+ const raw = readFileSync(file, "utf-8");
+ const value: unknown = JSON.parse(raw);
+ return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+ } catch (err) {
+ console.error("[agentmemory] failed to parse hook payload:", (err as Error).message);
+ return null;
+ } finally {
+ try {
+ unlinkSync(file);
+ } catch {}
+ }
+}
+
+// Sessions were landing under ".codex": a path pointing into an agent's state
+// directory walked up to ~/.codex and that became the project name.
+//
+// Rejecting every dot-named directory would be wrong, though. Plenty of real
+// projects are dot-named -- ~/.dotfiles, ~/.emacs.d, ~/.config kept under
+// chezmoi, and GitHub's own convention of a repository literally named
+// ".github". What separates those from ~/.codex or ~/.vscode is not the name,
+// it is that a human deliberately version controls them. So the rule is "a
+// dot-named directory that is not a repository", which needs no list of tool
+// names to keep up to date as new agents ship.
+function isMetadataProject(project: ResolvedProject): boolean {
+ return project.name.startsWith(".") && !project.fromGitRoot;
+}
+
+function isHomeDirectory(pathValue: string): boolean {
+ return normalizePathSlashes(pathValue) === normalizePathSlashes(HOME);
+}
+
+// The path exactly, or its parent when it points at a file. Unlike
+// existingAncestor() this does not climb: for a workspace path that some
+// source claims is authoritative, "the directory is gone" means the record is
+// stale, not "use whatever ancestor still exists". Climbing there silently
+// turns D:/Andrew/Code/cc-router (moved away) into the project "Code" and
+// files the session's memories under it.
+function existingDirectory(pathValue: string): string | null {
+ if (!pathExists(pathValue)) return null;
+ const resolved = process.platform === "win32" ? pathValue.replace(/\//g, "\\") : pathValue;
+ try {
+ return statSync(resolved).isFile() ? dirname(resolved) : resolved;
+ } catch {
+ return null;
+ }
+}
+
+function resolveFromPathCandidates(
+ candidates: unknown[],
+ sessionId: string | undefined,
+ options: { exact?: boolean; remember?: boolean } = {},
+): Workspace | null {
+ for (const candidate of candidates) {
+ if (typeof candidate !== "string" || isBadPath(candidate)) continue;
+ const existing = options.exact ? existingDirectory(candidate) : existingAncestor(candidate);
+ if (!existing || isBadPath(existing)) continue;
+ const project = projectFromPath(existing);
+ // $HOME is what a hook sees when the agent was launched with no workspace
+ // at all. Accepting it invents a project named after the account -- real
+ // sessions were being filed under "Andrew" with cwd C:\Users\Andrew --
+ // when the honest answer is that there is no workspace. Same carve-out as
+ // the dot-directory rule: allowed when HOME is itself a repository, which
+ // is the dotfiles-checked-out-in-$HOME layout.
+ if (isHomeDirectory(existing) && !project.fromGitRoot) continue;
+ if (!isMetadataProject(project)) {
+ if (options.remember !== false) rememberSession(sessionId, project.name, existing);
+ return { project: project.name, cwd: existing };
+ }
+ }
+ return null;
+}
+
+// Which layer answered is the single most useful thing to know when a session
+// lands under the wrong project, and it is invisible from the outside: every
+// layer returns the same shape. Set AM_CURSOR_DEBUG=1 to have the resolver say
+// so on stderr, which Cursor surfaces in its hook log.
+function debugLayer(layer: string, result: Workspace | null): Workspace | null {
+ if (result && process.env["AM_CURSOR_DEBUG"] === "1") {
+ console.error(`[agentmemory] workspace resolved by ${layer}: ${result.project} (${result.cwd})`);
+ }
+ return result;
+}
+
+export function resolveWorkspace(data: HookData): Workspace {
+ const sessionId = [data?.["session_id"], data?.["sessionId"], data?.["conversation_id"]].find((value): value is string => typeof value === "string" && Boolean(value.trim()));
+ // A cached workspace that has since moved or been deleted is stale; fall
+ // through so the current payload can replace it.
+ const cached = recallSession(sessionId);
+ if (cached?.cwd && !isBadPath(cached.cwd) && existingDirectory(cached.cwd)) {
+ return { project: canonicalProject(cached.cwd), cwd: cached.cwd };
+ }
+
+ const payloadCandidates: unknown[] = [
+ ...(Array.isArray(data?.["workspace_roots"]) ? (data["workspace_roots"] as unknown[]) : []),
+ ...(Array.isArray(data?.["workspace_folders"]) ? (data["workspace_folders"] as unknown[]) : []),
+ data?.["workspace_folder"],
+ data?.["workspaceFolder"],
+ data?.["workspace"],
+ data?.["cwd"],
+ data?.["root_path"],
+ data?.["project_path"],
+ ];
+
+ const fromPayload = debugLayer("payload", resolveFromPathCandidates(payloadCandidates, sessionId));
+ if (fromPayload) return fromPayload;
+
+ const toolPaths = collectPathStrings(data?.["tool_input"] ?? data?.["toolArgs"])
+ .map(existingDirectory)
+ .filter((p): p is string => Boolean(p) && !isIdeInstallPath(p));
+ const fromTools = debugLayer("tool_input", resolveFromPathCandidates(toolPaths, sessionId));
+ if (fromTools) return fromTools;
+
+ if (sessionId) {
+ // Cursor's own record of where this session was running. Exact, so it is
+ // tried before the inference layers below -- it costs one indexed SQLite
+ // read (~5ms) and, because the result is cached per session, happens at
+ // most once per session rather than once per hook.
+ const fromDb = debugLayer(
+ "cursor-db",
+ resolveFromPathCandidates([workspaceFromCursorDb(sessionId)], sessionId, { exact: true }),
+ );
+ if (fromDb) return fromDb;
+
+ // Same validation as every other layer: both sources here already
+ // verified the directory exists, so `exact` keeps a stale one from
+ // silently climbing to a parent.
+ const fromSession = debugLayer(
+ "transcript-dir",
+ resolveFromPathCandidates([workspaceFromSessionId(sessionId)], sessionId, { exact: true }),
+ );
+ if (fromSession) return fromSession;
+ }
+
+ // Env comes last. CURSOR_PROJECT_DIR is Cursor's documented workspace root
+ // for hooks; the other two are explicit user overrides. Those are cached.
+ const authoritativeEnv: unknown[] = [
+ process.env["CURSOR_PROJECT_DIR"],
+ process.env["CURSOR_WORKSPACE_ROOT"],
+ process.env["CURSOR_WORKSPACE_FOLDER"],
+ ];
+ const fromEnv = debugLayer("env", resolveFromPathCandidates(authoritativeEnv, sessionId));
+ if (fromEnv) return fromEnv;
+
+ // PWD and VSCODE_CWD only describe where the hook process was launched
+ // (VSCODE_CWD is often the IDE install directory), so they are used for
+ // this hook but never cached: later hooks with real evidence must win.
+ const launchEnv: unknown[] = [process.env["PWD"], process.env["VSCODE_CWD"]];
+ const fromLaunch = debugLayer(
+ "launch-env",
+ resolveFromPathCandidates(launchEnv, sessionId, { remember: false }),
+ );
+ if (fromLaunch) return fromLaunch;
+
+ const label = process.env["CURSOR_WORKSPACE_LABEL"];
+ if (label) return { project: label, cwd: label };
+
+ return { project: "unknown-project", cwd: "unknown-project" };
+}
+
+export function resolveProject(data: HookData): string {
+ return resolveWorkspace(data).project;
+}
diff --git a/test/cursor-adapter.test.ts b/test/cursor-adapter.test.ts
new file mode 100644
index 00000000..f8c7517f
--- /dev/null
+++ b/test/cursor-adapter.test.ts
@@ -0,0 +1,272 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { createServer, type Server } from "node:http";
+import { spawn } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, rmSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { HOOK_MAP, delegateHook, isCursorHookKey } from "../src/hooks/cursor/delegate.js";
+
+// What the Cursor adapter is responsible for is narrow and testable without a
+// daemon: pick the right canonical hook, tell it which project this is, hand
+// it the payload, and report what happened. These tests cover exactly that.
+//
+// They deliberately do not use spawnSync. spawnSync blocks the calling
+// process's event loop, so an in-process HTTP server cannot accept the very
+// connection the child is making -- the requests arrive only after the child
+// has exited, which reads as "the hook sent nothing" and sends you hunting a
+// bug that is not there.
+
+const REPO_ROOT = join(import.meta.dirname, "..");
+const CURSOR_SCRIPTS = join(REPO_ROOT, "plugin", "scripts", "cursor");
+const OFFICIAL_SCRIPTS = join(REPO_ROOT, "plugin", "scripts");
+
+const uniqueId = (prefix: string): string =>
+ `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+
+interface Capture {
+ url: string;
+ body: unknown;
+}
+
+function startCaptureServer(): Promise<{ url: string; captures: Capture[]; close: () => void }> {
+ const captures: Capture[] = [];
+ const server: Server = createServer((req, res) => {
+ let raw = "";
+ req.on("data", (c) => (raw += c));
+ req.on("end", () => {
+ let body: unknown = raw;
+ try {
+ body = JSON.parse(raw);
+ } catch {}
+ captures.push({ url: req.url ?? "", body });
+ res.writeHead(200, { "Content-Type": "application/json" });
+ res.end(JSON.stringify({ ok: true, sessions: [] }));
+ });
+ });
+ return new Promise((resolve) => {
+ server.listen(0, "127.0.0.1", () => {
+ const address = server.address();
+ const port = typeof address === "object" && address ? address.port : 0;
+ resolve({
+ url: `http://127.0.0.1:${port}`,
+ captures,
+ close: () => server.close(),
+ });
+ });
+ });
+}
+
+function runShim(
+ script: string,
+ args: string[],
+ payload: unknown,
+ env: Record<string, string>,
+): Promise<{ code: number | null; stderr: string }> {
+ return new Promise((resolve) => {
+ const child = spawn(process.execPath, [join(CURSOR_SCRIPTS, script), ...args], {
+ env: { ...process.env, ...env },
+ stdio: ["pipe", "pipe", "pipe"],
+ });
+ let stderr = "";
+ child.stderr.on("data", (c) => (stderr += c));
+ child.stdout.resume();
+ child.stdin.end(JSON.stringify(payload));
+ child.on("close", (code) => resolve({ code, stderr }));
+ });
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+async function waitForCapture(
+ captures: Capture[],
+ predicate: (c: Capture) => boolean,
+ timeoutMs = 15000,
+): Promise<Capture | null> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ const hit = captures.find(predicate);
+ if (hit) return hit;
+ await sleep(50);
+ }
+ return null;
+}
+
+describe("cursor hook map", () => {
+ // The map is the only thing standing between a Cursor lifecycle event and
+ // the hook that handles it, and its values are bare strings. A typo here
+ // does not throw: the hook silently stops recording and nothing reports it.
+ it("every Cursor event maps to a canonical hook that exists", () => {
+ const missing = Object.entries(HOOK_MAP).filter(
+ ([, script]) => !existsSync(join(OFFICIAL_SCRIPTS, script)),
+ );
+ expect(missing).toEqual([]);
+ });
+
+ it("covers the events plugin/cursor/hooks.json declares", () => {
+ const config = JSON.parse(
+ readFileSync(join(REPO_ROOT, "plugin", "cursor", "hooks.json"), "utf-8"),
+ ) as { hooks: Record<string, unknown> };
+ for (const event of Object.keys(config.hooks)) {
+ expect(isCursorHookKey(event), `plugin/cursor/hooks.json declares "${event}"`).toBe(true);
+ }
+ });
+});
+
+describe("delegateHook", () => {
+ let dir: string;
+
+ beforeAll(() => {
+ dir = mkdtempSync(join(tmpdir(), "am-cursor-delegate-"));
+ // A stand-in for a canonical hook: records the environment and payload it
+ // was handed so the adapter's contract with it can be asserted.
+ writeFileSync(
+ join(dir, "session-start.mjs"),
+ [
+ "let input = '';",
+ "for await (const chunk of process.stdin) input += chunk;",
+ "process.stdout.write(JSON.stringify({",
+ " project: process.env.AGENTMEMORY_PROJECT_NAME,",
+ " payload: JSON.parse(input || '{}'),",
+ "}));",
+ ].join("\n"),
+ );
+ writeFileSync(join(dir, "stop.mjs"), "process.exit(3);");
+ });
+
+ afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+ it("passes the resolved project through the environment and cwd through the payload", () => {
+ const workspace = join(dir, "my-test-project");
+ mkdirSync(workspace, { recursive: true });
+
+ const chunks: string[] = [];
+ const write = process.stdout.write.bind(process.stdout);
+ process.stdout.write = ((c: string) => {
+ chunks.push(String(c));
+ return true;
+ }) as typeof process.stdout.write;
+ try {
+ delegateHook(
+ "sessionStart",
+ { session_id: uniqueId("delegate"), workspace_roots: [workspace] },
+ { officialDir: dir },
+ );
+ } finally {
+ process.stdout.write = write;
+ }
+
+ const seen = JSON.parse(chunks.join("")) as {
+ project: string;
+ payload: { cwd: string; session_id: string; project: string };
+ };
+ // resolveProject() in the canonical hooks reads AGENTMEMORY_PROJECT_NAME
+ // before anything else; that is the whole delegation mechanism.
+ expect(seen.project).toBe("my-test-project");
+ expect(basename(seen.payload.cwd)).toBe("my-test-project");
+ // pre-tool-use reads data.project directly to scope /enrich.
+ expect(seen.payload.project).toBe("my-test-project");
+ expect(seen.payload.session_id).toBeTruthy();
+ });
+
+ it("propagates a non-zero exit from the canonical hook", () => {
+ expect(delegateHook("stop", { session_id: uniqueId("exit") }, { officialDir: dir })).toBe(3);
+ });
+
+ it("reports a hook that cannot be launched instead of returning success", () => {
+ const errors: string[] = [];
+ const original = console.error;
+ console.error = (...args: unknown[]) => errors.push(args.join(" "));
+ let status: number;
+ try {
+ status = delegateHook(
+ "preToolUse", // pre-tool-use.mjs does not exist in the temp dir
+ { session_id: uniqueId("missing") },
+ { officialDir: join(dir, "does-not-exist") },
+ );
+ } finally {
+ console.error = original;
+ }
+ // Fail open -- a memory hook must never block the editor -- but say so,
+ // rather than reporting the silent loss as success. The message has to be
+ // actionable: this is what a source checkout that never ran the build
+ // hits, and a Node module-not-found stack would not explain it.
+ expect(status).toBe(0);
+ expect(errors.join("\n")).toMatch(/canonical hook not found/);
+ expect(errors.join("\n")).toMatch(/npm run build/);
+ });
+});
+
+describe("built shims against a local server", () => {
+ let server: Awaited<ReturnType<typeof startCaptureServer>>;
+
+ beforeAll(async () => {
+ server = await startCaptureServer();
+ });
+ afterAll(() => server.close());
+
+ const hookEnv = (): Record<string, string> => ({
+ AGENTMEMORY_URL: server.url,
+ AGENTMEMORY_SECRET: "test-secret",
+ });
+
+ it.each([null, [], true])("ignores malformed hook payload %j without blocking Cursor", async payload => {
+ const before = server.captures.length;
+ const result = await runShim("run-hook.mjs", ["sessionStart"], payload, hookEnv());
+ expect(result.code).toBe(0);
+ expect(result.stderr).toBe("");
+ expect(server.captures).toHaveLength(before);
+ });
+
+ it("run-hook delivers sessionStart with the resolved project", async () => {
+ const workspace = mkdtempSync(join(tmpdir(), "am-cursor-ws-"));
+ const sessionId = uniqueId("shim-start");
+
+ const { code } = await runShim(
+ "run-hook.mjs",
+ ["sessionStart"],
+ { session_id: sessionId, workspace_roots: [workspace.replace(/\\/g, "/")] },
+ hookEnv(),
+ );
+ expect(code).toBe(0);
+
+ const hit = await waitForCapture(server.captures, (c) =>
+ c.url.includes("/agentmemory/session/start"),
+ );
+ expect(hit, "no session/start request reached the server").not.toBeNull();
+ const body = hit!.body as { sessionId: string; project: string; cwd: string };
+ expect(body.sessionId).toBe(sessionId);
+ expect(body.project).toBe(basename(workspace));
+ rmSync(workspace, { recursive: true, force: true });
+ }, 30000);
+
+ it("run-detached delivers a large payload through its background worker", async () => {
+ const workspace = mkdtempSync(join(tmpdir(), "am-cursor-ws-"));
+ const sessionId = uniqueId("shim-stop");
+ const before = server.captures.length;
+
+ // The parent's exit says only that the worker was spawned. What matters
+ // is that the detached worker -- which outlives a closing Cursor window --
+ // actually reaches the daemon.
+ const { code } = await runShim(
+ "run-detached.mjs",
+ ["stop"],
+ { session_id: sessionId, workspace_roots: [workspace.replace(/\\/g, "/")], padding: "x".repeat(200000) },
+ hookEnv(),
+ );
+ expect(code).toBe(0);
+
+ const hit = await waitForCapture(
+ server.captures,
+ (c) =>
+ server.captures.indexOf(c) >= before &&
+ typeof c.body === "object" &&
+ c.body !== null &&
+ (c.body as { sessionId?: string }).sessionId === sessionId,
+ 30000,
+ );
+ expect(hit, "detached worker never reached the server").not.toBeNull();
+ expect(hit!.url).toBe("/agentmemory/session/end");
+ expect(hit!.body).toMatchObject({ sessionId, final: false });
+ rmSync(workspace, { recursive: true, force: true });
+ }, 45000);
+});
diff --git a/test/cursor-db.test.ts b/test/cursor-db.test.ts
new file mode 100644
index 00000000..ed7e7d3d
--- /dev/null
+++ b/test/cursor-db.test.ts
@@ -0,0 +1,42 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRequire } from 'node:module';
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const sqlite = (() => { try { return createRequire(import.meta.url)('node:sqlite'); } catch { return null; } })();
+describe.skipIf(!sqlite)('Cursor read-only workspace lookup', () => {
+ let home: string;
+ let storage: string;
+ beforeEach(() => {
+ home = mkdtempSync(join(tmpdir(), 'am-cursor-db-'));
+ vi.stubEnv('HOME', home); vi.stubEnv('USERPROFILE', home);
+ vi.stubEnv('APPDATA', join(home, 'AppData/Roaming')); vi.stubEnv('XDG_CONFIG_HOME', join(home, '.config'));
+ storage = process.platform === 'darwin' ? join(home, 'Library/Application Support/Cursor/User') : process.platform === 'win32' ? join(home, 'AppData/Roaming/Cursor/User') : join(home, '.config/Cursor/User');
+ mkdirSync(join(storage, 'globalStorage'), { recursive: true }); vi.resetModules();
+ });
+ afterEach(() => { vi.unstubAllEnvs(); rmSync(home, { recursive: true, force: true }); });
+ function database(path: string, key: string, value: unknown) {
+ const db = new sqlite.DatabaseSync(path);
+ try { db.exec('CREATE TABLE ItemTable (key TEXT PRIMARY KEY, value TEXT)'); db.prepare('INSERT INTO ItemTable VALUES (?, ?)').run(key, JSON.stringify(value)); }
+ finally { db.close(); }
+ }
+ it('reads the global workspace mapping without modifying the database', async () => {
+ const path = join(storage, 'globalStorage/state.vscdb');
+ database(path, 'composer.composerHeaders', { allComposers: [{ composerId: 'session', workspaceIdentifier: { uri: { fsPath: '/fixture/project' } } }] });
+ const original = readFileSync(path);
+ const { workspaceFromCursorDb } = await import('../src/hooks/cursor/cursor-db.js');
+ expect(workspaceFromCursorDb('session')).toBe('/fixture/project');
+ expect(workspaceFromCursorDb('unknown')).toBeNull(); expect(readFileSync(path)).toEqual(original);
+ });
+ it('uses legacy metadata and rejects unmappable remote workspaces', async () => {
+ const workspace = join(storage, 'workspaceStorage/legacy'); mkdirSync(workspace, { recursive: true });
+ database(join(workspace, 'state.vscdb'), 'composer.composerData', { allComposers: [{ composerId: 'legacy' }] });
+ writeFileSync(join(workspace, 'workspace.json'), JSON.stringify({ folder: pathToFileURL(home).href }));
+ const { workspaceFromCursorDb } = await import('../src/hooks/cursor/cursor-db.js');
+ expect(workspaceFromCursorDb('legacy')).toBe(home);
+ writeFileSync(join(workspace, 'workspace.json'), JSON.stringify({ folder: 'vscode-remote://ssh-remote+host/project' }));
+ expect(workspaceFromCursorDb('legacy')).toBeNull();
+ });
+});
diff --git a/test/cursor-env.test.ts b/test/cursor-env.test.ts
new file mode 100644
index 00000000..fbb726a5
--- /dev/null
+++ b/test/cursor-env.test.ts
@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+// @ts-expect-error -- plain .mjs integration script without type declarations
+import { authHeader, parseEnvFile, requireConnection } from "../integrations/cursor/_env.mjs";
+
+describe("cursor integration env file", () => {
+ it("strips quotes and inline comments like the daemon", () => {
+ const dir = mkdtempSync(join(tmpdir(), "am-cursor-env-"));
+ const file = join(dir, ".env");
+ writeFileSync(
+ file,
+ [
+ 'AGENTMEMORY_URL="http://localhost:3111"',
+ "AGENTMEMORY_SECRET='abc'",
+ "AGENTMEMORY_TOOLS=all # every tool",
+ "export EXTRA=1",
+ ].join("\n"),
+ );
+ try {
+ expect(parseEnvFile(file)).toEqual({
+ AGENTMEMORY_URL: "http://localhost:3111",
+ AGENTMEMORY_SECRET: "abc",
+ AGENTMEMORY_TOOLS: "all",
+ EXTRA: "1",
+ });
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ it("omits the bearer header for a keyless daemon", () => {
+ expect(authHeader("")).toEqual({});
+ expect(authHeader("abc")).toEqual({ Authorization: "Bearer abc" });
+ });
+});
+
+
+describe('cursor local credentials', () => {
+ let home: string;
+ let envPath: string;
+ beforeEach(() => {
+ home = mkdtempSync(join(tmpdir(), 'am-cursor-auth-')); mkdirSync(join(home, '.agentmemory'));
+ envPath = join(home, '.agentmemory/.env');
+ writeFileSync(envPath, 'AGENTMEMORY_URL=http://127.0.0.1:3111\n');
+ writeFileSync(join(home, '.agentmemory/secret'), 'stored-fixture');
+ vi.stubEnv('HOME', home); vi.stubEnv('USERPROFILE', home);
+ vi.stubEnv('AGENTMEMORY_URL', ''); vi.stubEnv('AGENTMEMORY_SECRET', ''); vi.stubEnv('AGENTMEMORY_CREDENTIAL_MODE', '');
+ });
+ afterEach(() => { vi.unstubAllEnvs(); rmSync(home, { recursive: true, force: true }); });
+ it('uses the generated local secret when the env file has none', () => {
+ expect(requireConnection(envPath).secret).toBe('stored-fixture');
+ });
+ it('does not send file credentials to a remote URL or in explicit-only mode', () => {
+ writeFileSync(envPath, 'AGENTMEMORY_URL=http://127.0.0.1:3111\nAGENTMEMORY_SECRET=local-fixture\n');
+ vi.stubEnv('AGENTMEMORY_URL', 'https://remote.example'); expect(requireConnection(envPath).secret).toBe('');
+ vi.stubEnv('AGENTMEMORY_URL', 'http://127.0.0.1:3111'); vi.stubEnv('AGENTMEMORY_CREDENTIAL_MODE', 'explicit');
+ expect(requireConnection(envPath).secret).toBe('');
+ vi.stubEnv('AGENTMEMORY_SECRET', 'explicit-fixture'); expect(requireConnection(envPath).secret).toBe('explicit-fixture');
+ });
+});
diff --git a/test/cursor-install.test.ts b/test/cursor-install.test.ts
new file mode 100644
index 00000000..557524bb
--- /dev/null
+++ b/test/cursor-install.test.ts
@@ -0,0 +1,34 @@
+import { it, expect } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { cpSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+it('local Cursor setup preserves unrelated hooks and handles quoted checkout paths', () => {
+ const dir = mkdtempSync(join(tmpdir(), 'am-cursor-install-'));
+ const root = join(dir, 'checkout with $literal');
+ const home = join(dir, 'home');
+ try {
+ mkdirSync(join(root, 'integrations/cursor'), { recursive: true });
+ mkdirSync(join(root, 'plugin/scripts/cursor'), { recursive: true });
+ writeFileSync(join(root, 'plugin/scripts/cursor/run-hook.mjs'), '');
+ for (const name of ['install-local.mjs', '_env.mjs']) cpSync(join('integrations/cursor', name), join(root, 'integrations/cursor', name));
+ mkdirSync(join(home, '.cursor'), { recursive: true });
+ const own = { command: `node "${root}/plugin/scripts/cursor/run-hook.mjs" postToolUse` };
+ const unrelated = [
+ { command: 'node "/tools/audit.mjs"', matcher: 'agentmemory' },
+ { command: 'node "/tools/audit.mjs" --label agentmemory' },
+ { command: 'echo agentmemory' },
+ { command: `node "${root}/plugin/scripts/cursor/run-hook.mjs.backup" postToolUse` },
+ ];
+ const hooks = { version: 1, hooks: { postToolUse: [own, ...unrelated] } };
+ writeFileSync(join(home, '.cursor/hooks.json'), JSON.stringify(hooks));
+ execFileSync(process.execPath, [join(root, 'integrations/cursor/install-local.mjs'), '--clear-user-hooks'], {
+ env: { ...process.env, HOME: home, USERPROFILE: home, AGENTMEMORY_URL: 'http://127.0.0.1:3111', AGENTMEMORY_SECRET: 'fixture' }, encoding: 'utf8', timeout: 15000,
+ });
+ expect(JSON.parse(readFileSync(join(home, '.cursor/hooks.json'), 'utf8'))).toEqual({ ...hooks, hooks: { postToolUse: unrelated } });
+ const backup = readdirSync(join(home, '.cursor')).find(name => name.startsWith('hooks.json.pre-plugin-'))!;
+ expect(JSON.parse(readFileSync(join(home, '.cursor', backup), 'utf8'))).toEqual(hooks);
+ expect(realpathSync(join(home, '.cursor/plugins/marketplaces/local-agentmemory'))).toBe(realpathSync(root));
+ } finally { rmSync(dir, { recursive: true, force: true }); }
+});
diff --git a/test/cursor-plugin.test.ts b/test/cursor-plugin.test.ts
index afba1407..a6c164c5 100644
--- a/test/cursor-plugin.test.ts
+++ b/test/cursor-plugin.test.ts
@@ -79,6 +79,20 @@ describe("Cursor plugin hooks config", () => {
}
}
});
+
+ it("routes every event through the Cursor adapter instead of the canonical hook", () => {
+ for (const [event, entries] of Object.entries(hooks.hooks) as Array<
+ [string, Array<{ command: string }>]
+ >) {
+ for (const entry of entries) {
+ if (event === "stop" || event === "sessionEnd") {
+ expect(entry.command).toContain("plugin/scripts/cursor/run-detached.mjs");
+ } else {
+ expect(entry.command).toContain("plugin/scripts/cursor/run-hook.mjs");
+ }
+ }
+ }
+ });
});
describe("Cursor plugin MCP config", () => {
diff --git a/test/cursor-workspace.test.ts b/test/cursor-workspace.test.ts
new file mode 100644
index 00000000..87b4384c
--- /dev/null
+++ b/test/cursor-workspace.test.ts
@@ -0,0 +1,303 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import {
+ isCursorMetadataPath,
+ normalizePathSlashes,
+ pathUnderHome,
+ resolveWorkspace
+} from '../src/hooks/cursor/workspace.js';
+
+// resolveWorkspace caches per session id, so every test needs a fresh one or
+// it is served the previous run's answer instead of exercising its branch.
+const sessionId = (label: string): string =>
+ `${label}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+
+// The last resort before "unknown" reads the environment. Tests that assert a
+// payload was rejected have to blank it, or the developer's own shell (PWD)
+// answers instead and the assertion passes for the wrong reason.
+const ENV_KEYS = [
+ 'CURSOR_PROJECT_DIR',
+ 'CURSOR_WORKSPACE_ROOT',
+ 'CURSOR_WORKSPACE_FOLDER',
+ 'CURSOR_WORKSPACE_LABEL',
+ 'PWD',
+ 'VSCODE_CWD'
+];
+
+function withoutWorkspaceEnv<T>(fn: () => T): T {
+ const saved = ENV_KEYS.map((k) => [k, process.env[k]] as const);
+ for (const k of ENV_KEYS) delete process.env[k];
+ try {
+ return fn();
+ } finally {
+ for (const [k, v] of saved) if (v !== undefined) process.env[k] = v;
+ }
+}
+
+describe('cursor workspace resolver', () => {
+ it('isCursorMetadataPath rejects substring false positives', () => {
+ expect(isCursorMetadataPath('.cursor')).toBe(true);
+ expect(isCursorMetadataPath('/foo/.cursor/bar')).toBe(true);
+ expect(isCursorMetadataPath('C:\\Users\\me\\.cursor-backup')).toBe(false);
+ expect(isCursorMetadataPath('/home/user/.cursor-workspace-clone')).toBe(false);
+ });
+
+ it('treats ~/.cursor/worktrees as real checkouts, not metadata', () => {
+ // Cursor puts background-agent worktrees there. Classifying them as
+ // metadata sends those sessions to whatever the transcript scan guesses.
+ expect(isCursorMetadataPath('/home/me/.cursor/worktrees/myrepo-a1b2')).toBe(false);
+ expect(isCursorMetadataPath('/home/me/.cursor/extensions')).toBe(true);
+ });
+
+ it('pathUnderHome requires a path-component boundary after HOME', () => {
+ const home = normalizePathSlashes(process.env.HOME || process.env.USERPROFILE || '/home/alice');
+ expect(pathUnderHome(home)).toBe(true);
+ expect(pathUnderHome(`${home}/projects/agentmemory`)).toBe(true);
+ expect(pathUnderHome(`${home}-backup`)).toBe(false);
+ });
+
+ it('uses workspace_roots when cwd is .cursor metadata', () => {
+ const dir = mkdtempSync(join(tmpdir(), 'am-ws-'));
+ try {
+ const resolved = resolveWorkspace({
+ session_id: sessionId('metadata-cwd'),
+ workspace_roots: [normalizePathSlashes(dir)],
+ cwd: '.cursor'
+ });
+ expect(resolved.project).toBe(basename(dir));
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ it('resolves a tool_input file path to its directory, outside $HOME', () => {
+ // Doubles as the container case: on CI the temp dir is /tmp/... (POSIX
+ // absolute, not under $HOME), which a HOME-only rule silently rejected --
+ // the same way it rejects a Codespaces checkout under /workspaces.
+ const dir = mkdtempSync(join(tmpdir(), 'am-ws-'));
+ writeFileSync(join(dir, 'package.json'), '{}');
+ try {
+ const resolved = resolveWorkspace({
+ session_id: sessionId('tool-input'),
+ tool_input: { path: normalizePathSlashes(join(dir, 'package.json')) }
+ });
+ expect(resolved.project).toBe(basename(dir));
+ expect(normalizePathSlashes(resolved.cwd)).toBe(normalizePathSlashes(dir));
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+
+ it('never reports an OS directory as the project', () => {
+ // A stray /usr/lib/... in tool_input must not produce a project "lib".
+ const resolved = withoutWorkspaceEnv(() =>
+ resolveWorkspace({
+ session_id: sessionId('system-path'),
+ tool_input: { path: '/usr/lib/node_modules/whatever.js' }
+ })
+ );
+ expect(resolved.project).toBe('unknown-project');
+ });
+
+ it('never reports a tool metadata directory as the project', () => {
+ // Sessions were landing under ".codex"; only ".cursor" used to be blocked.
+ const home = process.env.HOME || process.env.USERPROFILE || tmpdir();
+ const dotDir = join(home, `.am-test-dot-${Date.now()}`);
+ mkdirSync(dotDir, { recursive: true });
+ try {
+ const resolved = withoutWorkspaceEnv(() =>
+ resolveWorkspace({ session_id: sessionId('dot-dir'), cwd: normalizePathSlashes(dotDir) })
+ );
+ expect(resolved.project).toBe('unknown-project');
+ } finally {
+ rmSync(dotDir, { recursive: true, force: true });
+ }
+ });
+
+ it('keeps a dot-named directory that is version controlled', () => {
+ // ~/.dotfiles, ~/.emacs.d, ~/.config under chezmoi, and GitHub's own
+ // convention of a repository named ".github" are all real projects people
+ // open in an editor. What separates them from ~/.codex is not the leading
+ // dot, it is that a human deliberately version controls them.
+ const parent = mkdtempSync(join(tmpdir(), 'am-ws-'));
+ const repo = join(parent, '.dotfiles');
+ mkdirSync(repo, { recursive: true });
+ execFileSync('git', ['init', '-q'], { cwd: repo, stdio: 'ignore' });
+ try {
+ const resolved = withoutWorkspaceEnv(() =>
+ resolveWorkspace({
+ session_id: sessionId('dot-repo'),
+ workspace_roots: [normalizePathSlashes(repo)]
+ })
+ );
+ expect(resolved.project).toBe('.dotfiles');
+ } finally {
+ rmSync(parent, { recursive: true, force: true });
+ }
+ });
+
+ it('never reports the home directory as the project', () => {
+ // An agent launched with no workspace reports $HOME, which used to become
+ // a project named after the account -- 18 real sessions in one day filed
+ // under "Andrew", cwd C:\Users\Andrew. Unless $HOME is itself a
+ // repository, "no workspace" is the honest answer.
+ const home = process.env.HOME || process.env.USERPROFILE;
+ if (!home) return;
+ const resolved = withoutWorkspaceEnv(() =>
+ resolveWorkspace({ session_id: sessionId('home-cwd'), cwd: normalizePathSlashes(home) })
+ );
+ expect(resolved.project).toBe('unknown-project');
+ });
+
+ it('never reports a bare drive root as the project', () => {
+ const resolved = withoutWorkspaceEnv(() =>
+ resolveWorkspace({ session_id: sessionId('drive-root'), cwd: 'C:/' })
+ );
+ expect(resolved.project).toBe('unknown-project');
+ });
+
+ it('terminates on paths whose parent is itself', () => {
+ // Regression: the ancestor walk used dirname() with only a `!== "/"`
+ // guard, but dirname is a fixed point at every root -- dirname("//") is
+ // "//", dirname("C:") is "C:". Any URL-shaped path ("//host/x", which the
+ // transcript scan produces constantly) spun forever and hung the hook.
+ const started = Date.now();
+ for (const cwd of ['//', '//host/share/project', 'C:', 'D:/', '/']) {
+ withoutWorkspaceEnv(() => resolveWorkspace({ session_id: sessionId('root-ish'), cwd }));
+ }
+ expect(Date.now() - started).toBeLessThan(10000);
+ });
+
+ it('ignores an IDE install directory', () => {
+ const resolved = withoutWorkspaceEnv(() =>
+ resolveWorkspace({
+ session_id: sessionId('ide-install'),
+ // VSCODE_CWD leaks this shape and used to yield the project "cursor".
+ cwd: 'C:/Users/me/AppData/Local/Programs/cursor'
+ })
+ );
+ expect(resolved.project).not.toBe('cursor');
+ });
+
+ it('drops a cached workspace that no longer exists', () => {
+ const parent = mkdtempSync(join(tmpdir(), 'am-ws-'));
+ const oldDir = join(parent, 'old-app');
+ const newDir = join(parent, 'new-app');
+ mkdirSync(oldDir);
+ mkdirSync(newDir);
+ const id = sessionId('moved');
+ try {
+ withoutWorkspaceEnv(() => {
+ expect(resolveWorkspace({ session_id: id, workspace_roots: [oldDir] }).project).toBe('old-app');
+ rmSync(oldDir, { recursive: true, force: true });
+ expect(resolveWorkspace({ session_id: id, workspace_roots: [newDir] }).project).toBe('new-app');
+ });
+ } finally {
+ rmSync(parent, { recursive: true, force: true });
+ }
+ });
+
+ it('does not cache a workspace inferred from the launch directory', () => {
+ const parent = mkdtempSync(join(tmpdir(), 'am-ws-'));
+ const launchDir = join(parent, 'launch-dir');
+ const realDir = join(parent, 'real-app');
+ mkdirSync(launchDir);
+ mkdirSync(realDir);
+ const id = sessionId('pwd');
+ try {
+ withoutWorkspaceEnv(() => {
+ process.env.PWD = launchDir;
+ expect(resolveWorkspace({ session_id: id }).project).toBe('launch-dir');
+ delete process.env.PWD;
+ expect(resolveWorkspace({ session_id: id, workspace_roots: [realDir] }).project).toBe(
+ 'real-app'
+ );
+ });
+ } finally {
+ rmSync(parent, { recursive: true, force: true });
+ }
+ });
+
+ it("uses Cursor's documented CURSOR_PROJECT_DIR", () => {
+ const dir = mkdtempSync(join(tmpdir(), 'am-ws-'));
+ try {
+ const resolved = withoutWorkspaceEnv(() => {
+ process.env.CURSOR_PROJECT_DIR = dir;
+ return resolveWorkspace({ session_id: sessionId('project-dir') });
+ });
+ expect(resolved.project).toBe(basename(dir));
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ });
+});
+
+
+describe('cursor workspace cache and aliases', () => {
+ let home: string;
+ let cachePath: string;
+ beforeEach(() => {
+ home = mkdtempSync(join(tmpdir(), 'am-cursor-cache-'));
+ cachePath = join(home, '.cursor/hooks/.agentmemory-session-cache.json');
+ mkdirSync(join(home, '.cursor/hooks'), { recursive: true });
+ vi.stubEnv('HOME', home); vi.stubEnv('USERPROFILE', home);
+ for (const key of ENV_KEYS) vi.stubEnv(key, '');
+ vi.stubEnv('AGENTMEMORY_PROJECT_NAME', ''); vi.resetModules();
+ });
+ afterEach(() => { vi.unstubAllEnvs(); rmSync(home, { recursive: true, force: true }); });
+ it('expires a cached mapping on reads without waiting for another write', async () => {
+ const old = join(home, 'old'); const current = join(home, 'current');
+ mkdirSync(old); mkdirSync(current);
+ writeFileSync(cachePath, JSON.stringify({ session: { project: 'old', cwd: old, updatedAt: new Date(Date.now() - 8 * 86400000).toISOString() } }));
+ const { resolveWorkspace } = await import('../src/hooks/cursor/workspace.js');
+ expect(resolveWorkspace({ session_id: 'session', workspace_roots: [current] }).project).toBe('current');
+ });
+ it('caps the cache after inserting the new session', async () => {
+ const workspace = join(home, 'project'); mkdirSync(workspace);
+ const entry = { project: 'project', cwd: workspace, updatedAt: new Date(Date.now() - 1000).toISOString() };
+ writeFileSync(cachePath, JSON.stringify(Object.fromEntries(Array.from({ length: 200 }, (_, i) => ['old-' + i, entry]))));
+ const { resolveWorkspace } = await import('../src/hooks/cursor/workspace.js');
+ resolveWorkspace({ session_id: 'new', workspace_roots: [workspace] });
+ const cache = JSON.parse(readFileSync(cachePath, 'utf8'));
+ expect(Object.keys(cache)).toHaveLength(200); expect(cache.new.cwd).toBe(workspace);
+ });
+ it.each(['null', '[]', '{"session":null}'])('ignores malformed cache contents: %s', async raw => {
+ const workspace = join(home, 'project'); mkdirSync(workspace); writeFileSync(cachePath, raw);
+ const { resolveWorkspace } = await import('../src/hooks/cursor/workspace.js');
+ expect(resolveWorkspace({ session_id: 'session', workspace_roots: [workspace] }).project).toBe('project');
+ });
+ it('uses conversation_id for caching and toolArgs for workspace evidence', async () => {
+ const workspace = join(home, 'project'); mkdirSync(workspace); writeFileSync(join(workspace, 'file.ts'), '');
+ const { resolveWorkspace } = await import('../src/hooks/cursor/workspace.js');
+ expect(resolveWorkspace({ conversation_id: 'conversation', toolArgs: { path: join(workspace, 'file.ts') } }).project).toBe('project');
+ expect(resolveWorkspace({ conversation_id: 'conversation' }).cwd).toBe(workspace);
+ });
+ it.each(['temporary', 'home'])('does not cache a generic ancestor of a missing %s tool path', async location => {
+ const root = location === 'temporary' ? tmpdir() : home;
+ const missing = join(root, `am-missing-${Date.now()}`, 'result.json');
+ const workspace = join(home, 'actual-project');
+ mkdirSync(workspace);
+ const { resolveWorkspace } = await import('../src/hooks/cursor/workspace.js');
+
+ expect(resolveWorkspace({ session_id: 'missing-tool', tool_input: { path: missing } }).project).toBe('unknown-project');
+ expect(resolveWorkspace({ session_id: 'missing-tool', workspace_roots: [workspace] }).project).toBe('actual-project');
+
+ vi.stubEnv('CURSOR_PROJECT_DIR', workspace);
+ expect(resolveWorkspace({ session_id: 'tool-with-env', toolArgs: { path: missing } }).project).toBe('actual-project');
+ });
+ it('keeps shared project naming and explicit overrides across linked worktrees', async () => {
+ const repo = join(home, 'main-repo'); const worktree = join(home, 'other-checkout'); mkdirSync(repo);
+ execFileSync('git', ['init', '-q'], { cwd: repo });
+ execFileSync('git', ['-c', 'user.name=Fixture', '-c', '[email protected]', '-c', 'core.hooksPath=/dev/null', 'commit', '-qm', 'fixture', '--allow-empty'], { cwd: repo });
+ execFileSync('git', ['worktree', 'add', '-q', '--detach', worktree], { cwd: repo });
+ const { enrichPayload } = await import('../src/hooks/cursor/delegate.js');
+ const data = { session_id: 'worktree', workspace_roots: [worktree] };
+ expect(enrichPayload(data).project).toBe('main-repo');
+ vi.stubEnv('AGENTMEMORY_PROJECT_NAME', 'configured'); expect(enrichPayload(data).project).toBe('configured');
+ expect(enrichPayload({ session_id: 'no-workspace' }).project).toBe('configured');
+ vi.stubEnv('AGENTMEMORY_PROJECT_NAME', ''); expect(enrichPayload(data).project).toBe('main-repo');
+ });
+});
diff --git a/test/rest-proxy-credentials.test.ts b/test/rest-proxy-credentials.test.ts
index b382a711..7761e12d 100644
--- a/test/rest-proxy-credentials.test.ts
+++ b/test/rest-proxy-credentials.test.ts
@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
+import { createServer, type Server } from "node:http";
import { resetHandleForTests, resolveHandle, setLivezProbe } from "../src/mcp/rest-proxy.js";
describe("MCP proxy credential origins", () => {
@@ -115,6 +116,48 @@ describe("MCP proxy credential origins", () => {
expect(redirects).toEqual(["error", "error"]);
});
+ it.each(["probe", "write"])("does not send local credentials or data to a redirected %s destination", async (phase) => {
+ const redirected: string[] = [];
+ const authorization: Array<string | undefined> = [];
+ const destination = createServer((req, res) => {
+ redirected.push(req.url ?? "");
+ res.end("{}");
+ });
+ const listen = async (server: Server) => {
+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+ const address = server.address();
+ if (!address || typeof address === "string") throw new Error("missing server address");
+ return `http://127.0.0.1:${address.port}`;
+ };
+ const destinationUrl = await listen(destination);
+ const origin = createServer((req, res) => {
+ authorization.push(req.headers.authorization);
+ if (phase === "write" && req.url === "/agentmemory/livez") res.end("{}");
+ else {
+ res.writeHead(307, { location: `${destinationUrl}/redirected` });
+ res.end();
+ }
+ });
+ try {
+ vi.stubEnv("AGENTMEMORY_URL", await listen(origin));
+ vi.stubEnv("AGENTMEMORY_SECRET", "synthetic-local-secret");
+ const handle = await resolveHandle();
+ if (phase === "probe") expect(handle.mode).toBe("local");
+ else {
+ if (handle.mode !== "proxy") throw new Error("expected proxy mode");
+ await expect(handle.call("/agentmemory/remember", {
+ method: "POST", body: '{"content":"synthetic"}', redirect: "follow",
+ })).rejects.toThrow();
+ }
+ expect(authorization).toEqual(Array(phase === "probe" ? 1 : 2).fill("Bearer synthetic-local-secret"));
+ expect(redirected).toEqual([]);
+ } finally {
+ origin.closeAllConnections();
+ destination.closeAllConnections();
+ await Promise.all([origin, destination].map(server => new Promise<void>(resolve => server.close(() => resolve()))));
+ }
+ });
+
it.each([
"file:///synthetic-url-secret", "https://user:[email protected]",
"https://example.invalid/?token=synthetic-url-secret", "https://example.invalid/#synthetic-url-secret",
diff --git a/tsdown.config.ts b/tsdown.config.ts
index 5662b385..8257636a 100644
--- a/tsdown.config.ts
+++ b/tsdown.config.ts
@@ -18,6 +18,14 @@ const hookEntries = [
"src/hooks/_capture.ts",
];
+// Cursor gets a thin adapter rather than its own hook copies: two CLI
+// entrypoints that resolve the workspace Cursor fails to report, then
+// delegate to the canonical hooks above. workspace.ts/delegate.ts are not
+// entries — they inline into each CLI, so the emitted files stay
+// self-contained like every other hook, and the canonical .mjs they spawn
+// sit exactly one directory up from plugin/scripts/cursor/.
+const cursorEntries = ["src/hooks/cursor/run-hook.ts", "src/hooks/cursor/run-detached.ts"];
+
const sharedCaptureModule = {
name: "agentmemory-shared-capture",
resolveId(source: string) {
@@ -126,4 +134,11 @@ export default defineConfig([
clean: false,
sourcemap: false,
})),
+ ...cursorEntries.map((entry) => ({
+ entry: [entry],
+ outDir: "plugin/scripts/cursor",
+ ...shared,
+ clean: false,
+ sourcemap: false,
+ })),
]);