Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

feat: Cursor-independent ECC memory via ECC_AGENT_DATA_HOME (#2066)

Tom Cruise Missile6a40469408c6
diff --git a/.env.example b/.env.example
index ec0ddba51..8169a46bf 100644
--- a/.env.example
+++ b/.env.example
@@ -30,6 +30,11 @@ ASTRAFLOW_CN_API_KEY=
# ASTRAFLOW_CN_MODEL=gpt-4o-mini
# ASTRAFLOW_CN_BASE_URL=https://api.modelverse.cn/v1
+# ─── ECC agent data (multi-harness isolation) ───────────────────────────────
+# Memory hooks (sessions, learned skills, aliases, metrics). Default: ~/.claude
+# Use a separate root when running ECC in Cursor alongside Claude Code:
+# ECC_AGENT_DATA_HOME=$HOME/.cursor/ecc
+
# ─── Session & Security ─────────────────────────────────────────────────────
# GitHub username (used by CI scripts for credential context)
GITHUB_USER="your-github-username"
diff --git a/README.md b/README.md
index 9cc9e7d32..2883c76e8 100644
--- a/README.md
+++ b/README.md
@@ -487,6 +487,7 @@ export ECC_SESSION_RETENTION_DAYS=14
export ECC_CONTEXT_MONITOR_COST_WARNINGS=off
```
+
Windows PowerShell:
```powershell
@@ -494,6 +495,24 @@ Windows PowerShell:
[Environment]::SetEnvironmentVariable('ECC_SESSION_RETENTION_DAYS', '14', 'User')
```
+### Agent data home (multi-harness isolation)
+
+Memory persistence hooks (session summaries, learned skills, session aliases, metrics) store data under a single agent data root. By default that root is `~/.claude`. When you use ECC in both Claude Code and Cursor on the same machine, set a separate root for Cursor so the two environments do not overwrite each other's session files:
+
+```bash
+# Cursor-only boundary (Claude Code keeps the default ~/.claude)
+export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc"
+```
+
+Paths resolved under that root include:
+
+- `$ECC_AGENT_DATA_HOME/session-data/` — session summaries
+- `$ECC_AGENT_DATA_HOME/skills/learned/` — learned skills from evaluate-session
+- `$ECC_AGENT_DATA_HOME/session-aliases.json` — session aliases
+- `$ECC_AGENT_DATA_HOME/metrics/` — cost and activity metrics
+
+See [affaan-m/ECC#2065](https://github.com/affaan-m/ECC/issues/2065).
+
---
## What's Inside
@@ -1261,6 +1280,25 @@ ECC does not install root `AGENTS.md` into `.cursor/`. Cursor treats nested `AGE
Cursor-native loading behavior can vary by Cursor build. ECC installs agents as `.cursor/agents/ecc-*.md`; if your Cursor build does not expose project agents, those files still work as explicit reference definitions instead of hidden global prompt context.
+### Memory and data isolation (Cursor + Claude Code)
+
+ECC memory hooks reuse the same `scripts/hooks/*.js` as Claude Code. For Cursor, ECC tries to keep memory **out of `~/.claude` automatically**:
+
+1. **Cursor `sessionStart` hook** (installed to `.cursor/hooks.json` on `--target cursor`) injects `ECC_AGENT_DATA_HOME` for the whole composer session.
+2. **Hook runtime default** — when `CURSOR_VERSION` or `CURSOR_PROJECT_DIR` is present, hooks default to `~/.cursor/ecc` if the env var is unset.
+3. **Project config** — `.cursor/ecc-agent-data.json` documents and overrides the path (`agentDataHome`).
+4. **Always-on rule** — `.cursor/rules/ecc-agent-data-home.mdc` reminds the agent where memory lives.
+
+You can still override explicitly:
+
+```bash
+export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc"
+```
+
+To **share** memory with Claude Code on purpose, set `ECC_AGENT_DATA_HOME=~/.claude` in the shell or in `.cursor/ecc-agent-data.json`.
+
+Continuous learning v2 instincts remain separate under `CLV2_HOMUNCULUS_DIR` (default `~/.local/share/ecc-homunculus`).
+
### Hook Architecture (DRY Adapter Pattern)
Cursor has **more hook events than Claude Code** (20 vs 8). The `.cursor/hooks/adapter.js` module transforms Cursor's stdin JSON to Claude Code's format, allowing existing `scripts/hooks/*.js` to be reused without duplication.
diff --git a/scaffolds/cursor/ecc-agent-data.json b/scaffolds/cursor/ecc-agent-data.json
new file mode 100644
index 000000000..a39a46ed9
--- /dev/null
+++ b/scaffolds/cursor/ecc-agent-data.json
@@ -0,0 +1,5 @@
+{
+ "$schema": "https://json.schemastore.org/json",
+ "description": "ECC agent data root for this project when using Cursor. Memory hooks read session summaries and learned skills from here instead of ~/.claude.",
+ "agentDataHome": "~/.cursor/ecc"
+}
diff --git a/scaffolds/cursor/hooks.json b/scaffolds/cursor/hooks.json
new file mode 100644
index 000000000..f4e389e8a
--- /dev/null
+++ b/scaffolds/cursor/hooks.json
@@ -0,0 +1,10 @@
+{
+ "version": 1,
+ "hooks": {
+ "sessionStart": [
+ {
+ "command": "node .cursor/scripts/hooks/cursor-session-env.js"
+ }
+ ]
+ }
+}
diff --git a/scaffolds/cursor/rules/ecc-agent-data-home.mdc b/scaffolds/cursor/rules/ecc-agent-data-home.mdc
new file mode 100644
index 000000000..c7e2b6085
--- /dev/null
+++ b/scaffolds/cursor/rules/ecc-agent-data-home.mdc
@@ -0,0 +1,16 @@
+---
+description: "ECC Cursor memory boundary — keeps session data out of Claude Code's ~/.claude"
+alwaysApply: true
+---
+
+# ECC agent data home (Cursor)
+
+This project uses ECC with **isolated memory persistence** for Cursor:
+
+- Default data root: `~/.cursor/ecc` (not `~/.claude`)
+- Env var: `ECC_AGENT_DATA_HOME` (set automatically by ECC's Cursor `sessionStart` hook when hooks are wired)
+- Project override: `.cursor/ecc-agent-data.json` → `agentDataHome`
+
+If the user asks where ECC stored session context or learned skills, point them at `$ECC_AGENT_DATA_HOME/session-data/` and `$ECC_AGENT_DATA_HOME/skills/learned/`.
+
+To **share** memory with Claude Code intentionally (not recommended for parallel use), set `ECC_AGENT_DATA_HOME` to `~/.claude` in the shell or in `.cursor/ecc-agent-data.json`.
diff --git a/scripts/hooks/cursor-session-env.js b/scripts/hooks/cursor-session-env.js
new file mode 100644
index 000000000..e5fe360ff
--- /dev/null
+++ b/scripts/hooks/cursor-session-env.js
@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * Cursor sessionStart hook — inject ECC_AGENT_DATA_HOME for the composer session.
+ *
+ * Cursor passes session-scoped env from sessionStart output to all later hooks.
+ * @see https://cursor.com/docs/hooks
+ */
+
+const {
+ getCursorSessionEnvPayload,
+ resolveAgentDataHome,
+ AGENT_DATA_HOME_ENV,
+} = require('../lib/agent-data-home');
+const { readStdinJson, log } = require('../lib/utils');
+
+function main() {
+ readStdinJson()
+ .then(() => {
+ const envPayload = getCursorSessionEnvPayload({ preferCursorDefault: true });
+ const agentDataHome = envPayload[AGENT_DATA_HOME_ENV];
+ const payload = {
+ env: envPayload,
+ additional_context: [
+ 'ECC memory persistence uses a dedicated agent data root for this Cursor session.',
+ `${AGENT_DATA_HOME_ENV}=${agentDataHome}`,
+ 'Session summaries, learned skills, aliases, and metrics live under that directory.',
+ 'Override via shell env, project .cursor/ecc-agent-data.json, or ECC docs (issue #2065).',
+ ].join('\n'),
+ };
+
+ process.stdout.write(`${JSON.stringify(payload)}\n`);
+ log(`[cursor-session-env] Set ${AGENT_DATA_HOME_ENV}=${agentDataHome}`);
+ process.exit(0);
+ })
+ .catch(error => {
+ const fallbackHome = resolveAgentDataHome({ preferCursorDefault: true });
+ const payload = {
+ env: { [AGENT_DATA_HOME_ENV]: fallbackHome },
+ };
+ process.stdout.write(`${JSON.stringify(payload)}\n`);
+ log(`[cursor-session-env] Fallback ${AGENT_DATA_HOME_ENV}=${fallbackHome} (${error.message})`);
+ process.exit(0);
+ });
+}
+
+if (require.main === module) {
+ main();
+}
+
+module.exports = { main };
diff --git a/scripts/hooks/plugin-hook-bootstrap.js b/scripts/hooks/plugin-hook-bootstrap.js
index aef94aab2..c965d4034 100644
--- a/scripts/hooks/plugin-hook-bootstrap.js
+++ b/scripts/hooks/plugin-hook-bootstrap.js
@@ -4,6 +4,7 @@
const fs = require('fs');
const path = require('path');
const { spawnSync } = require('child_process');
+const { ensureAgentDataHomeEnv } = require('../lib/agent-data-home');
function readStdinRaw() {
try {
@@ -83,14 +84,16 @@ function findShellBinary() {
}
function spawnNode(rootDir, relPath, raw, args) {
+ ensureAgentDataHomeEnv();
+ const hookEnv = {
+ ...process.env,
+ CLAUDE_PLUGIN_ROOT: rootDir,
+ ECC_PLUGIN_ROOT: rootDir,
+ };
return spawnSync(process.execPath, [resolveTarget(rootDir, relPath), ...args], {
input: raw,
encoding: 'utf8',
- env: {
- ...process.env,
- CLAUDE_PLUGIN_ROOT: rootDir,
- ECC_PLUGIN_ROOT: rootDir,
- },
+ env: hookEnv,
cwd: process.cwd(),
timeout: 30000,
windowsHide: true,
@@ -107,14 +110,16 @@ function spawnShell(rootDir, relPath, raw, args) {
};
}
+ ensureAgentDataHomeEnv();
+ const hookEnv = {
+ ...process.env,
+ CLAUDE_PLUGIN_ROOT: rootDir,
+ ECC_PLUGIN_ROOT: rootDir,
+ };
return spawnSync(shell, [resolveTarget(rootDir, relPath), ...args], {
input: raw,
encoding: 'utf8',
- env: {
- ...process.env,
- CLAUDE_PLUGIN_ROOT: rootDir,
- ECC_PLUGIN_ROOT: rootDir,
- },
+ env: hookEnv,
cwd: process.cwd(),
timeout: 30000,
windowsHide: true,
diff --git a/scripts/lib/agent-data-home.js b/scripts/lib/agent-data-home.js
new file mode 100644
index 000000000..32da5563a
--- /dev/null
+++ b/scripts/lib/agent-data-home.js
@@ -0,0 +1,199 @@
+/**
+ * Resolve ECC agent data home (memory persistence root) across harnesses.
+ *
+ * Docstring policy: public entry points here are documented; small internal
+ * helpers (e.g. `expandHomePath`, `readProjectConfigAt`) are left undocumented on
+ * purpose, consistent with ECC script modules elsewhere. Automated PR reviewers
+ * (e.g. CodeRabbit) may still flag low JSDoc coverage against a high threshold on
+ * the diff—that check is informational for this repo, not a bar every helper in
+ * touched files must meet. Prefer clarity in code and tests over blanket JSDoc on
+ * private helpers unless maintainers adopt a project-wide coverage rule.
+ *
+ * @see https://github.com/affaan-m/ECC/issues/2065
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENT_DATA_HOME_ENV = 'ECC_AGENT_DATA_HOME';
+const DEFAULT_CLAUDE_DIR_NAME = '.claude';
+const DEFAULT_CURSOR_ECC_DIR_SEGMENTS = ['.cursor', 'ecc'];
+const PROJECT_CONFIG_RELATIVE = path.join('.cursor', 'ecc-agent-data.json');
+
+/**
+ * Home directory for tilde expansion and default agent-data paths.
+ *
+ * Intentionally mirrors `getHomeDir()` in `scripts/lib/utils.js` (HOME/USERPROFILE,
+ * then `os.homedir()`). Do not import `utils.getHomeDir` here: `utils.js` already
+ * requires this module (`resolveAgentDataHome`), which would create a circular
+ * dependency and risk divergent defaults for `~/.cursor/ecc` vs `~/.claude`.
+ *
+ * If consolidation is needed later, prefer one of:
+ *
+ * | Approach | Tradeoff |
+ * | --- | --- |
+ * | Shared `scripts/lib/home-dir.js` imported by both | Clean; breaks the cycle |
+ * | Keep duplicate + cross-reference comment (this file) | Zero require risk |
+ * | Move all resolution here; thin-wrap from `utils` | Larger refactor |
+ */
+function getHomeDirFromEnv() {
+ const explicitHome = process.env.HOME || process.env.USERPROFILE;
+ if (explicitHome && String(explicitHome).trim().length > 0) {
+ return path.resolve(explicitHome);
+ }
+ return require('os').homedir();
+}
+
+function expandHomePath(value, baseDir) {
+ if (!value || typeof value !== 'string') return null;
+ const trimmed = value.trim();
+ if (!trimmed) return null;
+ if (trimmed.startsWith('~')) {
+ const remainder = trimmed.slice(1).replace(/^[/\\]+/, '');
+ return remainder ? path.join(getHomeDirFromEnv(), remainder) : getHomeDirFromEnv();
+ }
+ if (path.isAbsolute(trimmed)) {
+ return path.resolve(trimmed);
+ }
+ const base = baseDir && String(baseDir).trim()
+ ? path.resolve(baseDir)
+ : process.cwd();
+ return path.resolve(base, trimmed);
+}
+
+/**
+ * Project root for a config file under .cursor/ecc-agent-data.json.
+ */
+function resolveProjectRootFromConfigPath(configPath) {
+ const configDir = path.dirname(path.resolve(configPath));
+ if (path.basename(configDir) === '.cursor') {
+ return path.dirname(configDir);
+ }
+ return configDir;
+}
+
+/**
+ * True when the current process is a Cursor hook subprocess.
+ * Cursor documents CURSOR_VERSION and CURSOR_PROJECT_DIR for hook scripts.
+ */
+function isCursorHookRuntime() {
+ if (process.env.CURSOR_VERSION && String(process.env.CURSOR_VERSION).trim()) {
+ return true;
+ }
+ if (process.env.CURSOR_PROJECT_DIR && String(process.env.CURSOR_PROJECT_DIR).trim()) {
+ return true;
+ }
+ return false;
+}
+
+function getDefaultCursorAgentDataHome() {
+ return path.join(getHomeDirFromEnv(), ...DEFAULT_CURSOR_ECC_DIR_SEGMENTS);
+}
+
+function getDefaultClaudeAgentDataHome() {
+ return path.join(getHomeDirFromEnv(), DEFAULT_CLAUDE_DIR_NAME);
+}
+
+function readProjectConfigAt(configPath) {
+ if (!configPath || typeof configPath !== 'string') return null;
+ if (!fs.existsSync(configPath)) return null;
+
+ try {
+ const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+ const candidate = parsed.agentDataHome || parsed.ECC_AGENT_DATA_HOME;
+ if (typeof candidate !== 'string' || !candidate.trim()) return null;
+ const projectRoot = resolveProjectRootFromConfigPath(configPath);
+ return expandHomePath(candidate, projectRoot);
+ } catch (error) {
+ console.error(
+ `[ECC] Failed to read or parse agent data config at ${configPath}: ${error.message}`
+ );
+ return null;
+ }
+}
+
+function readProjectConfig(projectDir) {
+ if (!projectDir || typeof projectDir !== 'string') return null;
+ return readProjectConfigAt(path.join(path.resolve(projectDir), PROJECT_CONFIG_RELATIVE));
+}
+
+function resolveProjectDir() {
+ const candidates = [
+ process.env.CURSOR_PROJECT_DIR,
+ process.env.CLAUDE_PROJECT_DIR,
+ process.cwd(),
+ ];
+
+ for (const candidate of candidates) {
+ if (!candidate || typeof candidate !== 'string') continue;
+ const resolved = path.resolve(candidate);
+ if (fs.existsSync(path.join(resolved, '.cursor'))) {
+ return resolved;
+ }
+ }
+
+ return process.cwd();
+}
+
+/**
+ * Resolve agent data home without mutating process.env.
+ */
+function resolveAgentDataHome(options = {}) {
+ const fromEnv = expandHomePath(process.env[AGENT_DATA_HOME_ENV]);
+ if (fromEnv) return fromEnv;
+
+ const projectDir = options.projectDir || resolveProjectDir();
+ const fromProject = readProjectConfig(projectDir);
+ if (fromProject) return fromProject;
+
+ if (options.preferCursorDefault === true || isCursorHookRuntime()) {
+ return getDefaultCursorAgentDataHome();
+ }
+
+ return getDefaultClaudeAgentDataHome();
+}
+
+/**
+ * Set ECC_AGENT_DATA_HOME on the current process when unset (hook subprocess safety net).
+ * @returns {string} Resolved agent data home
+ */
+function ensureAgentDataHomeEnv(options = {}) {
+ const resolved = resolveAgentDataHome(options);
+ if (!expandHomePath(process.env[AGENT_DATA_HOME_ENV])) {
+ process.env[AGENT_DATA_HOME_ENV] = resolved;
+ }
+ return resolved;
+}
+
+/**
+ * Build Cursor sessionStart hook output env payload.
+ */
+function getCursorSessionEnvPayload(options = {}) {
+ const agentDataHome = resolveAgentDataHome({
+ ...options,
+ preferCursorDefault: true,
+ });
+
+ return {
+ ECC_AGENT_DATA_HOME: agentDataHome,
+ };
+}
+
+module.exports = {
+ AGENT_DATA_HOME_ENV,
+ DEFAULT_CLAUDE_DIR_NAME,
+ DEFAULT_CURSOR_ECC_DIR_SEGMENTS,
+ PROJECT_CONFIG_RELATIVE,
+ expandHomePath,
+ resolveProjectRootFromConfigPath,
+ isCursorHookRuntime,
+ getDefaultCursorAgentDataHome,
+ getDefaultClaudeAgentDataHome,
+ readProjectConfig,
+ readProjectConfigAt,
+ resolveProjectDir,
+ resolveAgentDataHome,
+ ensureAgentDataHomeEnv,
+ getCursorSessionEnvPayload,
+};
diff --git a/scripts/lib/install-executor.js b/scripts/lib/install-executor.js
index dc29f1c8c..ce2274eab 100644
--- a/scripts/lib/install-executor.js
+++ b/scripts/lib/install-executor.js
@@ -207,6 +207,52 @@ function readJsonObject(filePath, label) {
return parsed;
}
+function addCursorAgentDataScaffoldOperations(operations, options) {
+ const scaffoldRoot = path.join(options.sourceRoot, 'scaffolds', 'cursor');
+ if (!fs.existsSync(scaffoldRoot)) {
+ return;
+ }
+
+ addFileCopyOperation(operations, {
+ moduleId: options.moduleId,
+ sourceRoot: options.sourceRoot,
+ sourceRelativePath: path.join('scaffolds', 'cursor', 'ecc-agent-data.json'),
+ destinationPath: path.join(options.targetRoot, 'ecc-agent-data.json'),
+ strategy: 'preserve-relative-path',
+ });
+
+ addFileCopyOperation(operations, {
+ moduleId: options.moduleId,
+ sourceRoot: options.sourceRoot,
+ sourceRelativePath: path.join('scaffolds', 'cursor', 'rules', 'ecc-agent-data-home.mdc'),
+ destinationPath: path.join(options.targetRoot, 'rules', 'ecc-agent-data-home.mdc'),
+ strategy: 'preserve-relative-path',
+ });
+
+ addJsonMergeOperation(operations, {
+ moduleId: options.moduleId,
+ sourceRoot: options.sourceRoot,
+ sourceRelativePath: path.join('scaffolds', 'cursor', 'hooks.json'),
+ destinationPath: path.join(options.targetRoot, 'hooks.json'),
+ });
+
+ const cursorSessionHookDeps = [
+ path.join('scripts', 'hooks', 'cursor-session-env.js'),
+ path.join('scripts', 'lib', 'agent-data-home.js'),
+ path.join('scripts', 'lib', 'utils.js'),
+ ];
+
+ for (const sourceRelativePath of cursorSessionHookDeps) {
+ addFileCopyOperation(operations, {
+ moduleId: options.moduleId,
+ sourceRoot: options.sourceRoot,
+ sourceRelativePath,
+ destinationPath: path.join(options.targetRoot, sourceRelativePath),
+ strategy: 'preserve-relative-path',
+ });
+ }
+}
+
function addJsonMergeOperation(operations, options) {
const sourcePath = path.join(options.sourceRoot, options.sourceRelativePath);
if (!fs.existsSync(sourcePath)) {
@@ -405,6 +451,12 @@ function planCursorLegacyInstall(context) {
destinationPath: path.join(targetRoot, 'mcp.json'),
});
+ addCursorAgentDataScaffoldOperations(operations, {
+ moduleId: 'legacy-cursor-install',
+ sourceRoot: context.sourceRoot,
+ targetRoot,
+ });
+
return {
mode: 'legacy',
adapter,
diff --git a/scripts/lib/session-aliases.d.ts b/scripts/lib/session-aliases.d.ts
index c1744713f..3930dc722 100644
--- a/scripts/lib/session-aliases.d.ts
+++ b/scripts/lib/session-aliases.d.ts
@@ -1,6 +1,6 @@
/**
* Session Aliases Library for Claude Code.
- * Manages named aliases for session files, stored in ~/.claude/session-aliases.json.
+ * Manages named aliases for session files, stored in $ECC_AGENT_DATA_HOME/session-aliases.json (default ~/.claude).
*/
/** Internal alias storage entry */
diff --git a/scripts/lib/session-aliases.js b/scripts/lib/session-aliases.js
index cf9acdaab..bfc846315 100644
--- a/scripts/lib/session-aliases.js
+++ b/scripts/lib/session-aliases.js
@@ -1,6 +1,6 @@
/**
* Session Aliases Library for Claude Code
- * Manages session aliases stored in ~/.claude/session-aliases.json
+ * Manages session aliases stored in $ECC_AGENT_DATA_HOME/session-aliases.json (default ~/.claude).
*/
const fs = require('fs');
diff --git a/scripts/lib/utils.d.ts b/scripts/lib/utils.d.ts
index 55d276217..9e980c699 100644
--- a/scripts/lib/utils.d.ts
+++ b/scripts/lib/utils.d.ts
@@ -15,19 +15,25 @@ export const isLinux: boolean;
/** Get the user's home directory (cross-platform) */
export function getHomeDir(): string;
-/** Get the Claude config directory (~/.claude) */
+/**
+ * ECC agent data root for memory persistence and related state.
+ * Defaults to ~/.claude; override with ECC_AGENT_DATA_HOME (e.g. ~/.cursor/ecc).
+ */
+export function getAgentDataHome(): string;
+
+/** Get the agent data directory (alias of getAgentDataHome) */
export function getClaudeDir(): string;
-/** Get the canonical ECC sessions directory (~/.claude/session-data) */
+/** Get the canonical ECC sessions directory ($ECC_AGENT_DATA_HOME/session-data) */
export function getSessionsDir(): string;
-/** Get the legacy Claude-managed sessions directory (~/.claude/sessions) */
+/** Get the legacy sessions directory ($ECC_AGENT_DATA_HOME/sessions) */
export function getLegacySessionsDir(): string;
/** Get session directories to search, with canonical storage first and legacy fallback second */
export function getSessionSearchDirs(): string[];
-/** Get the learned skills directory (~/.claude/skills/learned) */
+/** Get the learned skills directory ($ECC_AGENT_DATA_HOME/skills/learned) */
export function getLearnedSkillsDir(): string;
/** Get the temp directory (cross-platform) */
diff --git a/scripts/lib/utils.js b/scripts/lib/utils.js
index f1717e5d3..a201e234e 100644
--- a/scripts/lib/utils.js
+++ b/scripts/lib/utils.js
@@ -15,6 +15,9 @@ const isMacOS = process.platform === 'darwin';
const isLinux = process.platform === 'linux';
const SESSION_DATA_DIR_NAME = 'session-data';
const LEGACY_SESSIONS_DIR_NAME = 'sessions';
+const {
+ resolveAgentDataHome,
+} = require('./agent-data-home');
const WINDOWS_RESERVED_SESSION_IDS = new Set([
'CON', 'PRN', 'AUX', 'NUL',
'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
@@ -33,12 +36,20 @@ function getHomeDir() {
}
/**
- * Get the Claude config directory
+ * ECC agent data root for memory persistence (see scripts/lib/agent-data-home.js).
+ */
+function getAgentDataHome() {
+ return resolveAgentDataHome();
+}
+
+/**
+ * Get the Claude config directory (alias of getAgentDataHome for backwards compatibility).
*/
function getClaudeDir() {
- return path.join(getHomeDir(), '.claude');
+ return getAgentDataHome();
}
+
/**
* Get the sessions directory
*/
@@ -585,6 +596,7 @@ module.exports = {
// Directories
getHomeDir,
+ getAgentDataHome,
getClaudeDir,
getSessionsDir,
getLegacySessionsDir,
diff --git a/tests/lib/agent-data-home.test.js b/tests/lib/agent-data-home.test.js
new file mode 100644
index 000000000..21909b56e
--- /dev/null
+++ b/tests/lib/agent-data-home.test.js
@@ -0,0 +1,260 @@
+/**
+ * Tests for scripts/lib/agent-data-home.js
+ *
+ * Run with: node tests/lib/agent-data-home.test.js
+ *
+ * Cwd / project context: many cases use `withIsolatedCwd()` (empty temp dir, no
+ * `.cursor/`) so results do not depend on running inside a dogfooded ECC repo.
+ * When this repo has `.cursor/ecc-agent-data.json` installed, `resolveAgentDataHome()`
+ * from the real project root intentionally resolves to `~/.cursor/ecc` — see the
+ * dedicated test below; do not expect `~/.claude` while cwd is the ECC tree.
+ */
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+function test(name, fn) {
+ try {
+ fn();
+ console.log(` ✓ ${name}`);
+ return true;
+ } catch (error) {
+ console.log(` ✗ ${name}`);
+ console.log(` Error: ${error.message}`);
+ return false;
+ }
+}
+
+function withEnv(overrides, fn) {
+ const previous = {};
+ for (const key of Object.keys(overrides)) {
+ previous[key] = process.env[key];
+ if (overrides[key] === undefined) {
+ delete process.env[key];
+ } else {
+ process.env[key] = overrides[key];
+ }
+ }
+
+ try {
+ fn();
+ } finally {
+ for (const key of Object.keys(previous)) {
+ if (previous[key] === undefined) {
+ delete process.env[key];
+ } else {
+ process.env[key] = previous[key];
+ }
+ }
+ delete require.cache[require.resolve('../../scripts/lib/agent-data-home')];
+ }
+}
+
+/**
+ * Run fn with cwd in an empty directory (no .cursor/) so resolveProjectDir() does
+ * not pick up the ECC repo's installed agent-data config.
+ */
+function withIsolatedCwd(fn) {
+ const isolatedDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-agent-data-home-'));
+ const originalCwd = process.cwd();
+ try {
+ process.chdir(isolatedDir);
+ return fn(isolatedDir);
+ } finally {
+ process.chdir(originalCwd);
+ fs.rmSync(isolatedDir, { recursive: true, force: true });
+ }
+}
+
+function runTests() {
+ console.log('\n=== Testing agent-data-home.js ===\n');
+ let passed = 0;
+ let failed = 0;
+
+ if (test('defaults to ~/.claude outside Cursor (isolated cwd)', () => {
+ withIsolatedCwd(() => {
+ withEnv({
+ ECC_AGENT_DATA_HOME: undefined,
+ CURSOR_VERSION: undefined,
+ CURSOR_PROJECT_DIR: undefined,
+ }, () => {
+ const agentDataHome = require('../../scripts/lib/agent-data-home');
+ const home = os.homedir();
+ assert.strictEqual(
+ agentDataHome.resolveAgentDataHome(),
+ path.join(home, '.claude')
+ );
+ });
+ });
+ })) passed++; else failed++;
+
+ if (test('resolveAgentDataHome uses projectDir + .cursor/ecc-agent-data.json', () => {
+ const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-agent-data-home-project-'));
+ const cursorDir = path.join(projectDir, '.cursor');
+ fs.mkdirSync(cursorDir, { recursive: true });
+ fs.writeFileSync(
+ path.join(cursorDir, 'ecc-agent-data.json'),
+ JSON.stringify({ agentDataHome: '~/.cursor/ecc' }),
+ 'utf8'
+ );
+
+ try {
+ withIsolatedCwd(() => {
+ withEnv({
+ ECC_AGENT_DATA_HOME: undefined,
+ CURSOR_VERSION: undefined,
+ CURSOR_PROJECT_DIR: undefined,
+ }, () => {
+ const agentDataHome = require('../../scripts/lib/agent-data-home');
+ assert.strictEqual(
+ agentDataHome.resolveAgentDataHome({ projectDir }),
+ path.join(os.homedir(), '.cursor', 'ecc')
+ );
+ });
+ });
+ } finally {
+ fs.rmSync(projectDir, { recursive: true, force: true });
+ }
+ })) passed++; else failed++;
+
+ if (test('defaults to ~/.cursor/ecc in Cursor hook runtime (isolated cwd)', () => {
+ withIsolatedCwd(() => {
+ withEnv({
+ ECC_AGENT_DATA_HOME: undefined,
+ CURSOR_VERSION: '1.0.0',
+ CURSOR_PROJECT_DIR: undefined,
+ }, () => {
+ const agentDataHome = require('../../scripts/lib/agent-data-home');
+ const home = os.homedir();
+ assert.strictEqual(
+ agentDataHome.resolveAgentDataHome(),
+ path.join(home, '.cursor', 'ecc')
+ );
+ });
+ });
+ })) passed++; else failed++;
+
+ if (test('honors ECC_AGENT_DATA_HOME over Cursor default', () => {
+ const override = path.join(os.tmpdir(), `ecc-override-${Date.now()}`);
+ withEnv({
+ ECC_AGENT_DATA_HOME: override,
+ CURSOR_VERSION: '1.0.0',
+ }, () => {
+ const agentDataHome = require('../../scripts/lib/agent-data-home');
+ assert.strictEqual(agentDataHome.resolveAgentDataHome(), path.resolve(override));
+ });
+ })) passed++; else failed++;
+
+ if (test('reads project ecc-agent-data.json config file', () => {
+ const tmpDir = path.join(os.tmpdir(), `ecc-agent-data-home-read-${Date.now()}`);
+ fs.mkdirSync(tmpDir, { recursive: true });
+ const configPath = path.join(tmpDir, 'ecc-agent-data.json');
+ const customHome = path.join(tmpDir, 'data-root');
+ fs.writeFileSync(
+ configPath,
+ JSON.stringify({ agentDataHome: customHome }),
+ 'utf8'
+ );
+
+ try {
+ withEnv({
+ ECC_AGENT_DATA_HOME: undefined,
+ CURSOR_VERSION: undefined,
+ }, () => {
+ const agentDataHome = require('../../scripts/lib/agent-data-home');
+ assert.strictEqual(
+ agentDataHome.readProjectConfigAt(configPath),
+ path.resolve(customHome)
+ );
+ });
+ } finally {
+ fs.rmSync(tmpDir, { recursive: true, force: true });
+ }
+ })) passed++; else failed++;
+
+ if (test('resolves relative agentDataHome against project root, not cwd', () => {
+ const stamp = Date.now();
+ const projectDir = path.join(os.tmpdir(), `ecc-agent-data-home-relative-${stamp}`);
+ const cursorDir = path.join(projectDir, '.cursor');
+ const otherCwd = path.join(os.tmpdir(), `ecc-agent-data-home-other-cwd-${stamp}`);
+ fs.mkdirSync(cursorDir, { recursive: true });
+ fs.mkdirSync(otherCwd, { recursive: true });
+ const configPath = path.join(cursorDir, 'ecc-agent-data.json');
+ const expectedHome = path.join(projectDir, '.ecc-data');
+ fs.writeFileSync(
+ configPath,
+ JSON.stringify({ agentDataHome: '.ecc-data' }),
+ 'utf8'
+ );
+
+ const originalCwd = process.cwd();
+ try {
+ process.chdir(otherCwd);
+ withEnv({
+ ECC_AGENT_DATA_HOME: undefined,
+ CURSOR_VERSION: undefined,
+ CURSOR_PROJECT_DIR: projectDir,
+ }, () => {
+ const agentDataHome = require('../../scripts/lib/agent-data-home');
+ assert.strictEqual(agentDataHome.readProjectConfigAt(configPath), expectedHome);
+ assert.strictEqual(
+ agentDataHome.resolveAgentDataHome({ projectDir }),
+ expectedHome
+ );
+ });
+ } finally {
+ process.chdir(originalCwd);
+ fs.rmSync(projectDir, { recursive: true, force: true });
+ fs.rmSync(otherCwd, { recursive: true, force: true });
+ }
+ })) passed++; else failed++;
+
+ if (test('readProjectConfigAt logs parse failures', () => {
+ const tmpDir = path.join(os.tmpdir(), `ecc-agent-data-home-log-${Date.now()}`);
+ fs.mkdirSync(tmpDir, { recursive: true });
+ const configPath = path.join(tmpDir, 'ecc-agent-data.json');
+ fs.writeFileSync(configPath, '{ invalid json', 'utf8');
+
+ const originalError = console.error;
+ const messages = [];
+ console.error = (...args) => {
+ messages.push(args.join(' '));
+ };
+
+ try {
+ withEnv({
+ ECC_AGENT_DATA_HOME: undefined,
+ CURSOR_VERSION: undefined,
+ }, () => {
+ const agentDataHome = require('../../scripts/lib/agent-data-home');
+ assert.strictEqual(agentDataHome.readProjectConfigAt(configPath), null);
+ assert.ok(
+ messages.some(message => message.includes(configPath)),
+ 'Expected config path in error log'
+ );
+ });
+ } finally {
+ console.error = originalError;
+ fs.rmSync(tmpDir, { recursive: true, force: true });
+ }
+ })) passed++; else failed++;
+
+ if (test('ensureAgentDataHomeEnv sets process.env when unset', () => {
+ withEnv({
+ ECC_AGENT_DATA_HOME: undefined,
+ CURSOR_VERSION: '1.0.0',
+ }, () => {
+ const agentDataHome = require('../../scripts/lib/agent-data-home');
+ const resolved = agentDataHome.ensureAgentDataHomeEnv();
+ assert.ok(process.env.ECC_AGENT_DATA_HOME);
+ assert.strictEqual(process.env.ECC_AGENT_DATA_HOME, resolved);
+ });
+ })) passed++; else failed++;
+
+ console.log(`\n=== Test Results ===\nPassed: ${passed}\nFailed: ${failed}\n`);
+ if (failed > 0) process.exit(1);
+}
+
+runTests();
diff --git a/tests/lib/utils.test.js b/tests/lib/utils.test.js
index 3217567a2..54fa8dfca 100644
--- a/tests/lib/utils.test.js
+++ b/tests/lib/utils.test.js
@@ -115,7 +115,79 @@ function runTests() {
const sessionsDir = utils.getSessionsDir();
const claudeDir = utils.getClaudeDir();
assert.ok(sessionsDir.startsWith(claudeDir), 'Sessions should be under Claude dir');
- assert.ok(sessionsDir.endsWith(path.join('.claude', 'session-data')) || sessionsDir.endsWith('/.claude/session-data'), 'Should use canonical session-data directory');
+ assert.ok(sessionsDir.endsWith('session-data'), 'Should use canonical session-data directory');
+ })) passed++; else failed++;
+
+ if (test('getAgentDataHome honors ECC_AGENT_DATA_HOME', () => {
+ const original = process.env.ECC_AGENT_DATA_HOME;
+ const overrideRoot = path.join(utils.getTempDir(), `ecc-agent-data-${Date.now()}`);
+ try {
+ process.env.ECC_AGENT_DATA_HOME = overrideRoot;
+ delete require.cache[require.resolve('../../scripts/lib/utils')];
+ const reloaded = require('../../scripts/lib/utils');
+ assert.strictEqual(reloaded.getAgentDataHome(), path.resolve(overrideRoot));
+ assert.strictEqual(reloaded.getClaudeDir(), path.resolve(overrideRoot));
+ assert.strictEqual(
+ reloaded.getSessionsDir(),
+ path.join(path.resolve(overrideRoot), 'session-data')
+ );
+ assert.strictEqual(
+ reloaded.getLearnedSkillsDir(),
+ path.join(path.resolve(overrideRoot), 'skills', 'learned')
+ );
+ } finally {
+ delete require.cache[require.resolve('../../scripts/lib/utils')];
+ if (original === undefined) {
+ delete process.env.ECC_AGENT_DATA_HOME;
+ } else {
+ process.env.ECC_AGENT_DATA_HOME = original;
+ }
+ }
+ })) passed++; else failed++;
+
+ if (test('getAgentDataHome defaults to ~/.cursor/ecc when CURSOR_VERSION is set', () => {
+ const originalVersion = process.env.CURSOR_VERSION;
+ const originalHome = process.env.ECC_AGENT_DATA_HOME;
+ try {
+ delete process.env.ECC_AGENT_DATA_HOME;
+ process.env.CURSOR_VERSION = 'test-cursor';
+ delete require.cache[require.resolve('../../scripts/lib/utils')];
+ delete require.cache[require.resolve('../../scripts/lib/agent-data-home')];
+ const reloaded = require('../../scripts/lib/utils');
+ const expected = path.join(reloaded.getHomeDir(), '.cursor', 'ecc');
+ assert.strictEqual(reloaded.getAgentDataHome(), expected);
+ } finally {
+ delete require.cache[require.resolve('../../scripts/lib/utils')];
+ delete require.cache[require.resolve('../../scripts/lib/agent-data-home')];
+ if (originalVersion === undefined) {
+ delete process.env.CURSOR_VERSION;
+ } else {
+ process.env.CURSOR_VERSION = originalVersion;
+ }
+ if (originalHome === undefined) {
+ delete process.env.ECC_AGENT_DATA_HOME;
+ } else {
+ process.env.ECC_AGENT_DATA_HOME = originalHome;
+ }
+ }
+ })) passed++; else failed++;
+
+ if (test('getAgentDataHome expands tilde in ECC_AGENT_DATA_HOME', () => {
+ const original = process.env.ECC_AGENT_DATA_HOME;
+ try {
+ process.env.ECC_AGENT_DATA_HOME = path.join('~', '.cursor', 'ecc-test');
+ delete require.cache[require.resolve('../../scripts/lib/utils')];
+ const reloaded = require('../../scripts/lib/utils');
+ const expected = path.join(reloaded.getHomeDir(), '.cursor', 'ecc-test');
+ assert.strictEqual(reloaded.getAgentDataHome(), expected);
+ } finally {
+ delete require.cache[require.resolve('../../scripts/lib/utils')];
+ if (original === undefined) {
+ delete process.env.ECC_AGENT_DATA_HOME;
+ } else {
+ process.env.ECC_AGENT_DATA_HOME = original;
+ }
+ }
})) passed++; else failed++;
if (test('getSessionSearchDirs includes canonical and legacy paths', () => {