diff --git a/docs/integrations/pi.md b/docs/integrations/pi.md
new file mode 100644
index 0000000..c4078f9
--- /dev/null
+++ b/docs/integrations/pi.md
@@ -0,0 +1,43 @@
+# PI integration (example)
+
+This project ships a small HTTP server that exposes engram's query, learn,
+and context streaming endpoints. To integrate with external tooling (like
+`pi`), you can call the server from your agent process to run the same
+hook handlers engram uses internally.
+
+Quick example (requires Node 20+ and the engram HTTP server running):
+
+1. Start the engram HTTP server for your project:
+
+   - From a built installation: `engramx serve --port 7337 --project /path/to/project`
+   - Or run the server via the CLI: `node dist/cli.js serve --port 7337 --project /path/to/project`
+
+   The server writes an auth token to `~/.engram/http-server.token` on first start.
+
+2. Run the example PI client that demonstrates the flow:
+
+   ```bash
+   node examples/pi-client.js /path/to/project
+   ```
+
+   The script will:
+   - Call `POST /hook` with a `SessionStart` payload (project brief + provider warmup)
+   - Call `POST /hook` with a `UserPromptSubmit` payload (pre-query injection)
+   - POST a session summary to `/learn` so engram can persist session learnings
+
+3. Production integration suggestions:
+
+   - Call `POST /hook` with `SessionStart` at the beginning of a user session
+     to warm provider caches and inject both project and global memory.
+   - During request processing, call `POST /hook` for `UserPromptSubmit` and
+     `PreToolUse` events (or use `GET /context/stream` and `/query`) to
+     resolve context on-demand.
+   - When the request completes and you have a session summary, call `POST /learn`
+     with the summary text so engram persists the learning in its graph.
+
+Security: all HTTP endpoints require an auth token (read from
+`~/.engram/http-server.token` or supplied via `Authorization: Bearer <token>`).
+This keeps the server local-only and fail-closed.
+
+If you want, I can add a small PI-side wrapper that calls these endpoints
+from the pi harness directly (example: a `pi` skill or integration).
\ No newline at end of file
diff --git a/docs/operations/dev-reload-port-audit.md b/docs/operations/dev-reload-port-audit.md
new file mode 100644
index 0000000..23319ea
--- /dev/null
+++ b/docs/operations/dev-reload-port-audit.md
@@ -0,0 +1,66 @@
+Dev-reload: port wait and startup audit
+
+Summary
+
+This document records the recent changes made to reduce transient EADDRINUSE errors during development reloads and to add a small startup audit line when the HTTP server writes its PID file.
+
+What was changed
+
+1) scripts/dev-reload.sh
+
+- After building the project, the script now waits (best-effort) for the configured PORT to be free before starting the server. This reduces races where nodemon spawns a new process while the old one is still closing and listening on the port.
+- Behavior is configurable via environment variables:
+  - WAIT_RETRIES (default: 16)
+  - SLEEP_INTERVAL (default: 0.5 seconds)
+- If the port remains busy after the retry loop the script proceeds anyway (non-blocking fallback) to avoid hanging CI or developer shells.
+
+2) src/server/http.ts
+
+- The writePid(projectRoot) helper still writes .engram/http-server.pid but now also appends an audit line with timestamp, pid, port, and project to two locations:
+  - <projectRoot>/.engram/http-server.start.log (project-scoped audit log)
+  - ~/.engram/http-server.log (user-level co-log)
+- Audit line format: <ISO timestamp> START pid=<pid> port=<port> project=<projectRoot>
+- Audit writes are best-effort; failures are swallowed so they don't block server startup.
+
+Why
+
+- Frequent EADDRINUSE errors were observed during rapid dev reloads. These are usually harmless (old process still closing) but they spam stderr and can hide real issues. Waiting briefly for the port to be released reduces noise and stabilizes local dev workflow.
+- The PID file used by the HUD / component-status can sometimes be missing during restart windows. The audit log makes it trivial to confirm when the server wrote the PID (and which pid/port it recorded), which aids debugging.
+
+Files modified
+
+- scripts/dev-reload.sh
+- src/server/http.ts
+
+How to test locally
+
+1) Force a dev rebuild (touch a source file and allow nodemon/dev watcher to run dev-reload)
+2) Watch the script output: you should see lines like:
+   [dev-reload] waiting for port 7337 to be free (still: <pids>) — attempt X/Y
+   [dev-reload] starting server via: node dist/cli.js ui ...
+3) After server starts, verify:
+   - cat <projectRoot>/.engram/http-server.pid → should contain the pid
+   - tail -n 50 <projectRoot>/.engram/http-server.start.log → last line is the START audit line
+   - tail -n 50 ~/.engram/http-server.log → contains the START audit line
+4) Exercise the dashboard/UI or POST a SessionStart hook to confirm the updated server responds with the injected project brief.
+
+Environment knobs
+
+- WAIT_RETRIES= number of attempts waiting for port to be free (default 16)
+- SLEEP_INTERVAL= seconds to sleep between attempts (default 0.5)
+
+Todo / Follow-ups (issues created)
+
+- [ ] Add a small integration test that verifies the audit line is written on server startup (requires test harness that can spawn the server).
+- [ ] Consider making the dev-reload script fail-hard if the port remains busy (configurable via env var) to avoid accidental double-runs in CI.
+- [ ] Rotate/trim the audit logs (project-level and user-level) to avoid unbounded disk growth.
+- [ ] Improve portability for environments without lsof (Windows) — consider a Node-based port probe helper or use netstat variations.
+- [ ] Expose the startup audit via component-status so the UI can show "Last startup at <ts> (pid)".
+
+Link to changes
+
+- Branch: feat/sessionstart-resume-auto-memory
+- Commits:
+  - dev: wait for port free in dev-reload; http: append startup audit line when writing pid
+
+If you'd like any of the follow-ups implemented now (tests, log rotation, stricter dev-reload behavior), tell me which ones and I'll implement them in follow-up commits/PRs.
diff --git a/examples/pi-client.js b/examples/pi-client.js
new file mode 100644
index 0000000..f982550
--- /dev/null
+++ b/examples/pi-client.js
@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * Example PI client that demonstrates calling engram's /hook and /learn endpoints.
+ *
+ * Usage: node examples/pi-client.js /path/to/project
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const PORT = process.env.ENGRAM_HTTP_PORT ?? 7337;
+const TOKEN_PATH = join(homedir(), ".engram", "http-server.token");
+
+function readToken() {
+  try {
+    const t = readFileSync(TOKEN_PATH, "utf-8").trim();
+    return t;
+  } catch (err) {
+    console.error("Failed to read token at", TOKEN_PATH, err?.message ?? err);
+    process.exit(1);
+  }
+}
+
+async function postHook(payload) {
+  const resp = await fetch(`http://127.0.0.1:${PORT}/hook`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${readToken()}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(payload),
+  });
+  if (resp.status === 204) return null;
+  return await resp.json();
+}
+
+async function postLearn(content, file) {
+  const resp = await fetch(`http://127.0.0.1:${PORT}/learn`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${readToken()}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ content, file }),
+  });
+  if (resp.status >= 400) {
+    const txt = await resp.text();
+    throw new Error(`learn failed: ${txt}`);
+  }
+  return await resp.json();
+}
+
+const projectRootArg = process.argv[2] ?? process.cwd();
+
+(async () => {
+  console.log("Project root:", projectRootArg);
+  console.log("Calling SessionStart...");
+  const session = await postHook({ hook_event_name: "SessionStart", cwd: projectRootArg, source: "startup" });
+  console.log("SessionStart result:", session);
+
+  console.log("Calling UserPromptSubmit...");
+  const prompt = await postHook({ hook_event_name: "UserPromptSubmit", cwd: projectRootArg, prompt: "How does authentication work?" });
+  console.log("UserPromptSubmit result:", prompt);
+
+  console.log("Posting a summary to /learn...");
+  const learn = await postLearn("Session summary: example decision to prefer JWT tokens", "pi-example");
+  console.log("Learn result:", learn);
+})().catch((err) => {
+  console.error("Error", err);
+  process.exit(1);
+});
diff --git a/package-lock.json b/package-lock.json
index 31abca3..1d1e2a7 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -7,6 +7,7 @@
     "": {
       "name": "engramx",
       "version": "3.4.0",
+      "hasInstallScript": true,
       "license": "Apache-2.0",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.29.0",
@@ -27,6 +28,7 @@
       },
       "devDependencies": {
         "@types/node": "^25.5.2",
+        "nodemon": "^3.0.2",
         "tsup": "^8.5.1",
         "typescript": "^6.0.2",
         "vitest": "^4.1.4"
@@ -1534,6 +1536,33 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/anymatch": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.3.tgz",
+      "integrity": "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "normalize-path": "^3.0.0",
+        "picomatch": "^2.0.4"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/anymatch/node_modules/picomatch": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
+      "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
     "node_modules/assertion-error": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
@@ -1544,6 +1573,29 @@
         "node": ">=12"
       }
     },
+    "node_modules/balanced-match": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
+      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
+    "node_modules/binary-extensions": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/binary-extensions/-/binary-extensions-2.3.0.tgz",
+      "integrity": "sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/body-parser": {
       "version": "2.2.2",
       "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.2.tgz",
@@ -1568,6 +1620,32 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/brace-expansion": {
+      "version": "5.0.5",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz",
+      "integrity": "sha512-VZznLgtwhn+Mact9tfiwx64fA9erHH/MCXEUfB/0bX/6Fz6ny5EGTXYltMocqg4xFAQZtnO3DHWWXi8RiuN7cQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^4.0.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
+    "node_modules/braces": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz",
+      "integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fill-range": "^7.1.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/bundle-require": {
       "version": "5.1.0",
       "resolved": "https://registry.npmjs.org/bundle-require/-/bundle-require-5.1.0.tgz",
@@ -2075,6 +2153,19 @@
         }
       }
     },
+    "node_modules/fill-range": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz",
+      "integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "to-regex-range": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/finalhandler": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-2.1.1.tgz",
@@ -2187,6 +2278,19 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/glob-parent": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz",
+      "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "is-glob": "^4.0.1"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
     "node_modules/gopd": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
@@ -2199,6 +2303,16 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/has-flag": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-3.0.0.tgz",
+      "integrity": "sha512-sKJf1+ceQBr4SMkvQnBDNDtf4TXpVhVGateu0t918bl30FnbE2m4vNLX+VWe/dpjlb+HugGYzW7uQXH98HPEYw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/has-symbols": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz",
@@ -2268,6 +2382,13 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/ignore-by-default": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/ignore-by-default/-/ignore-by-default-1.0.1.tgz",
+      "integrity": "sha512-Ius2VYcGNk7T90CppJqcIkS5ooHUZyIQK+ClZfMfMNFEF9VSE73Fq+906u/CWu92x4gzZMWOwfFYckPObzdEbA==",
+      "dev": true,
+      "license": "ISC"
+    },
     "node_modules/inherits": {
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
@@ -2292,6 +2413,52 @@
         "node": ">= 0.10"
       }
     },
+    "node_modules/is-binary-path": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/is-binary-path/-/is-binary-path-2.1.0.tgz",
+      "integrity": "sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "binary-extensions": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/is-extglob": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
+      "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/is-glob": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz",
+      "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-extglob": "^2.1.1"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/is-number": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz",
+      "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.12.0"
+      }
+    },
     "node_modules/is-promise": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz",
@@ -2703,6 +2870,22 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/minimatch": {
+      "version": "10.2.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.5.tgz",
+      "integrity": "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "brace-expansion": "^5.0.5"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/mlly": {
       "version": "1.8.2",
       "resolved": "https://registry.npmjs.org/mlly/-/mlly-1.8.2.tgz",
@@ -2782,6 +2965,96 @@
         "node-gyp-build-test": "build-test.js"
       }
     },
+    "node_modules/nodemon": {
+      "version": "3.1.14",
+      "resolved": "https://registry.npmjs.org/nodemon/-/nodemon-3.1.14.tgz",
+      "integrity": "sha512-jakjZi93UtB3jHMWsXL68FXSAosbLfY0In5gtKq3niLSkrWznrVBzXFNOEMJUfc9+Ke7SHWoAZsiMkNP3vq6Jw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "chokidar": "^3.5.2",
+        "debug": "^4",
+        "ignore-by-default": "^1.0.1",
+        "minimatch": "^10.2.1",
+        "pstree.remy": "^1.1.8",
+        "semver": "^7.5.3",
+        "simple-update-notifier": "^2.0.0",
+        "supports-color": "^5.5.0",
+        "touch": "^3.1.0",
+        "undefsafe": "^2.0.5"
+      },
+      "bin": {
+        "nodemon": "bin/nodemon.js"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/nodemon"
+      }
+    },
+    "node_modules/nodemon/node_modules/chokidar": {
+      "version": "3.6.0",
+      "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.6.0.tgz",
+      "integrity": "sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "anymatch": "~3.1.2",
+        "braces": "~3.0.2",
+        "glob-parent": "~5.1.2",
+        "is-binary-path": "~2.1.0",
+        "is-glob": "~4.0.1",
+        "normalize-path": "~3.0.0",
+        "readdirp": "~3.6.0"
+      },
+      "engines": {
+        "node": ">= 8.10.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.2"
+      }
+    },
+    "node_modules/nodemon/node_modules/picomatch": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
+      "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
+    "node_modules/nodemon/node_modules/readdirp": {
+      "version": "3.6.0",
+      "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz",
+      "integrity": "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "picomatch": "^2.2.1"
+      },
+      "engines": {
+        "node": ">=8.10.0"
+      }
+    },
+    "node_modules/normalize-path": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz",
+      "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/object-assign": {
       "version": "4.1.1",
       "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
@@ -3006,6 +3279,13 @@
         "node": ">= 0.10"
       }
     },
+    "node_modules/pstree.remy": {
+      "version": "1.1.8",
+      "resolved": "https://registry.npmjs.org/pstree.remy/-/pstree.remy-1.1.8.tgz",
+      "integrity": "sha512-77DZwxQmxKnu3aR542U+X8FypNzbfJ+C5XQDk3uWjWxn6151aIMGthWYRXTqT1E5oJvg+ljaa2OJi+VfvCOQ8w==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/qs": {
       "version": "6.15.1",
       "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.1.tgz",
@@ -3179,6 +3459,19 @@
       "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
       "license": "MIT"
     },
+    "node_modules/semver": {
+      "version": "7.7.4",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
+      "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/send": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/send/-/send-1.2.1.tgz",
@@ -3330,6 +3623,19 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/simple-update-notifier": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/simple-update-notifier/-/simple-update-notifier-2.0.0.tgz",
+      "integrity": "sha512-a2B9Y0KlNXl9u/vsW6sTIu9vGEpfKu2wRV6l1H3XEas/0gUIzGzBoP/IouTcUQbm9JWZLH3COxyn03TYlFax6w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "semver": "^7.5.3"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/source-map": {
       "version": "0.7.6",
       "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.7.6.tgz",
@@ -3412,6 +3718,19 @@
         "node": ">= 6"
       }
     },
+    "node_modules/supports-color": {
+      "version": "5.5.0",
+      "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-5.5.0.tgz",
+      "integrity": "sha512-QjVjwdXIt408MIiAqCX4oUKsgU2EqAGzs2Ppkm4aQYbjm+ZEWEcW4SfFNTr4uMNZma0ey4f5lgLrkB0aX0QMow==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "has-flag": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
     "node_modules/thenify": {
       "version": "3.3.1",
       "resolved": "https://registry.npmjs.org/thenify/-/thenify-3.3.1.tgz",
@@ -3476,6 +3795,19 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/to-regex-range": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",
+      "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-number": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=8.0"
+      }
+    },
     "node_modules/toidentifier": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz",
@@ -3485,6 +3817,16 @@
         "node": ">=0.6"
       }
     },
+    "node_modules/touch": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/touch/-/touch-3.1.1.tgz",
+      "integrity": "sha512-r0eojU4bI8MnHr8c5bNo7lJDdI2qXlWWJk6a9EAFG7vbhTjElYhBVS3/miuE0uOuoLdb8Mc/rVfsmm6eo5o9GA==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "nodetouch": "bin/nodetouch.js"
+      }
+    },
     "node_modules/tree-kill": {
       "version": "1.2.2",
       "resolved": "https://registry.npmjs.org/tree-kill/-/tree-kill-1.2.2.tgz",
@@ -3713,6 +4055,13 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/undefsafe": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/undefsafe/-/undefsafe-2.0.5.tgz",
+      "integrity": "sha512-WxONCrssBM8TSPRqN5EmsjVrsv4A8X12J4ArBiiayv3DyyG3ZlIg6yysuuSYdZsVz3TKcTg2fd//Ujd4CHV1iA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/undici-types": {
       "version": "7.18.2",
       "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.18.2.tgz",
diff --git a/package.json b/package.json
index a29468a..fe119e9 100644
--- a/package.json
+++ b/package.json
@@ -22,6 +22,7 @@
     "build": "tsup && node scripts/bundle-grammars.mjs",
     "build:nogrammars": "tsup",
     "dev": "tsup --watch",
+    "dev:reload": "nodemon --watch src --watch package.json --ext ts,js,json --exec \"bash scripts/dev-reload.sh\"",
     "test": "vitest",
     "lint": "tsc --noEmit",
     "prepublishOnly": "npm run build",
@@ -76,6 +77,7 @@
     "@types/node": "^25.5.2",
     "tsup": "^8.5.1",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.4"
+    "vitest": "^4.1.4",
+    "nodemon": "^3.0.2"
   }
 }
diff --git a/scripts/dev-reload.sh b/scripts/dev-reload.sh
new file mode 100644
index 0000000..8f26ae8
--- /dev/null
+++ b/scripts/dev-reload.sh
@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PORT=${PORT:-7337}
+PROJECT_ROOT="$(pwd)"
+PIDFILE="$PROJECT_ROOT/.engram/http-server.pid"
+
+echo "[dev-reload] port=$PORT project=$PROJECT_ROOT"
+
+# Kill anything listening on the target port. Try a portable lsof invocation.
+# Some lsof builds dislike the 127.0.0.1:PORT form — try a couple of variants.
+pids=$(lsof -ti "tcp:${PORT}" -sTCP:LISTEN 2>/dev/null || true)
+if [ -z "$pids" ]; then
+  pids=$(lsof -ti "TCP:${PORT}" -sTCP:LISTEN 2>/dev/null || true)
+fi
+if [ -n "$pids" ]; then
+  echo "[dev-reload] killing processes listening on 127.0.0.1:${PORT}: $pids"
+  echo "$pids" | xargs -r kill -9 || true
+fi
+
+# Also remove pidfile if present
+if [ -f "$PIDFILE" ]; then
+  echo "[dev-reload] found pidfile: $PIDFILE"
+  pidfile_pid=$(cat "$PIDFILE" 2>/dev/null || true)
+  if [ -n "$pidfile_pid" ]; then
+    echo "[dev-reload] killing pid from pidfile: $pidfile_pid"
+    kill -9 "$pidfile_pid" 2>/dev/null || true
+  fi
+  rm -f "$PIDFILE" || true
+fi
+
+# Build artifacts
+echo "[dev-reload] running npm run build"
+npm run build
+
+# Wait for the target port to be free before starting the server. This
+# avoids a race where nodemon spawns a new process while the old one is
+# still closing, producing EADDRINUSE errors. We retry a few times with
+# short sleeps and proceed even if the port remains busy (best-effort).
+WAIT_RETRIES=${WAIT_RETRIES:-16}
+SLEEP_INTERVAL=${SLEEP_INTERVAL:-0.5}
+for i in $(seq 1 "$WAIT_RETRIES"); do
+  pids=$(lsof -ti "tcp:${PORT}" -sTCP:LISTEN 2>/dev/null || true)
+  if [ -z "$pids" ]; then
+    echo "[dev-reload] port ${PORT} is free"
+    break
+  fi
+  echo "[dev-reload] waiting for port ${PORT} to be free (still: $pids) — attempt $i/$WAIT_RETRIES"
+  sleep "$SLEEP_INTERVAL"
+done
+
+# Start server via the CLI auto-start entrypoint (ui) so PID/lock semantics are consistent
+# Use --no-open to avoid launching a browser from dev script
+echo "[dev-reload] starting server via: node dist/cli.js ui --no-open --port ${PORT} -p ${PROJECT_ROOT}"
+node dist/cli.js ui --no-open --port "${PORT}" -p "${PROJECT_ROOT}"
+
+echo "[dev-reload] done"
diff --git a/src/autogen.ts b/src/autogen.ts
index 8fd6d32..3785524 100644
--- a/src/autogen.ts
+++ b/src/autogen.ts
@@ -14,8 +14,8 @@ import { join } from "node:path";
 import type { GraphStore } from "./graph/store.js";
 import type { GraphNode } from "./graph/schema.js";
 
-const AUTOGEN_START = "<!-- engram:start -->";
-const AUTOGEN_END = "<!-- engram:end -->";
+const AUTOGEN_START = "<!-- engramx:start -->";
+const AUTOGEN_END = "<!-- engramx:end -->";
 
 // ─── View data model ────────────────────────────────────────────────────────
 
@@ -333,7 +333,7 @@ export function writeToFile(filePath: string, summary: string): void {
 
   if (analysis.state === "unbalanced") {
     throw new Error(
-      `engram: cannot safely update ${filePath}: ${analysis.error} Re-run engram gen after fixing the markers.`
+      `engramx: cannot safely update ${filePath}: ${analysis.error} Re-run engram gen after fixing the markers.`
     );
   }
 
diff --git a/src/cli.ts b/src/cli.ts
index 2e9e964..cfafecb 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -48,6 +48,7 @@ import { getComponentStatus, formatHudStatus } from "./intercept/component-statu
 import {
   buildEngramSection,
   writeEngramSectionToMemoryMd,
+  writeEngramSectionToPath,
 } from "./intercept/memory-md.js";
 import { basename } from "node:path";
 
@@ -279,7 +280,7 @@ program
       const root = pathResolve(opts.project);
       if (!existsSync(join(root, ".engram", "graph.db"))) {
         console.error(
-          `engram: no graph found at ${root}. Run 'engram init' first.`
+          `engramx: no graph found at ${root}. Run 'engram init' first.`
         );
         process.exit(1);
       }
@@ -291,7 +292,7 @@ program
         process.exitCode = 0;
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        console.error(`engram: ${msg}`);
+        console.error(`engramx: ${msg}`);
         if (opts.verbose && err instanceof Error && err.stack) {
           console.error(err.stack);
         }
@@ -548,8 +549,9 @@ program
   .description("Teach engram a decision, pattern, or lesson")
   .argument("<text>", "What to remember (e.g., 'We chose JWT over sessions for horizontal scaling')")
   .option("-p, --project <path>", "Project directory", ".")
-  .action(async (text: string, opts: { project: string }) => {
-    const result = await learn(opts.project, text);
+  .option("--scope <scope>", "Memory scope: project|global|entity", "project")
+  .action(async (text: string, opts: { project: string; scope: string }) => {
+    const result = await learn(opts.project, text, "manual", opts.scope);
     if (result.nodesAdded > 0) {
       console.log(chalk.green(`🧠 Learned ${result.nodesAdded} new insight(s).`));
     } else {
@@ -1463,9 +1465,10 @@ program
     "Write engram's structural facts into MEMORY.md (complementary to Anthropic Auto-Dream)"
   )
   .option("-p, --project <path>", "Project directory", ".")
+  .option("--scope <scope>", "Memory scope: project|global|entity", "project")
   .option("--dry-run", "Print what would be written without writing", false)
   .action(
-    async (opts: { project: string; dryRun: boolean }) => {
+    async (opts: { project: string; scope: string; dryRun: boolean }) => {
       const absProject = pathResolve(opts.project);
       const projectRoot = findProjectRoot(absProject);
       if (!projectRoot) {
@@ -1476,87 +1479,189 @@ program
         process.exit(1);
       }
 
-      // Gather facts from core APIs
-      const [gods, mistakeList, graphStats] = await Promise.all([
-        godNodes(projectRoot, 10).catch(() => []),
-        mistakes(projectRoot, { limit: 5 }).catch(() => []),
-        stats(projectRoot).catch(() => null),
-      ]);
+      const scope = typeof opts.scope === "string" && opts.scope ? opts.scope : "project";
 
-      if (!graphStats) {
-        console.error(chalk.red("Failed to read graph stats."));
-        process.exit(1);
-      }
-
-      // Read git branch from .git/HEAD (reuses the logic pattern
-      // from the SessionStart handler)
-      let branch: string | null = null;
+      const { getStore } = await import("./core.js");
+      const store = await getStore(projectRoot);
       try {
-        const headPath = join(projectRoot, ".git", "HEAD");
-        if (existsSync(headPath)) {
-          const content = readFileSync(headPath, "utf-8").trim();
-          const m = content.match(/^ref:\s+refs\/heads\/(.+)$/);
-          if (m) branch = m[1];
+        const graphStats = store.getStats(scope === "project" ? projectRoot : undefined);
+
+        // Helper to read current branch for project-scoped writes
+        let branch: string | null = null;
+        if (scope === "project") {
+          try {
+            const headPath = join(projectRoot, ".git", "HEAD");
+            if (existsSync(headPath)) {
+              const content = readFileSync(headPath, "utf-8").trim();
+              const m = content.match(/^ref:\s+refs\/heads\/(.+)$/);
+              if (m) branch = m[1];
+            }
+          } catch {
+            /* ignore */
+          }
         }
-      } catch {
-        /* branch stays null */
-      }
 
-      const section = buildEngramSection({
-        projectName: basename(projectRoot),
-        branch,
-        stats: {
-          nodes: graphStats.nodes,
-          edges: graphStats.edges,
-          extractedPct: graphStats.extractedPct,
-        },
-        godNodes: gods,
-        landmines: mistakeList.map((m) => ({
-          label: m.label,
-          sourceFile: m.sourceFile,
-        })),
-        lastMined: graphStats.lastMined,
-      });
+        const slugify = (s: string) =>
+          s
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/(^-|-$)/g, "") || "entity";
+
+        if (scope === "project") {
+          const godsRows = store.getGodNodes(10, projectRoot);
+          const gods = godsRows
+            .filter((g) => {
+              const ms = (g.node.metadata as Record<string, unknown>).memoryScope as string | null | undefined;
+              return ms === "project" || ms === null || ms === undefined;
+            })
+            .slice(0, 10)
+            .map((g) => ({ label: g.node.label, kind: g.node.kind, sourceFile: g.node.sourceFile }));
+
+          let mistakeList = store.getAllNodes(projectRoot).filter((n) => n.kind === "mistake");
+          mistakeList = mistakeList.filter((m) => {
+            const ms = (m.metadata as Record<string, unknown>).memoryScope as string | null | undefined;
+            return ms === "project" || ms === null || ms === undefined;
+          });
+          mistakeList.sort((a, b) => b.lastVerified - a.lastVerified);
+          mistakeList = mistakeList.slice(0, 5);
+
+          const section = buildEngramSection({
+            projectName: basename(projectRoot),
+            branch,
+            stats: {
+              nodes: graphStats.nodes,
+              edges: graphStats.edges,
+              extractedPct: graphStats.extractedPct,
+            },
+            godNodes: gods,
+            landmines: mistakeList.map((m) => ({ label: m.label, sourceFile: m.sourceFile })),
+            lastMined: graphStats.lastMined,
+          });
+
+          console.log(chalk.bold(`\n📝 engram memory-sync`));
+          console.log(chalk.dim(`   Target: ${join(projectRoot, "MEMORY.md")}`));
+
+          if (opts.dryRun) {
+            console.log(chalk.cyan("\n   Section to write (dry-run):\n"));
+            console.log(section.split("\n").map((l) => "     " + l).join("\n"));
+            console.log(chalk.dim("\n   (dry-run — no changes written)"));
+            return;
+          }
+
+          const ok = writeEngramSectionToMemoryMd(projectRoot, section);
+          if (!ok) {
+            console.error(chalk.red("\n   ❌ Write failed. MEMORY.md may be too large, or the engram section exceeded its size cap."));
+            process.exit(1);
+          }
+
+          console.log(chalk.green(`\n   ✅ Synced ${gods.length} god nodes${mistakeList.length > 0 ? ` and ${mistakeList.length} landmines` : ""} to MEMORY.md`));
+          console.log(chalk.dim(`\n   Next: Anthropic's Auto-Dream will consolidate this alongside its prose entries.\n`));
+          return;
+        }
 
-      console.log(
-        chalk.bold(`\n📝 engram memory-sync`)
-      );
-      console.log(
-        chalk.dim(`   Target: ${join(projectRoot, "MEMORY.md")}`)
-      );
+        if (scope === "global") {
+          const godsRows = store.getGodNodes(200);
+          const gods = godsRows
+            .filter((g) => (g.node.metadata as Record<string, unknown>).memoryScope === "global")
+            .slice(0, 10)
+            .map((g) => ({ label: g.node.label, kind: g.node.kind, sourceFile: g.node.sourceFile }));
+
+          let mistakeList = store.getAllNodes().filter((n) => n.kind === "mistake");
+          mistakeList = mistakeList.filter((m) => (m.metadata as Record<string, unknown>).memoryScope === "global");
+          mistakeList.sort((a, b) => b.lastVerified - a.lastVerified);
+          mistakeList = mistakeList.slice(0, 5);
+
+          const section = buildEngramSection({
+            projectName: "Global engramx memory",
+            branch: null,
+            stats: {
+              nodes: graphStats.nodes,
+              edges: graphStats.edges,
+              extractedPct: graphStats.extractedPct,
+            },
+            godNodes: gods,
+            landmines: mistakeList.map((m) => ({ label: m.label, sourceFile: m.sourceFile })),
+            lastMined: graphStats.lastMined,
+          });
+
+          const globalPath = join(homedir(), ".engramx", "MEMORY.md");
+          mkdirSync(dirname(globalPath), { recursive: true });
+
+          console.log(chalk.bold(`\n📝 engram memory-sync (global)`));
+          console.log(chalk.dim(`   Target: ${globalPath}`));
+
+          if (opts.dryRun) {
+            console.log(chalk.cyan("\n   Section to write (dry-run):\n"));
+            console.log(section.split("\n").map((l) => "     " + l).join("\n"));
+            console.log(chalk.dim("\n   (dry-run — no changes written)"));
+            return;
+          }
+
+          const ok = writeEngramSectionToPath(globalPath, section);
+          if (!ok) {
+            console.error(chalk.red("\n   ❌ Write failed. Global MEMORY.md write failed or exceeded size cap."));
+            process.exit(1);
+          }
+
+          console.log(chalk.green(`\n   ✅ Synced ${gods.length} god nodes${mistakeList.length > 0 ? ` and ${mistakeList.length} landmines` : ""} to ${globalPath}`));
+          console.log(chalk.dim(`\n   Next: Anthropic's Auto-Dream will consolidate this alongside its prose entries.\n`));
+          return;
+        }
 
-      if (opts.dryRun) {
-        console.log(chalk.cyan("\n   Section to write (dry-run):\n"));
-        console.log(
-          section
-            .split("\n")
-            .map((l) => "     " + l)
-            .join("\n")
-        );
-        console.log(chalk.dim("\n   (dry-run — no changes written)"));
-        return;
-      }
+        if (scope === "entity") {
+          const godsRows = store.getGodNodes(500);
+          const entityGods = godsRows.filter((g) => (g.node.metadata as Record<string, unknown>).memoryScope === "entity");
+
+          if (entityGods.length === 0) {
+            console.log(chalk.dim("   No entity-scoped memories found."));
+            return;
+          }
+
+          const outDir = join(homedir(), ".engramx", "entities");
+          mkdirSync(outDir, { recursive: true });
+
+          let written = 0;
+          for (const g of entityGods.slice(0, 20)) {
+            const section = buildEngramSection({
+              projectName: g.node.label,
+              branch: null,
+              stats: {
+                nodes: graphStats.nodes,
+                edges: graphStats.edges,
+                extractedPct: graphStats.extractedPct,
+              },
+              godNodes: [{ label: g.node.label, kind: g.node.kind, sourceFile: g.node.sourceFile }],
+              landmines: [],
+              lastMined: graphStats.lastMined,
+            });
+
+            const filename = `${slugify(g.node.label)}.MEMORY.md`;
+            const outPath = join(outDir, filename);
+
+            console.log(chalk.dim(`   Target: ${outPath}`));
+
+            if (opts.dryRun) {
+              console.log(chalk.cyan("\n   Section to write (dry-run):\n"));
+              console.log(section.split("\n").map((l) => "     " + l).join("\n"));
+              continue;
+            }
+
+            const ok = writeEngramSectionToPath(outPath, section);
+            if (ok) written++;
+          }
+
+          if (!opts.dryRun) {
+            console.log(chalk.green(`\n   ✅ Synced ${written} entity memories to ${outDir}`));
+            console.log(chalk.dim(`\n   Next: Anthropic's Auto-Dream will consolidate these alongside prose entries.\n`));
+          }
+          return;
+        }
 
-      const ok = writeEngramSectionToMemoryMd(projectRoot, section);
-      if (!ok) {
-        console.error(
-          chalk.red(
-            "\n   ❌ Write failed. MEMORY.md may be too large, or the engram section exceeded its size cap."
-          )
-        );
+        console.error(chalk.red(`Unknown scope: ${scope}`));
         process.exit(1);
+      } finally {
+        store.close();
       }
-
-      console.log(
-        chalk.green(
-          `\n   ✅ Synced ${gods.length} god nodes${mistakeList.length > 0 ? ` and ${mistakeList.length} landmines` : ""} to MEMORY.md`
-        )
-      );
-      console.log(
-        chalk.dim(
-          `\n   Next: Anthropic's Auto-Dream will consolidate this alongside its prose entries.\n`
-        )
-      );
     }
   );
 
diff --git a/src/core.ts b/src/core.ts
index ec3448f..54bafd2 100644
--- a/src/core.ts
+++ b/src/core.ts
@@ -13,20 +13,68 @@ import { mineGitHistory } from "./miners/git-miner.js";
 import { mineSessionHistory, learnFromSession } from "./miners/session-miner.js";
 import { mineSkills } from "./miners/skills-miner.js";
 import type { GraphStats } from "./graph/schema.js";
+import { recordSession } from "./intelligence/token-tracker.js";
 
 const ENGRAM_DIR = ".engram";
 const DB_FILE = "graph.db";
 const LOCK_FILE = "init.lock";
 const DEFAULT_SKILLS_DIR = join(homedir(), ".claude", "skills");
 
-export function getDbPath(projectRoot: string): string {
-  return join(projectRoot, ENGRAM_DIR, DB_FILE);
+// Global DB config: single database for all projects
+const GLOBAL_DB_DIR = process.env.ENGRAM_GLOBAL_DB_DIR || join(homedir(), ".engramx");
+const GLOBAL_DB_FILE = process.env.ENGRAM_GLOBAL_DB_FILE || "memory.db";
+
+export function getGlobalDbPath(): string {
+  return process.env.ENGRAM_GLOBAL_DB_PATH || join(GLOBAL_DB_DIR, GLOBAL_DB_FILE);
+}
+
+export function getDbPath(_projectRoot: string): string {
+  // Backwards-compatible alias: always use the single global DB.
+  return getGlobalDbPath();
 }
 
 export async function getStore(projectRoot: string): Promise<GraphStore> {
+  // GraphStore is now a global DB; callers should pass projectRoot to
+  // project-aware methods when needed.
   return GraphStore.open(getDbPath(projectRoot));
 }
 
+/**
+ * Helper to encode a project-specific stat key stored in the global stats table.
+ * Use a stable base64-encoding of the projectRoot so keys are filesystem-safe.
+ */
+export function projectStatKey(projectRoot: string, key: string): string {
+  const id = Buffer.from(projectRoot).toString("base64");
+  return `project:${id}:${key}`;
+}
+
+/**
+ * Read the current git branch for a project. Lightweight (no shell) — reads
+ * .git/HEAD and returns branch name or 'detached' or null.
+ */
+export function readGitBranch(projectRoot: string): string | null {
+  try {
+    let current = resolve(projectRoot);
+    for (let depth = 0; depth < 10; depth++) {
+      const headPath = join(current, ".git", "HEAD");
+      if (existsSync(headPath)) {
+        const content = readFileSync(headPath, "utf-8").trim();
+        const refMatch = content.match(/^ref:\s+refs\/heads\/(.+)$/);
+        if (refMatch) return refMatch[1];
+        if (/^[0-9a-f]{7,40}$/i.test(content)) return "detached";
+        return null;
+      }
+      const parent = dirname(current);
+      if (parent === current) return null;
+      current = parent;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+
 export interface InitResult {
   nodes: number;
   edges: number;
@@ -72,7 +120,7 @@ export async function init(
   } catch (err: unknown) {
     if ((err as NodeJS.ErrnoException).code === "EEXIST") {
       throw new Error(
-        `engram: another init is running on ${root} (lock: ${lockPath}). ` +
+        `engramx: another init is running on ${root} (lock: ${lockPath}). ` +
           `If no other process is active, delete the lock file manually.`
       );
     }
@@ -85,7 +133,7 @@ export async function init(
     if (options.incremental) {
       const store = await getStore(root);
       try {
-        const mtimeJson = store.getStat("file_mtimes");
+        const mtimeJson = store.getStat(projectStatKey(root, "file_mtimes"));
         if (mtimeJson) {
           previousMtimes = new Map(JSON.parse(mtimeJson));
         }
@@ -138,18 +186,20 @@ export async function init(
         const clearedFiles = new Set<string>();
         for (const node of allNodes) {
           if (node.sourceFile && !clearedFiles.has(node.sourceFile)) {
-            store.removeNodesForFile(node.sourceFile);
+            store.removeNodesForFile(node.sourceFile, root);
             clearedFiles.add(node.sourceFile);
           }
         }
       } else {
         store.clearAll();
       }
-      store.bulkUpsert(allNodes, allEdges);
-      store.setStat("last_mined", String(Date.now()));
-      store.setStat("project_root", root);
-      // Persist mtimes for next incremental run
-      store.setStat("file_mtimes", JSON.stringify([...mtimes.entries()]));
+      const branch = readGitBranch(root);
+      // Bulk upsert with project scoping so the global DB can host multiple projects.
+      store.bulkUpsert(allNodes, allEdges, root, branch ?? undefined, "project");
+      store.setStat(projectStatKey(root, "last_mined"), String(Date.now()));
+      store.setStat(projectStatKey(root, "project_root"), root);
+      // Persist mtimes for next incremental run (project-scoped)
+      store.setStat(projectStatKey(root, "file_mtimes"), JSON.stringify([...mtimes.entries()]));
     } finally {
       store.close();
     }
@@ -178,9 +228,61 @@ export async function query(
   question: string,
   options: { mode?: "bfs" | "dfs"; depth?: number; tokenBudget?: number } = {}
 ): Promise<{ text: string; estimatedTokens: number; nodesFound: number }> {
+  const root = resolve(projectRoot);
   const store = await getStore(projectRoot);
   try {
-    const result = queryGraph(store, question, options);
+    const result = queryGraph(store, question, { ...options, projectRoot: root });
+
+    // Instrument: record session metrics using full-corpus baseline.
+    // Baseline heuristic: naiveTokens = ceil(totalCharsAcrossProject / 4)
+    try {
+      // Collect unique source files for this project and sum their lengths.
+      const allNodes = store.getAllNodes(root);
+      const seenFiles = new Set<string>();
+      for (const n of allNodes) {
+        if (n.sourceFile) seenFiles.add(n.sourceFile);
+      }
+
+      let totalChars = 0;
+      for (const f of seenFiles) {
+        try {
+          const fullPath = join(root, f);
+          if (existsSync(fullPath)) {
+            totalChars += readFileSync(fullPath, "utf-8").length;
+          }
+        } catch {
+          // ignore read errors
+        }
+      }
+
+      const naiveTokens = Math.max(1, Math.ceil(totalChars / 4));
+      const graphTokens = Math.max(1, Math.round(result.estimatedTokens || 0));
+
+      // Best-effort: record session stats into the store under project scope
+      try {
+        recordSession(store, naiveTokens, graphTokens, root);
+      } catch {
+        // non-fatal
+      }
+    } catch {
+      // non-fatal
+    }
+
+    // Aggressive auto: ingest the query result into memory in the background
+    try {
+      void import("./intercept/auto-memory.js").then((m) => {
+        try {
+          // Use a shortened question as a relPath hint for dedupe keys
+          const hint = `query:${question.slice(0, 200)}`;
+          return m.performAutoLearnForContent(projectRoot, result.text, hint, `auto:query`);
+        } catch {
+          return undefined as unknown as Promise<void>;
+        }
+      }).catch(() => undefined as unknown as Promise<void>);
+    } catch {
+      /* swallow */
+    }
+
     return { text: result.text, estimatedTokens: result.estimatedTokens, nodesFound: result.nodes.length };
   } finally {
     store.close();
@@ -194,7 +296,7 @@ export async function path(
 ): Promise<{ text: string; hops: number }> {
   const store = await getStore(projectRoot);
   try {
-    const result = shortestPath(store, source, target);
+    const result = shortestPath(store, source, target, undefined, projectRoot);
     return { text: result.text, hops: result.edges.length };
   } finally {
     store.close();
@@ -207,7 +309,7 @@ export async function godNodes(
 ): Promise<Array<{ label: string; kind: string; degree: number; sourceFile: string }>> {
   const store = await getStore(projectRoot);
   try {
-    return store.getGodNodes(topN).map((g) => ({
+    return store.getGodNodes(topN, projectRoot).map((g) => ({
       label: g.node.label, kind: g.node.kind, degree: g.degree, sourceFile: g.node.sourceFile,
     }));
   } finally {
@@ -218,7 +320,7 @@ export async function godNodes(
 export async function stats(projectRoot: string): Promise<GraphStats> {
   const store = await getStore(projectRoot);
   try {
-    return store.getStats();
+    return store.getStats(projectRoot);
   } finally {
     store.close();
   }
@@ -351,7 +453,7 @@ export async function getFileContext(
 
     const store = await getStore(root);
     try {
-      const summary = renderFileStructure(store, relPath);
+      const summary = renderFileStructure(store, relPath, undefined, root);
       if (summary.codeNodeCount === 0) {
         // No code declarations → not worth a summary even if there's a
         // file metadata node. Treat as passthrough.
@@ -430,7 +532,7 @@ export async function computeKeywordIDF(
 
     const store = await getStore(root);
     try {
-      const allNodes = store.getAllNodes();
+      const allNodes = store.getAllNodes(projectRoot);
       const total = allNodes.length;
       if (total === 0) return [];
 
@@ -467,20 +569,211 @@ export async function computeKeywordIDF(
   }
 }
 
+import { generateConclusionNodes } from "./miners/conclusions-miner.js";
+import { extractLinkCandidates } from "./miners/linking-helpers.js";
+
 export async function learn(
   projectRoot: string,
   text: string,
-  sourceLabel = "manual"
+  sourceLabel = "manual",
+  memoryScope: string = "project"
 ): Promise<{ nodesAdded: number }> {
-  const { nodes, edges } = learnFromSession(text, sourceLabel);
-  if (nodes.length === 0 && edges.length === 0) return { nodesAdded: 0 };
+  // Primary session mining (decisions/mistakes/patterns)
+  const sessionResult = learnFromSession(text, sourceLabel);
+  const conclusionResult = generateConclusionNodes(text, sourceLabel);
+
+  const combinedNodes = [...sessionResult.nodes, ...conclusionResult.nodes];
+  const combinedEdges = [...sessionResult.edges, ...conclusionResult.edges];
+
+  if (combinedNodes.length === 0 && combinedEdges.length === 0) return { nodesAdded: 0 };
+
   const store = await getStore(projectRoot);
   try {
-    store.bulkUpsert(nodes, edges);
+    // Bulk upsert nodes + edges (project-scoped)
+    store.bulkUpsert(combinedNodes, combinedEdges, projectRoot, undefined, memoryScope);
+
+    // Ensure the project is discoverable even when graph content was created
+    // by a manual `learn` call (no full init). Write a namespaced project_root
+    // stat entry so the dashboard's project list includes this project.
+    try {
+      store.setStat(projectStatKey(projectRoot, "project_root"), projectRoot);
+    } catch {
+      // best-effort — non-fatal if stats write fails
+    }
+
+    // Post-insert: create linking edges from conclusion nodes to existing
+    // graph nodes by simple keyword overlap. This helps surface relations
+    // between learned conclusions/fragments and code entities/files.
+    const now = Date.now();
+    const allNodes = store.getAllNodes(projectRoot);
+
+    const edgesToAdd = [] as typeof combinedEdges;
+    const seen = new Set<string>();
+
+    for (const c of conclusionResult.nodes) {
+      // only consider conclusion/pattern nodes we created (metadata marker)
+      if (!c.metadata || (c.metadata as Record<string, unknown>).miner !== "conclusion") continue;
+
+      // Gather candidates from both the node label and the full session text
+      const scanText = `${c.label}\n${text}`;
+      const { keywords, filePaths, commands } = extractLinkCandidates(scanText);
+
+      // Use IDF filtering to drop overly-common graph terms
+      let goodTokens: string[] = [];
+      try {
+        const idf = await computeKeywordIDF(projectRoot, keywords.slice(0, 80));
+        goodTokens = idf.filter((r) => r.idf > 0).slice(0, 12).map((r) => r.keyword.toLowerCase());
+      } catch {
+        goodTokens = keywords.slice(0, 12).map((k) => k.toLowerCase());
+      }
+
+      // 1) Keyword-based linking (similar_to)
+      for (const tok of goodTokens) {
+        for (const n of allNodes) {
+          if (n.id === c.id) continue;
+          if (n.label.toLowerCase().includes(tok)) {
+            const key = `${c.id}|${n.id}|similar_to`;
+            if (seen.has(key)) continue;
+            seen.add(key);
+            edgesToAdd.push({
+              source: c.id,
+              target: n.id,
+              relation: "similar_to",
+              confidence: "INFERRED",
+              confidenceScore: 0.6,
+              sourceFile: sourceLabel,
+              sourceLocation: null,
+              lastVerified: now,
+              metadata: { auto: true, matchedToken: tok },
+            });
+          } else if (n.metadata && JSON.stringify(n.metadata).toLowerCase().includes(tok)) {
+            const key = `${c.id}|${n.id}|similar_to`;
+            if (seen.has(key)) continue;
+            seen.add(key);
+            edgesToAdd.push({
+              source: c.id,
+              target: n.id,
+              relation: "similar_to",
+              confidence: "INFERRED",
+              confidenceScore: 0.55,
+              sourceFile: sourceLabel,
+              sourceLocation: null,
+              lastVerified: now,
+              metadata: { auto: true, matchedToken: tok, metaMatch: true },
+            });
+          }
+        }
+      }
+
+      // 2) File path linking (depends_on)
+      for (const fp of filePaths) {
+        try {
+          let candidate = fp.replace(/^\.\//, "");
+          candidate = candidate.replace(/^[A-Z]:\\/i, "");
+
+          const fileNodes = store.getNodesByFile(candidate, 500, projectRoot);
+          if (fileNodes.length > 0) {
+            for (const fn of fileNodes) {
+              const key = `${c.id}|${fn.id}|depends_on`;
+              if (seen.has(key)) continue;
+              seen.add(key);
+              edgesToAdd.push({
+                source: c.id,
+                target: fn.id,
+                relation: "depends_on",
+                confidence: "INFERRED",
+                confidenceScore: 0.85,
+                sourceFile: sourceLabel,
+                sourceLocation: null,
+                lastVerified: now,
+                metadata: { auto: true, detectedPath: fp },
+              });
+            }
+            continue;
+          }
+
+          // Fallback: match basename against node labels / sourceFile endings
+          const base = (candidate.split(/[\\/]/).pop() || candidate).toLowerCase();
+          for (const n of allNodes) {
+            if (!n.sourceFile && !n.label) continue;
+            const sf = (n.sourceFile || "").toLowerCase();
+            if (sf.endsWith(base) || (n.label || "").toLowerCase().includes(base)) {
+              const key = `${c.id}|${n.id}|depends_on`;
+              if (seen.has(key)) continue;
+              seen.add(key);
+              edgesToAdd.push({
+                source: c.id,
+                target: n.id,
+                relation: "depends_on",
+                confidence: "INFERRED",
+                confidenceScore: 0.75,
+                sourceFile: sourceLabel,
+                sourceLocation: null,
+                lastVerified: now,
+                metadata: { auto: true, detectedPath: fp, fallback: true },
+              });
+            }
+          }
+        } catch {
+          // non-fatal
+        }
+      }
+
+      // 3) Command mentions (mentions)
+      for (const cmd of commands) {
+        const lower = cmd.toLowerCase();
+        for (const n of allNodes) {
+          if (n.id === c.id) continue;
+          if ((n.label || "").toLowerCase().includes(lower) || JSON.stringify(n.metadata || {}).toLowerCase().includes(lower)) {
+            const key = `${c.id}|${n.id}|mentions`;
+            if (seen.has(key)) continue;
+            seen.add(key);
+            edgesToAdd.push({
+              source: c.id,
+              target: n.id,
+              relation: "mentions",
+              confidence: "INFERRED",
+              confidenceScore: 0.55,
+              sourceFile: sourceLabel,
+              sourceLocation: null,
+              lastVerified: now,
+              metadata: { auto: true, matchedCommand: cmd },
+            });
+          }
+        }
+      }
+    }
+
+    if (edgesToAdd.length > 0) {
+      // Upsert linking edges (no new nodes)
+      store.bulkUpsert([], edgesToAdd, projectRoot, undefined, memoryScope);
+    }
   } finally {
     store.close();
   }
-  return { nodesAdded: nodes.length };
+
+  // If this project has never been mined (no last_mined stat), trigger a
+  // best-effort incremental init in the background so file-level nodes
+  // (AST-extracted) become available for Read interception and the
+  // dashboard's Files tab. This is fire-and-forget and must not block
+  // the calling thread.
+  (async () => {
+    try {
+      const s = await getStore(projectRoot);
+      try {
+        const lm = s.getStat(projectStatKey(projectRoot, "last_mined"));
+        if (!lm || Number(lm) === 0) {
+          await init(projectRoot, { incremental: true });
+        }
+      } finally {
+        s.close();
+      }
+    } catch {
+      // swallow background init failures — learning succeeded regardless
+    }
+  })();
+
+  return { nodesAdded: combinedNodes.length };
 }
 
 export interface MistakeEntry {
@@ -511,7 +804,7 @@ export async function mistakes(
 ): Promise<MistakeEntry[]> {
   const store = await getStore(projectRoot);
   try {
-    let items = store.getAllNodes().filter((n) => n.kind === "mistake");
+    let items = store.getAllNodes(projectRoot).filter((n) => n.kind === "mistake");
 
     if (options.sourceFile !== undefined) {
       const target = options.sourceFile;
diff --git a/src/db/migrate.ts b/src/db/migrate.ts
index 5b87546..b33b101 100644
--- a/src/db/migrate.ts
+++ b/src/db/migrate.ts
@@ -15,7 +15,7 @@ export interface MigrationResult {
 }
 
 /** Current schema version — bump this when adding new migrations. */
-export const CURRENT_SCHEMA_VERSION = 8;
+export const CURRENT_SCHEMA_VERSION = 10;
 
 export interface RollbackResult {
   readonly fromVersion: number;
@@ -184,6 +184,114 @@ CREATE INDEX IF NOT EXISTS idx_query_cache_file ON query_cache(file_path);`,
         WHERE kind = 'mistake' AND valid_until IS NOT NULL;
     `);
   },
+
+  // v3.1.0: project scoping — add project_root/project_branch/memory_scope
+  // columns so a single global DB can host multiple projects' data and
+  // memory types (project/global/entity). Backfill is optional — new
+  // rows will populate these columns automatically.
+  9: (db: ExecDb) => {
+    addColumnIfMissing(db, "nodes", "project_root", "project_root TEXT NOT NULL DEFAULT ''");
+    addColumnIfMissing(db, "nodes", "project_branch", "project_branch TEXT");
+    addColumnIfMissing(db, "nodes", "memory_scope", "memory_scope TEXT");
+
+    addColumnIfMissing(db, "edges", "project_root", "project_root TEXT NOT NULL DEFAULT ''");
+
+    // Add project_root to provider_cache so caches can be scoped per project
+    addColumnIfMissing(db, "provider_cache", "project_root", "project_root TEXT NOT NULL DEFAULT ''");
+
+    // Index project_root on nodes/edges/provider_cache for efficient per-project queries
+    try { db.exec("CREATE INDEX IF NOT EXISTS idx_nodes_project_root ON nodes(project_root)"); } catch {}
+    try { db.exec("CREATE INDEX IF NOT EXISTS idx_edges_project_root ON edges(project_root)"); } catch {}
+    try { db.exec("CREATE INDEX IF NOT EXISTS idx_provider_cache_project_root ON provider_cache(project_root)"); } catch {}
+  },
+
+  // v3.2.0: canonical ids for deterministic dedupe + migration to merge existing duplicates
+  10: (db: ExecDb) => {
+    addColumnIfMissing(db, "nodes", "canonical_id", "canonical_id TEXT");
+    try { db.exec("CREATE INDEX IF NOT EXISTS idx_nodes_canonical_project ON nodes(canonical_id, project_root)"); } catch {}
+
+    // Compute canonical ids for existing nodes and backfill
+    try {
+      // Import computeCanonicalId dynamically so migrations are self-contained
+      const { computeCanonicalId } = require("../graph/canonical.js");
+      const res = db.exec("SELECT id, label, kind, memory_scope, project_root FROM nodes");
+      const rows = (res[0] && res[0].values) ? res[0].values : [];
+      for (const r of rows) {
+        const id = String(r[0] ?? "");
+        const label = String(r[1] ?? "");
+        const kind = String(r[2] ?? "");
+        const memoryScope = r[3] ?? "project";
+        const projectRoot = r[4] ?? "";
+        const canonical = computeCanonicalId(label, kind, memoryScope, projectRoot);
+        try {
+          // Use parameterized run when available
+          (db as unknown as RunDb).run("UPDATE nodes SET canonical_id = ? WHERE id = ?", [canonical, id]);
+        } catch {
+          try { db.exec(`UPDATE nodes SET canonical_id = '${String(canonical).replace(/'/g, "''")}' WHERE id = '${String(id).replace(/'/g, "''")}'`); } catch {}
+        }
+      }
+
+      // Find canonical groups with >1 member and merge duplicates
+      const groups = db.exec("SELECT canonical_id, project_root FROM nodes WHERE canonical_id IS NOT NULL AND canonical_id <> '' GROUP BY canonical_id, project_root HAVING COUNT(*) > 1");
+      const gvals = (groups[0] && groups[0].values) ? groups[0].values : [];
+      for (const gv of gvals) {
+        const canonical = String(gv[0]);
+        const proj = String(gv[1] ?? "");
+        const selSql = `SELECT id FROM nodes WHERE canonical_id = '${String(canonical).replace(/'/g, "''")}' AND project_root = '${String(proj).replace(/'/g, "''")}' ORDER BY confidence_score DESC, last_verified DESC`;
+        const sel = db.exec(selSql);
+        const nrows = (sel[0] && sel[0].values) ? sel[0].values.map((v) => String(v[0])) : [];
+        if (nrows.length <= 1) continue;
+        const primary = nrows[0];
+        const duplicates = nrows.slice(1);
+
+        for (const dup of duplicates) {
+          try {
+            // Re-insert source edges with primary as source (INSERT OR IGNORE)
+            const srcEdges = db.exec(`SELECT source, target, relation, confidence, confidence_score, source_file, source_location, last_verified, metadata, project_root FROM edges WHERE source = '${String(dup).replace(/'/g, "''")}'`);
+            const srcVals = (srcEdges[0] && srcEdges[0].values) ? srcEdges[0].values : [];
+            for (const e of srcVals) {
+              const [_s, target, relation, confidence, confidence_score, source_file, source_location, last_verified, metadata, edge_proj] = e;
+              try {
+                (db as unknown as RunDb).run(
+                  `INSERT OR IGNORE INTO edges (source, target, relation, confidence, confidence_score, source_file, source_location, last_verified, metadata, project_root) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+                  [primary, target, relation, confidence, confidence_score, source_file, source_location, last_verified, metadata, edge_proj]
+                );
+              } catch { /* best-effort */ }
+            }
+
+            // Re-insert target edges with primary as target
+            const tgtEdges = db.exec(`SELECT source, target, relation, confidence, confidence_score, source_file, source_location, last_verified, metadata, project_root FROM edges WHERE target = '${String(dup).replace(/'/g, "''")}'`);
+            const tgtVals = (tgtEdges[0] && tgtEdges[0].values) ? tgtEdges[0].values : [];
+            for (const e of tgtVals) {
+              const [source, _t, relation, confidence, confidence_score, source_file, source_location, last_verified, metadata, edge_proj] = e;
+              try {
+                (db as unknown as RunDb).run(
+                  `INSERT OR IGNORE INTO edges (source, target, relation, confidence, confidence_score, source_file, source_location, last_verified, metadata, project_root) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+                  [source, primary, relation, confidence, confidence_score, source_file, source_location, last_verified, metadata, edge_proj]
+                );
+              } catch { /* best-effort */ }
+            }
+
+            // Remove old edges referencing the duplicate
+            try {
+              (db as unknown as RunDb).run("DELETE FROM edges WHERE source = ? OR target = ?", [dup, dup]);
+            } catch { db.exec(`DELETE FROM edges WHERE source = '${String(dup).replace(/'/g, "''")}' OR target = '${String(dup).replace(/'/g, "''")}'`); }
+
+            // Finally remove the duplicate node
+            try {
+              (db as unknown as RunDb).run("DELETE FROM nodes WHERE id = ?", [dup]);
+            } catch { db.exec(`DELETE FROM nodes WHERE id = '${String(dup).replace(/'/g, "''")}'`); }
+          } catch {
+            // continue on error for best-effort merging
+          }
+        }
+      }
+    } catch (e) {
+      // Best-effort migration: if any of the merge steps fail, we don't
+      // want to abort the whole migration run. The canonical_id column
+      // still exists and the system will continue to operate.
+    }
+  },
 };
 
 type ExecDb = { exec: (sql: string) => Array<{ values: unknown[][] }> };
diff --git a/src/doctor/report.ts b/src/doctor/report.ts
index 41ec017..6fc2f35 100644
--- a/src/doctor/report.ts
+++ b/src/doctor/report.ts
@@ -115,7 +115,7 @@ function componentToCheck(c: ComponentHealth): DoctorCheck {
     lsp:
       "LSP is best-effort — install a language server (typescript-language-server, pyright, rust-analyzer).",
     ast:
-      "Tree-sitter grammars missing. Reinstall engram: `engram update` or `npm install -g engramx@latest`.",
+      "Tree-sitter grammars missing. Reinstall engramx: `engram update` or `npm install -g engramx@latest`.",
   };
   return {
     name: c.name,
diff --git a/src/graph/canonical.ts b/src/graph/canonical.ts
new file mode 100644
index 0000000..53a0a53
--- /dev/null
+++ b/src/graph/canonical.ts
@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto";
+
+// Deterministic canonical id generation for nodes.
+// Inputs: label, kind, memoryScope, projectRoot (optional). We normalize
+// the label (NFKC, collapse whitespace, remove punctuation) and hash a
+// versioned namespace so we can change algorithm later.
+
+function normalizeLabel(s: string): string {
+  if (!s) return "";
+  try {
+    // Unicode normalization to NFKC
+    let t = s.normalize("NFKC");
+    // Replace non-letter/number/space with nothing (remove punctuation)
+    t = t.replace(/[^\p{L}\p{N}\s]/gu, " ");
+    // Collapse whitespace and trim
+    t = t.replace(/\s+/g, " ").trim();
+    return t.toLowerCase();
+  } catch {
+    return s.replace(/\s+/g, " ").trim().toLowerCase();
+  }
+}
+
+export function computeCanonicalId(
+  label: string,
+  kind: string | undefined,
+  memoryScope: string | undefined,
+  projectRoot?: string | null
+): string {
+  const version = "v1"; // bump on algorithm changes
+  const norm = normalizeLabel(label || "");
+  const scope = memoryScope || "project";
+  const kindPart = kind || "";
+  const rootPart = projectRoot ? String(projectRoot) : "";
+  const base = `${version}|${scope}|${kindPart}|${norm}|${rootPart}`;
+  const hash = createHash("sha256").update(base).digest("hex").slice(0, 24);
+  return `c_${hash}`;
+}
diff --git a/src/graph/query.ts b/src/graph/query.ts
index b071a9a..317b0fb 100644
--- a/src/graph/query.ts
+++ b/src/graph/query.ts
@@ -50,7 +50,8 @@ interface TraversalResult {
 
 function scoreNodes(
   store: GraphStore,
-  terms: string[]
+  terms: string[],
+  projectRoot?: string
 ): Array<{ score: number; node: GraphNode }> {
   // Use SQL-level filtering via searchNodes instead of materializing
   // the entire graph into JS. Each term seeds from the index; we then
@@ -58,7 +59,7 @@ function scoreNodes(
   const seen = new Set<string>();
   const seedNodes: GraphNode[] = [];
   for (const t of terms) {
-    for (const node of store.searchNodes(t, 200)) {
+    for (const node of store.searchNodes(t, 200, projectRoot)) {
       if (!seen.has(node.id)) {
         seen.add(node.id);
         seedNodes.push(node);
@@ -108,15 +109,15 @@ function scoreNodes(
 export function queryGraph(
   store: GraphStore,
   question: string,
-  options: { mode?: "bfs" | "dfs"; depth?: number; tokenBudget?: number } = {}
+  options: { mode?: "bfs" | "dfs"; depth?: number; tokenBudget?: number; projectRoot?: string } = {}
 ): TraversalResult {
-  const { mode = "bfs", depth = 3, tokenBudget = 2000 } = options;
+  const { mode = "bfs", depth = 3, tokenBudget = 2000, projectRoot } = options;
   const terms = question
     .toLowerCase()
     .split(/\s+/)
     .filter((t) => t.length > 2);
 
-  const scored = scoreNodes(store, terms);
+  const scored = scoreNodes(store, terms, projectRoot);
   const startNodes = scored.slice(0, 3).map((s) => s.node);
 
   if (startNodes.length === 0) {
@@ -150,7 +151,7 @@ export function queryGraph(
     for (let d = 0; d < depth; d++) {
       const nextFrontier = new Set<string>();
       for (const nid of frontier) {
-        const neighbors = store.getNeighbors(nid);
+        const neighbors = store.getNeighbors(nid, undefined, projectRoot);
         for (const { node, edge } of neighbors) {
           if (shouldSkipEdgeFrom(nid, edge)) continue;
           if (!visited.has(node.id)) {
@@ -169,7 +170,7 @@ export function queryGraph(
     while (stack.length > 0) {
       const { id, d } = stack.pop()!;
       if (d > depth) continue;
-      const neighbors = store.getNeighbors(id);
+      const neighbors = store.getNeighbors(id, undefined, projectRoot);
       for (const { node, edge } of neighbors) {
         if (shouldSkipEdgeFrom(id, edge)) continue;
         if (!visited.has(node.id)) {
@@ -199,13 +200,14 @@ export function shortestPath(
   store: GraphStore,
   sourceTerm: string,
   targetTerm: string,
-  maxHops = 8
+  maxHops = 8,
+  projectRoot?: string
 ): TraversalResult {
   const sourceTerms = sourceTerm.toLowerCase().split(/\s+/).filter((t) => t.length > 2);
   const targetTerms = targetTerm.toLowerCase().split(/\s+/).filter((t) => t.length > 2);
 
-  const sourceScored = scoreNodes(store, sourceTerms);
-  const targetScored = scoreNodes(store, targetTerms);
+  const sourceScored = scoreNodes(store, sourceTerms, projectRoot);
+  const targetScored = scoreNodes(store, targetTerms, projectRoot);
 
   if (sourceScored.length === 0 || targetScored.length === 0) {
     return {
@@ -235,7 +237,7 @@ export function shortestPath(
         const node = store.getNode(path[i]);
         if (node) pathNodes.push(node);
         if (i < path.length - 1) {
-          const neighbors = store.getNeighbors(path[i]);
+          const neighbors = store.getNeighbors(path[i], undefined, projectRoot);
           const edge = neighbors.find((n) => n.node.id === path[i + 1])?.edge;
           if (edge) pathEdges.push(edge);
         }
@@ -251,7 +253,7 @@ export function shortestPath(
 
     if (path.length > maxHops) continue;
 
-    const neighbors = store.getNeighbors(current);
+    const neighbors = store.getNeighbors(current, undefined, projectRoot);
     for (const { node } of neighbors) {
       if (!seen.has(node.id)) {
         seen.add(node.id);
@@ -440,12 +442,13 @@ export interface FileStructureResult {
 export function renderFileStructure(
   store: GraphStore,
   relativeFilePath: string,
-  tokenBudget = 600
+  tokenBudget = 600,
+  projectRoot?: string
 ): FileStructureResult {
   // Use targeted SQL queries instead of full table scans. On 50k-node
   // projects, getAllNodes()/getAllEdges() materialize the entire graph
   // into JS arrays and time out silently.
-  const allFileNodes = store.getNodesByFile(relativeFilePath);
+  const allFileNodes = store.getNodesByFile(relativeFilePath, 500, projectRoot);
   const fileNodes = allFileNodes.filter((n) => !isHiddenKeyword(n));
 
   if (fileNodes.length === 0) {
@@ -471,7 +474,7 @@ export function renderFileStructure(
 
   // Fetch only edges that touch this file's nodes (indexed query).
   const fileNodeIds = new Set(fileNodes.map((n) => n.id));
-  const fileEdges = store.getEdgesForNodes([...fileNodeIds]);
+  const fileEdges = store.getEdgesForNodes([...fileNodeIds], projectRoot);
 
   // Degree map: how many edges touch each node in this file. Used to sort
   // nodes within each kind group so the most-connected (= most important)
@@ -520,7 +523,7 @@ export function renderFileStructure(
   ];
 
   const lines: string[] = [];
-  lines.push(`[engram] Structural summary for ${relativeFilePath}`);
+  lines.push(`[engramx] Structural summary for ${relativeFilePath}`);
   lines.push(
     `Nodes: ${fileNodes.length} | avg extraction confidence: ${avgConfidence.toFixed(2)}`
   );
diff --git a/src/graph/store.ts b/src/graph/store.ts
index 0efad5d..6a78ea8 100644
--- a/src/graph/store.ts
+++ b/src/graph/store.ts
@@ -99,15 +99,87 @@ export class GraphStore {
     runMigrations(this.db, this.dbPath);
   }
 
+  // Non-blocking save: export the DB synchronously (cheap) then
+  // write the bytes to disk asynchronously so file I/O doesn't block
+  // the main event loop. Coalesce rapid successive saves into a single
+  // final write to avoid thrashing the filesystem.
+  private _savePending = false as boolean;
+  private _saveQueuedBuffer: Buffer | null = null;
+
   save(): void {
-    const data = this.db.export();
-    writeFileSync(this.dbPath, Buffer.from(data));
+    let data: Uint8Array;
+    try {
+      data = this.db.export();
+    } catch (e) {
+      // If export fails for any reason, fall back to a best-effort
+      // synchronous write attempt (rare). Swallow errors to avoid
+      // crashing callers.
+      try {
+        writeFileSync(this.dbPath, Buffer.from([]));
+      } catch {
+        /* swallow */
+      }
+      return;
+    }
+
+    const buffer = Buffer.from(data);
+    const tmpPath = this.dbPath + ".tmp";
+
+    // If a save is already in progress, stash the latest buffer and
+    // return. The in-progress write will detect _saveQueuedBuffer and
+    // write it afterwards. This coalesces rapid updates.
+    if (this._savePending) {
+      this._saveQueuedBuffer = buffer;
+      return;
+    }
+
+    this._savePending = true;
+    const writeOnce = async (): Promise<void> => {
+      try {
+        // Async write temp -> rename for atomicity
+        await import("node:fs/promises").then((fs) => fs.writeFile(tmpPath, buffer));
+        await import("node:fs/promises").then((fs) => fs.rename(tmpPath, this.dbPath));
+
+        // If another save was queued while we were writing, write it now
+        if (this._saveQueuedBuffer) {
+          const nextBuf = this._saveQueuedBuffer;
+          this._saveQueuedBuffer = null;
+          try {
+            await import("node:fs/promises").then((fs) => fs.writeFile(tmpPath, nextBuf!));
+            await import("node:fs/promises").then((fs) => fs.rename(tmpPath, this.dbPath));
+          } catch (e) {
+            // Best-effort fallback to synchronous write
+            try {
+              writeFileSync(this.dbPath, nextBuf!);
+            } catch {
+              /* swallow */
+            }
+          }
+        }
+      } catch (e) {
+        // Best-effort fallback: synchronous write
+        try {
+          writeFileSync(this.dbPath, buffer);
+        } catch {
+          /* swallow */
+        }
+      } finally {
+        this._savePending = false;
+      }
+    };
+
+    // Fire-and-forget
+    void writeOnce();
   }
 
-  upsertNode(node: GraphNode): void {
+  upsertNode(node: GraphNode, defaults?: { projectRoot?: string; projectBranch?: string; memoryScope?: string }): void {
+    const projectRoot = (node as any).projectRoot ?? defaults?.projectRoot ?? "";
+    const projectBranch = (node as any).projectBranch ?? defaults?.projectBranch ?? null;
+    const memoryScope = (node as any).memoryScope ?? defaults?.memoryScope ?? null;
+
     this.db.run(
-      `INSERT OR REPLACE INTO nodes (id, label, kind, source_file, source_location, confidence, confidence_score, last_verified, query_count, metadata, valid_until, invalidated_by_commit)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      `INSERT OR REPLACE INTO nodes (id, label, kind, source_file, source_location, confidence, confidence_score, last_verified, query_count, metadata, valid_until, invalidated_by_commit, project_root, project_branch, memory_scope)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       [
         node.id,
         node.label,
@@ -121,14 +193,134 @@ export class GraphStore {
         JSON.stringify(node.metadata),
         node.validUntil ?? null,
         node.invalidatedByCommit ?? null,
+        projectRoot,
+        projectBranch,
+        memoryScope,
       ]
     );
   }
 
-  upsertEdge(edge: GraphEdge): void {
+  /**
+   * Merge-aware single node upsert. If a node supplies a canonical_id (or
+   * if a canonical id can be derived from the node.id prefix `c_`), the
+   * method will try to find an existing node with that canonical_id (scoped
+   * to project_root) and merge metadata/fields rather than blindly
+   * replacing the row.
+   *
+   * Returns the final node id written to the DB (existing or newly-created).
+   */
+  mergeUpsertNode(node: GraphNode, defaults?: { projectRoot?: string; projectBranch?: string; memoryScope?: string }): string {
+    const projectRoot = defaults?.projectRoot ?? "";
+    const projectBranch = defaults?.projectBranch ?? null;
+    const memoryScope = defaults?.memoryScope ?? null;
+
+    const canonical = (node as any).canonicalId ?? node.id?.startsWith("c_") ? (node as any).canonicalId ?? node.id : null;
+
+    if (!canonical) {
+      // No canonical id — fall back to simple upsert using provided id.
+      this.upsertNode(node, { projectRoot, projectBranch, memoryScope });
+      return node.id;
+    }
+
+    // Try to find existing node by canonical_id (project-scoped)
+    const sql = projectRoot
+      ? "SELECT * FROM nodes WHERE canonical_id = ? AND project_root = ? LIMIT 1"
+      : "SELECT * FROM nodes WHERE canonical_id = ? LIMIT 1";
+    const stmt = this.db.prepare(sql);
+    if (projectRoot) stmt.bind([canonical, projectRoot]);
+    else stmt.bind([canonical]);
+
+    if (stmt.step()) {
+      const row = stmt.getAsObject();
+      stmt.free();
+      const existing = this.rowToNode(row);
+
+      // Merge metadata (shallow merge; arrays concatenated dedup)
+      const existingMeta = existing.metadata ?? {};
+      const incomingMeta = node.metadata ?? {};
+      const mergedMeta: Record<string, unknown> = { ...existingMeta };
+      for (const k of Object.keys(incomingMeta)) {
+        const v = (incomingMeta as Record<string, unknown>)[k];
+        const ev = (existingMeta as Record<string, unknown>)[k];
+        if (Array.isArray(ev) && Array.isArray(v)) {
+          mergedMeta[k] = Array.from(new Set([...ev, ...v]));
+        } else if (ev === undefined || ev === null) {
+          mergedMeta[k] = v;
+        } else {
+          // prefer existing value for opaque fields
+          mergedMeta[k] = ev;
+        }
+      }
+
+      const mergedLabel = (existing.label && existing.label.length >= (node.label || "").length) ? existing.label : (node.label || existing.label);
+      const mergedKind = existing.kind || node.kind;
+      const mergedSourceFile = existing.sourceFile || node.sourceFile || "";
+      const mergedSourceLocation = existing.sourceLocation || node.sourceLocation || null;
+      const mergedConfidence = existing.confidence || node.confidence;
+      const mergedConfidenceScore = Math.max(existing.confidenceScore || 0, node.confidenceScore || 0);
+      const mergedLastVerified = Math.max(existing.lastVerified || 0, node.lastVerified || 0);
+      const mergedQueryCount = Math.max(existing.queryCount || 0, node.queryCount || 0);
+
+      const updateSql = `UPDATE nodes SET label = ?, kind = ?, source_file = ?, source_location = ?, confidence = ?, confidence_score = ?, last_verified = ?, query_count = ?, metadata = ?, valid_until = ?, invalidated_by_commit = ?, project_root = ?, project_branch = ?, memory_scope = ?, canonical_id = ? WHERE id = ?`;
+
+      let metadataStr = "{}";
+      try { metadataStr = JSON.stringify(mergedMeta); } catch { metadataStr = "{}"; }
+
+      this.db.run(updateSql, [
+        mergedLabel,
+        mergedKind,
+        mergedSourceFile,
+        mergedSourceLocation,
+        mergedConfidence,
+        mergedConfidenceScore,
+        mergedLastVerified,
+        mergedQueryCount,
+        metadataStr,
+        node.validUntil ?? null,
+        node.invalidatedByCommit ?? null,
+        projectRoot,
+        projectBranch,
+        memoryScope,
+        canonical,
+        existing.id,
+      ]);
+
+      return existing.id;
+    }
+
+    // No existing — insert a new node using the canonical id as the primary id
+    const idToUse = canonical;
+    this.db.run(
+      `INSERT OR REPLACE INTO nodes (id, label, kind, source_file, source_location, confidence, confidence_score, last_verified, query_count, metadata, valid_until, invalidated_by_commit, project_root, project_branch, memory_scope, canonical_id)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        idToUse,
+        node.label,
+        node.kind,
+        node.sourceFile,
+        node.sourceLocation,
+        node.confidence,
+        node.confidenceScore,
+        node.lastVerified,
+        node.queryCount,
+        JSON.stringify(node.metadata),
+        node.validUntil ?? null,
+        node.invalidatedByCommit ?? null,
+        projectRoot,
+        projectBranch,
+        memoryScope,
+        canonical,
+      ]
+    );
+
+    return idToUse;
+  }
+
+  upsertEdge(edge: GraphEdge, defaults?: { projectRoot?: string }): void {
+    const projectRoot = (edge as any).projectRoot ?? defaults?.projectRoot ?? "";
     this.db.run(
-      `INSERT OR REPLACE INTO edges (source, target, relation, confidence, confidence_score, source_file, source_location, last_verified, metadata)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      `INSERT OR REPLACE INTO edges (source, target, relation, confidence, confidence_score, source_file, source_location, last_verified, metadata, project_root)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       [
         edge.source,
         edge.target,
@@ -139,20 +331,27 @@ export class GraphStore {
         edge.sourceLocation,
         edge.lastVerified,
         JSON.stringify(edge.metadata),
+        projectRoot,
       ]
     );
   }
 
   /**
    * Remove all nodes and edges associated with a specific source file.
+   * If projectRoot is provided, only clears nodes/edges for that project.
    * Used by the file watcher for incremental re-indexing — old nodes for
    * a changed file are cleared before re-extracting.
    */
-  deleteBySourceFile(sourceFile: string): void {
+  deleteBySourceFile(sourceFile: string, projectRoot?: string): void {
     this.db.run("BEGIN TRANSACTION");
     try {
-      this.db.run("DELETE FROM edges WHERE source_file = ?", [sourceFile]);
-      this.db.run("DELETE FROM nodes WHERE source_file = ?", [sourceFile]);
+      if (projectRoot) {
+        this.db.run("DELETE FROM edges WHERE source_file = ? AND project_root = ?", [sourceFile, projectRoot]);
+        this.db.run("DELETE FROM nodes WHERE source_file = ? AND project_root = ?", [sourceFile, projectRoot]);
+      } else {
+        this.db.run("DELETE FROM edges WHERE source_file = ?", [sourceFile]);
+        this.db.run("DELETE FROM nodes WHERE source_file = ?", [sourceFile]);
+      }
       this.db.run("COMMIT");
     } catch (e) {
       this.db.run("ROLLBACK");
@@ -160,11 +359,13 @@ export class GraphStore {
     }
   }
 
-  countBySourceFile(sourceFile: string): number {
-    const stmt = this.db.prepare(
-      "SELECT COUNT(*) AS n FROM nodes WHERE source_file = ?"
-    );
-    stmt.bind([sourceFile]);
+  countBySourceFile(sourceFile: string, projectRoot?: string): number {
+    const sql = projectRoot
+      ? "SELECT COUNT(*) AS n FROM nodes WHERE source_file = ? AND project_root = ?"
+      : "SELECT COUNT(*) AS n FROM nodes WHERE source_file = ?";
+    const stmt = this.db.prepare(sql);
+    if (projectRoot) stmt.bind([sourceFile, projectRoot]);
+    else stmt.bind([sourceFile]);
     let count = 0;
     if (stmt.step()) {
       const row = stmt.getAsObject() as { n: number };
@@ -174,10 +375,35 @@ export class GraphStore {
     return count;
   }
 
-  bulkUpsert(nodes: GraphNode[], edges: GraphEdge[]): void {
+  /**
+   * Merge-aware bulk upsert. Nodes that provide a canonical_id will be
+   * merged into any existing node with the same canonical_id (project-scoped).
+   * Returns after inserting/updating nodes and edges; edges referencing
+   * replaced node ids are remapped to the merged node id.
+   */
+  bulkUpsert(nodes: GraphNode[], edges: GraphEdge[], projectRoot?: string, projectBranch?: string, memoryScope?: string): void {
     this.db.run("BEGIN TRANSACTION");
-    for (const node of nodes) this.upsertNode(node);
-    for (const edge of edges) this.upsertEdge(edge);
+    const idMap = new Map<string, string>();
+
+    for (const node of nodes) {
+      try {
+        const finalId = this.mergeUpsertNode(node, { projectRoot, projectBranch, memoryScope });
+        if (finalId && finalId !== node.id) idMap.set(node.id, finalId);
+      } catch (e) {
+        // Best-effort: swallow per-node errors to avoid failing the whole bulk
+      }
+    }
+
+    for (const edge of edges) {
+      // Remap source/target ids if nodes were canonicalized/merged
+      const s = idMap.get(edge.source) ?? edge.source;
+      const t = idMap.get(edge.target) ?? edge.target;
+      const edgeCopy = { ...edge, source: s, target: t };
+      try {
+        this.upsertEdge(edgeCopy, { projectRoot });
+      } catch {}
+    }
+
     this.db.run("COMMIT");
     this.save();
   }
@@ -194,14 +420,16 @@ export class GraphStore {
     return null;
   }
 
-  searchNodes(query: string, limit = 20): GraphNode[] {
+  searchNodes(query: string, limit = 20, projectRoot?: string): GraphNode[] {
     const escaped = query.replace(/%/g, "\\%").replace(/_/g, "\\_");
     const pattern = `%${escaped}%`;
     const results: GraphNode[] = [];
-    const stmt = this.db.prepare(
-      "SELECT * FROM nodes WHERE label LIKE ? ESCAPE '\\' OR id LIKE ? ESCAPE '\\' ORDER BY query_count DESC LIMIT ?"
-    );
-    stmt.bind([pattern, pattern, limit]);
+    const sql = projectRoot
+      ? "SELECT * FROM nodes WHERE (label LIKE ? ESCAPE '\\' OR id LIKE ? ESCAPE '\\') AND project_root = ? ORDER BY query_count DESC LIMIT ?"
+      : "SELECT * FROM nodes WHERE label LIKE ? ESCAPE '\\' OR id LIKE ? ESCAPE '\\' ORDER BY query_count DESC LIMIT ?";
+    const stmt = this.db.prepare(sql);
+    if (projectRoot) stmt.bind([pattern, pattern, projectRoot, limit]);
+    else stmt.bind([pattern, pattern, limit]);
     while (stmt.step()) {
       results.push(this.rowToNode(stmt.getAsObject()));
     }
@@ -211,14 +439,23 @@ export class GraphStore {
 
   getNeighbors(
     nodeId: string,
-    relationFilter?: EdgeRelation
+    relationFilter?: EdgeRelation,
+    projectRoot?: string
   ): Array<{ node: GraphNode; edge: GraphEdge }> {
     const sql = relationFilter
-      ? "SELECT * FROM edges WHERE (source = ? OR target = ?) AND relation = ?"
-      : "SELECT * FROM edges WHERE source = ? OR target = ?";
+      ? projectRoot
+        ? "SELECT * FROM edges WHERE (source = ? OR target = ?) AND relation = ? AND project_root = ?"
+        : "SELECT * FROM edges WHERE (source = ? OR target = ?) AND relation = ?"
+      : projectRoot
+        ? "SELECT * FROM edges WHERE (source = ? OR target = ?) AND project_root = ?"
+        : "SELECT * FROM edges WHERE source = ? OR target = ?";
     const params = relationFilter
-      ? [nodeId, nodeId, relationFilter]
-      : [nodeId, nodeId];
+      ? projectRoot
+        ? [nodeId, nodeId, relationFilter, projectRoot]
+        : [nodeId, nodeId, relationFilter]
+      : projectRoot
+        ? [nodeId, nodeId, projectRoot]
+        : [nodeId, nodeId];
 
     const stmt = this.db.prepare(sql);
     stmt.bind(params);
@@ -233,23 +470,31 @@ export class GraphStore {
     return results;
   }
 
-  getGodNodes(topN = 10): Array<{ node: GraphNode; degree: number }> {
+  getGodNodes(topN = 10, projectRoot?: string): Array<{ node: GraphNode; degree: number }> {
     const results: Array<{ node: GraphNode; degree: number }> = [];
     // Exclude structural plumbing (file/import/module) AND concept nodes.
     // The `concept` kind is used by the skills-miner for both skills and
     // keyword nodes — a keyword like "landing page" may have hundreds of
     // triggered_by edges but isn't a "core abstraction" of the codebase.
     // Users want real code entities + decisions/patterns/mistakes here.
-    const stmt = this.db.prepare(
-      `SELECT n.*, COUNT(*) as degree
-       FROM nodes n
-       JOIN edges e ON e.source = n.id OR e.target = n.id
-       WHERE n.kind NOT IN ('file', 'import', 'module', 'concept')
-       GROUP BY n.id
-       ORDER BY degree DESC
-       LIMIT ?`
-    );
-    stmt.bind([topN]);
+    const sql = projectRoot
+      ? `SELECT n.*, COUNT(*) as degree
+         FROM nodes n
+         JOIN edges e ON e.source = n.id OR e.target = n.id
+         WHERE n.kind NOT IN ('file', 'import', 'module', 'concept') AND n.project_root = ?
+         GROUP BY n.id
+         ORDER BY degree DESC
+         LIMIT ?`
+      : `SELECT n.*, COUNT(*) as degree
+         FROM nodes n
+         JOIN edges e ON e.source = n.id OR e.target = n.id
+         WHERE n.kind NOT IN ('file', 'import', 'module', 'concept')
+         GROUP BY n.id
+         ORDER BY degree DESC
+         LIMIT ?`;
+    const stmt = this.db.prepare(sql);
+    if (projectRoot) stmt.bind([projectRoot, topN]);
+    else stmt.bind([topN]);
     while (stmt.step()) {
       const row = stmt.getAsObject();
       results.push({
@@ -261,12 +506,14 @@ export class GraphStore {
     return results;
   }
 
-  getNodesByFile(sourceFile: string, limit = 500): GraphNode[] {
+  getNodesByFile(sourceFile: string, limit = 500, projectRoot?: string): GraphNode[] {
     const results: GraphNode[] = [];
-    const stmt = this.db.prepare(
-      "SELECT * FROM nodes WHERE source_file = ? LIMIT ?"
-    );
-    stmt.bind([sourceFile, limit]);
+    const sql = projectRoot
+      ? "SELECT * FROM nodes WHERE source_file = ? AND project_root = ? LIMIT ?"
+      : "SELECT * FROM nodes WHERE source_file = ? LIMIT ?";
+    const stmt = this.db.prepare(sql);
+    if (projectRoot) stmt.bind([sourceFile, projectRoot, limit]);
+    else stmt.bind([sourceFile, limit]);
     while (stmt.step()) {
       results.push(this.rowToNode(stmt.getAsObject()));
     }
@@ -274,7 +521,7 @@ export class GraphStore {
     return results;
   }
 
-  getEdgesForNodes(nodeIds: string[]): GraphEdge[] {
+  getEdgesForNodes(nodeIds: string[], projectRoot?: string): GraphEdge[] {
     if (nodeIds.length === 0) return [];
     // Chunk to stay under SQLite's SQLITE_LIMIT_VARIABLE_NUMBER (999).
     // Each chunk binds chunk.length * 2 params (source IN + target IN).
@@ -284,9 +531,11 @@ export class GraphStore {
     for (let i = 0; i < nodeIds.length; i += CHUNK) {
       const chunk = nodeIds.slice(i, i + CHUNK);
       const placeholders = chunk.map(() => "?").join(",");
-      const sql = `SELECT * FROM edges WHERE source IN (${placeholders}) OR target IN (${placeholders})`;
+      let sql = `SELECT * FROM edges WHERE source IN (${placeholders}) OR target IN (${placeholders})`;
+      if (projectRoot) sql = `SELECT * FROM edges WHERE (source IN (${placeholders}) OR target IN (${placeholders})) AND project_root = ?`;
       const stmt = this.db.prepare(sql);
-      stmt.bind([...chunk, ...chunk]);
+      if (projectRoot) stmt.bind([...chunk, ...chunk, projectRoot]);
+      else stmt.bind([...chunk, ...chunk]);
       while (stmt.step()) {
         const edge = this.rowToEdge(stmt.getAsObject());
         const key = `${edge.source}|${edge.target}|${edge.relation}`;
@@ -300,9 +549,11 @@ export class GraphStore {
     return results;
   }
 
-  getAllNodes(): GraphNode[] {
+  getAllNodes(projectRoot?: string): GraphNode[] {
     const results: GraphNode[] = [];
-    const stmt = this.db.prepare("SELECT * FROM nodes");
+    const sql = projectRoot ? "SELECT * FROM nodes WHERE project_root = ?" : "SELECT * FROM nodes";
+    const stmt = this.db.prepare(sql);
+    if (projectRoot) stmt.bind([projectRoot]);
     while (stmt.step()) {
       results.push(this.rowToNode(stmt.getAsObject()));
     }
@@ -327,13 +578,22 @@ export class GraphStore {
     );
   }
 
-  getStats(): GraphStats {
-    const nodeCount = (this.db.exec("SELECT COUNT(*) FROM nodes")[0]?.values[0]?.[0] as number) ?? 0;
-    const edgeCount = (this.db.exec("SELECT COUNT(*) FROM edges")[0]?.values[0]?.[0] as number) ?? 0;
+  getStats(projectRoot?: string): GraphStats {
+    // Helper to encode project stat keys
+    const encodeProjectKey = (p: string, k: string) => `project:${Buffer.from(p).toString("base64")}:${k}`;
+
+    const nodeCount = projectRoot
+      ? (this.db.exec("SELECT COUNT(*) FROM nodes WHERE project_root = ?", [projectRoot])[0]?.values[0]?.[0] as number) ?? 0
+      : (this.db.exec("SELECT COUNT(*) FROM nodes")[0]?.values[0]?.[0] as number) ?? 0;
+    const edgeCount = projectRoot
+      ? (this.db.exec("SELECT COUNT(*) FROM edges WHERE project_root = ?", [projectRoot])[0]?.values[0]?.[0] as number) ?? 0
+      : (this.db.exec("SELECT COUNT(*) FROM edges")[0]?.values[0]?.[0] as number) ?? 0;
+
+    const confSql = projectRoot
+      ? "SELECT confidence, COUNT(*) as c FROM edges WHERE project_root = ? GROUP BY confidence"
+      : "SELECT confidence, COUNT(*) as c FROM edges GROUP BY confidence";
+    const confRows = projectRoot ? this.db.exec(confSql, [projectRoot]) : this.db.exec(confSql);
 
-    const confRows = this.db.exec(
-      "SELECT confidence, COUNT(*) as c FROM edges GROUP BY confidence"
-    );
     const total = edgeCount || 1;
     const confMap: Record<string, number> = {};
     if (confRows[0]) {
@@ -342,12 +602,12 @@ export class GraphStore {
       }
     }
 
-    const savedRow = this.db.exec(
-      "SELECT value FROM stats WHERE key = 'tokens_saved'"
-    );
-    const lastMinedRow = this.db.exec(
-      "SELECT value FROM stats WHERE key = 'last_mined'"
-    );
+    // Stats table: for project-scoped values we use namespaced keys
+    const savedKey = projectRoot ? encodeProjectKey(projectRoot, "tokens_saved") : "tokens_saved";
+    const lastMinedKey = projectRoot ? encodeProjectKey(projectRoot, "last_mined") : "last_mined";
+
+    const savedRow = this.db.exec("SELECT value FROM stats WHERE key = ?", [savedKey]);
+    const lastMinedRow = this.db.exec("SELECT value FROM stats WHERE key = ?", [lastMinedKey]);
 
     return {
       nodes: nodeCount,
@@ -409,14 +669,17 @@ export class GraphStore {
    * Get all cached provider results for a file. Returns only non-stale
    * entries (cached_at + ttl > now).
    */
-  getCachedContext(filePath: string): CachedContext[] {
+  getCachedContext(filePath: string, projectRoot?: string): CachedContext[] {
     const now = Date.now();
     const results: CachedContext[] = [];
-    const stmt = this.db.prepare(
-      `SELECT * FROM provider_cache
-       WHERE file_path = ? AND (cached_at + ttl * 1000) > ?`
-    );
-    stmt.bind([filePath, now]);
+    const sql = projectRoot
+      ? `SELECT * FROM provider_cache
+       WHERE file_path = ? AND project_root = ? AND (cached_at + ttl * 1000) > ?`
+      : `SELECT * FROM provider_cache
+       WHERE file_path = ? AND (cached_at + ttl * 1000) > ?`;
+    const stmt = this.db.prepare(sql);
+    if (projectRoot) stmt.bind([filePath, projectRoot, now]);
+    else stmt.bind([filePath, now]);
     while (stmt.step()) {
       results.push(this.rowToCachedContext(stmt.getAsObject()));
     }
@@ -430,14 +693,18 @@ export class GraphStore {
    */
   getCachedContextForProvider(
     provider: string,
-    filePath: string
+    filePath: string,
+    projectRoot?: string
   ): CachedContext | null {
     const now = Date.now();
-    const stmt = this.db.prepare(
-      `SELECT * FROM provider_cache
-       WHERE provider = ? AND file_path = ? AND (cached_at + ttl * 1000) > ?`
-    );
-    stmt.bind([provider, filePath, now]);
+    const sql = projectRoot
+      ? `SELECT * FROM provider_cache
+       WHERE provider = ? AND file_path = ? AND project_root = ? AND (cached_at + ttl * 1000) > ?`
+      : `SELECT * FROM provider_cache
+       WHERE provider = ? AND file_path = ? AND (cached_at + ttl * 1000) > ?`;
+    const stmt = this.db.prepare(sql);
+    if (projectRoot) stmt.bind([provider, filePath, projectRoot, now]);
+    else stmt.bind([provider, filePath, now]);
     if (stmt.step()) {
       const row = stmt.getAsObject();
       stmt.free();
@@ -455,14 +722,24 @@ export class GraphStore {
     filePath: string,
     content: string,
     ttl: number,
-    queryUsed = ""
+    queryUsed = "",
+    projectRoot?: string
   ): void {
-    this.db.run(
-      `INSERT OR REPLACE INTO provider_cache
-       (provider, file_path, content, query_used, cached_at, ttl)
-       VALUES (?, ?, ?, ?, ?, ?)`,
-      [provider, filePath, content, queryUsed, Date.now(), ttl]
-    );
+    if (projectRoot) {
+      this.db.run(
+        `INSERT OR REPLACE INTO provider_cache
+         (provider, file_path, content, query_used, cached_at, ttl, project_root)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+        [provider, filePath, content, queryUsed, Date.now(), ttl, projectRoot]
+      );
+    } else {
+      this.db.run(
+        `INSERT OR REPLACE INTO provider_cache
+         (provider, file_path, content, query_used, cached_at, ttl, project_root)
+         VALUES (?, ?, ?, ?, ?, ?, '')`,
+        [provider, filePath, content, queryUsed, Date.now(), ttl]
+      );
+    }
   }
 
   /**
@@ -473,18 +750,28 @@ export class GraphStore {
     provider: string,
     entries: ReadonlyArray<{ filePath: string; content: string }>,
     ttl: number,
-    queryUsed = ""
+    queryUsed = "",
+    projectRoot?: string
   ): void {
     if (entries.length === 0) return;
     this.db.run("BEGIN TRANSACTION");
     try {
       for (const entry of entries) {
-        this.db.run(
-          `INSERT OR REPLACE INTO provider_cache
-           (provider, file_path, content, query_used, cached_at, ttl)
-           VALUES (?, ?, ?, ?, ?, ?)`,
-          [provider, entry.filePath, entry.content, queryUsed, Date.now(), ttl]
-        );
+        if (projectRoot) {
+          this.db.run(
+            `INSERT OR REPLACE INTO provider_cache
+             (provider, file_path, content, query_used, cached_at, ttl, project_root)
+             VALUES (?, ?, ?, ?, ?, ?, ?)`,
+            [provider, entry.filePath, entry.content, queryUsed, Date.now(), ttl, projectRoot]
+          );
+        } else {
+          this.db.run(
+            `INSERT OR REPLACE INTO provider_cache
+             (provider, file_path, content, query_used, cached_at, ttl, project_root)
+             VALUES (?, ?, ?, ?, ?, ?, '')`,
+            [provider, entry.filePath, entry.content, queryUsed, Date.now(), ttl]
+          );
+        }
       }
       this.db.run("COMMIT");
       this.save();
@@ -497,12 +784,19 @@ export class GraphStore {
   /**
    * Remove all stale cache entries. Called at SessionStart before warmup.
    */
-  pruneStaleCache(): number {
+  pruneStaleCache(projectRoot?: string): number {
     const now = Date.now();
-    this.db.run(
-      "DELETE FROM provider_cache WHERE (cached_at + ttl * 1000) <= ?",
-      [now]
-    );
+    if (projectRoot) {
+      this.db.run(
+        "DELETE FROM provider_cache WHERE project_root = ? AND (cached_at + ttl * 1000) <= ?",
+        [projectRoot, now]
+      );
+    } else {
+      this.db.run(
+        "DELETE FROM provider_cache WHERE (cached_at + ttl * 1000) <= ?",
+        [now]
+      );
+    }
     const result = this.db.exec("SELECT changes()");
     return (result[0]?.values[0]?.[0] as number) ?? 0;
   }
@@ -511,24 +805,32 @@ export class GraphStore {
    * Remove all cache entries for a provider. Used when a provider is
    * disabled or its configuration changes.
    */
-  clearProviderCache(provider: string): void {
-    this.db.run("DELETE FROM provider_cache WHERE provider = ?", [provider]);
+  clearProviderCache(provider: string, projectRoot?: string): void {
+    if (projectRoot) this.db.run("DELETE FROM provider_cache WHERE provider = ? AND project_root = ?", [provider, projectRoot]);
+    else this.db.run("DELETE FROM provider_cache WHERE provider = ?", [provider]);
   }
 
   /**
    * Get count of cached entries per provider.
    */
-  getCacheStats(): Array<{ provider: string; count: number; stale: number }> {
+  getCacheStats(projectRoot?: string): Array<{ provider: string; count: number; stale: number }> {
     const now = Date.now();
     const results: Array<{ provider: string; count: number; stale: number }> = [];
     const stmt = this.db.prepare(
-      `SELECT provider,
+      projectRoot
+        ? `SELECT provider,
+              COUNT(*) as total,
+              SUM(CASE WHEN (cached_at + ttl * 1000) <= ? THEN 1 ELSE 0 END) as stale
+         FROM provider_cache WHERE project_root = ?
+         GROUP BY provider`
+        : `SELECT provider,
               COUNT(*) as total,
               SUM(CASE WHEN (cached_at + ttl * 1000) <= ? THEN 1 ELSE 0 END) as stale
-       FROM provider_cache
-       GROUP BY provider`
+         FROM provider_cache
+         GROUP BY provider`
     );
-    stmt.bind([now]);
+    if (projectRoot) stmt.bind([now, projectRoot]);
+    else stmt.bind([now]);
     while (stmt.step()) {
       const row = stmt.getAsObject();
       results.push({
@@ -581,6 +883,12 @@ export class GraphStore {
   private rowToNode(row: Record<string, unknown>): GraphNode {
     const validUntilRaw = row.valid_until;
     const invalidatedByRaw = row.invalidated_by_commit;
+    const meta = JSON.parse((row.metadata as string) || "{}");
+    // Project scoping fields exposed in metadata for convenience.
+    (meta as Record<string, unknown>).projectRoot = (row.project_root as string) ?? "";
+    (meta as Record<string, unknown>).projectBranch = (row.project_branch as string) ?? null;
+    (meta as Record<string, unknown>).memoryScope = (row.memory_scope as string) ?? null;
+
     return {
       id: row.id as string,
       label: row.label as string,
@@ -591,7 +899,7 @@ export class GraphStore {
       confidenceScore: (row.confidence_score as number) ?? 1.0,
       lastVerified: (row.last_verified as number) ?? 0,
       queryCount: (row.query_count as number) ?? 0,
-      metadata: JSON.parse((row.metadata as string) || "{}"),
+      metadata: meta,
       validUntil:
         validUntilRaw === null || validUntilRaw === undefined
           ? undefined
@@ -604,6 +912,9 @@ export class GraphStore {
   }
 
   private rowToEdge(row: Record<string, unknown>): GraphEdge {
+    const meta = JSON.parse((row.metadata as string) || "{}");
+    (meta as Record<string, unknown>).projectRoot = (row.project_root as string) ?? "";
+
     return {
       source: row.source as string,
       target: row.target as string,
@@ -613,7 +924,7 @@ export class GraphStore {
       sourceFile: (row.source_file as string) ?? "",
       sourceLocation: (row.source_location as string) ?? null,
       lastVerified: (row.last_verified as number) ?? 0,
-      metadata: JSON.parse((row.metadata as string) || "{}"),
+      metadata: meta,
     };
   }
 }
diff --git a/src/hooks.ts b/src/hooks.ts
index 43eb968..9578845 100644
--- a/src/hooks.ts
+++ b/src/hooks.ts
@@ -40,7 +40,7 @@ if [ -z "$ENGRAM_BIN" ]; then
 fi
 
 if [ -d ".engram" ] && [ -f "$ENGRAM_BIN" ]; then
-  echo "[engram] Branch switched — rebuilding graph..."
+  echo "[engramx] Branch switched — rebuilding graph..."
   node "$ENGRAM_BIN" init . --quiet 2>/dev/null &
 fi
 ${HOOK_END}
diff --git a/src/integrations/pi.ts b/src/integrations/pi.ts
new file mode 100644
index 0000000..378e28f
--- /dev/null
+++ b/src/integrations/pi.ts
@@ -0,0 +1,102 @@
+/**
+ * PI integration helpers — minimal client to call the local engram HTTP
+ * server. Designed for simple integrations from external tooling (like
+ * pi). This is intentionally tiny and dependency-free: it uses the
+ * platform fetch API (Node 20+) and reads the local token file at
+ * ~/.engram/http-server.token when a token is not supplied.
+ *
+ * Usage:
+ *   import { postHook, postLearn, query } from "../integrations/pi.js";
+ *   await postHook({ hook_event_name: 'SessionStart', cwd: '/path', source: 'startup' });
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// Node 20+ provides a global `fetch`, but TypeScript's lib config
+// may not include DOM types in all environments. Declare the symbol
+// loosely here so this helper compiles under the repo's strict tsconfig.
+declare const fetch: any;
+
+const DEFAULT_PORT = 7337;
+const TOKEN_MIN_LEN = 32;
+
+function tokenPath(): string {
+  return join(homedir(), ".engram", "http-server.token");
+}
+
+function readTokenFromFile(): string | null {
+  const p = tokenPath();
+  if (!existsSync(p)) return null;
+  try {
+    const s = readFileSync(p, "utf-8").trim();
+    return s.length >= TOKEN_MIN_LEN ? s : null;
+  } catch {
+    return null;
+  }
+}
+
+async function fetchWithAuth(
+  path: string,
+  opts: { method?: string; body?: unknown; port?: number; token?: string } = {}
+): Promise<any> {
+  const port = opts.port ?? DEFAULT_PORT;
+  const token = opts.token ?? readTokenFromFile();
+  if (!token) throw new Error("No engram HTTP server token found; start the server or pass a token.");
+
+  const url = `http://127.0.0.1:${port}${path}`;
+
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${token}`,
+  };
+  let body: string | undefined;
+  if (opts.body !== undefined) {
+    headers["Content-Type"] = "application/json";
+    body = JSON.stringify(opts.body);
+  }
+
+  const res = await fetch(url, { method: opts.method ?? "GET", headers, body });
+  if (res.status === 204) return null;
+  if (res.status >= 400) {
+    const txt = await res.text();
+    throw new Error(`engram HTTP ${res.status}: ${txt}`);
+  }
+  return await res.json();
+}
+
+export async function postHook(
+  payload: unknown,
+  port?: number,
+  token?: string
+): Promise<any | null> {
+  return await fetchWithAuth("/hook", { method: "POST", body: payload, port, token });
+}
+
+export async function postLearn(
+  content: string,
+  file?: string,
+  port?: number,
+  token?: string
+): Promise<any> {
+  return await fetchWithAuth("/learn", { method: "POST", body: { content, file }, port, token });
+}
+
+export async function query(
+  q: string,
+  port?: number,
+  token?: string
+): Promise<any> {
+  const portToUse = port ?? DEFAULT_PORT;
+  const tokenToUse = token ?? readTokenFromFile();
+  if (!tokenToUse) throw new Error("No engram HTTP server token found; start the server or pass a token.");
+  const url = `http://127.0.0.1:${portToUse}/query?q=${encodeURIComponent(q)}`;
+  const res = await fetch(url, { headers: { Authorization: `Bearer ${tokenToUse}` } });
+  if (res.status >= 400) {
+    const txt = await res.text();
+    throw new Error(`engram HTTP ${res.status}: ${txt}`);
+  }
+  return await res.json();
+}
+
+export default { postHook, postLearn, query };
diff --git a/src/intelligence/token-tracker.ts b/src/intelligence/token-tracker.ts
index 139d7b0..e30315e 100644
--- a/src/intelligence/token-tracker.ts
+++ b/src/intelligence/token-tracker.ts
@@ -3,6 +3,8 @@
  * The viral screenshot generator. Hard numbers, not marketing claims.
  */
 import type { GraphStore } from "../graph/store.js";
+import { projectStatKey } from "../core.js";
+import { resolve as resolvePath } from "node:path";
 
 export interface SessionTokens {
   naiveTokens: number;
@@ -22,29 +24,65 @@ export interface CumulativeStats {
 
 const COST_PER_MILLION_TOKENS = 3.0;
 
+/**
+ * Record a single session's token numbers. If projectRoot is provided,
+ * stats are stored namespaced to that project so dashboards per-project
+ * show the correct totals.
+ */
 export function recordSession(
   store: GraphStore,
   naiveTokens: number,
-  graphTokens: number
+  graphTokens: number,
+  projectRoot?: string
 ): SessionTokens {
   const saved = Math.max(0, naiveTokens - graphTokens);
   const savedPct =
     naiveTokens > 0 ? Math.round((saved / naiveTokens) * 1000) / 10 : 0;
 
-  const prev = getCumulativeStats(store);
-  store.setStat("total_sessions", String(prev.totalSessions + 1));
-  store.setStat("total_naive_tokens", String(prev.totalNaiveTokens + naiveTokens));
-  store.setStat("total_graph_tokens", String(prev.totalGraphTokens + graphTokens));
-  store.setStat("total_tokens_saved", String(prev.totalSaved + saved));
+  const prev = getCumulativeStats(store, projectRoot);
+  const root = projectRoot ? resolvePath(projectRoot) : undefined;
+  const sessKey = root ? projectStatKey(root, "total_sessions") : "total_sessions";
+  const naiveKey = root ? projectStatKey(root, "total_naive_tokens") : "total_naive_tokens";
+  const graphKey = root ? projectStatKey(root, "total_graph_tokens") : "total_graph_tokens";
+  const savedKey = root ? projectStatKey(root, "total_tokens_saved") : "total_tokens_saved";
+
+  store.setStat(sessKey, String(prev.totalSessions + 1));
+  store.setStat(naiveKey, String(prev.totalNaiveTokens + naiveTokens));
+  store.setStat(graphKey, String(prev.totalGraphTokens + graphTokens));
+  store.setStat(savedKey, String(prev.totalSaved + saved));
+
+  // Append to a session log for time-series visualization. Keep the
+  // last 1000 entries to avoid unbounded growth.
+  try {
+    const logKey = root ? projectStatKey(root, "session_log") : "session_log";
+    const existing = store.getStat(logKey);
+    let arr: any[] = [];
+    if (existing) {
+      try { arr = JSON.parse(existing); if (!Array.isArray(arr)) arr = []; } catch { arr = []; }
+    }
+    arr.push({ ts: Date.now(), naiveTokens, graphTokens, saved, savedPct });
+    if (arr.length > 1000) arr = arr.slice(-1000);
+    store.setStat(logKey, JSON.stringify(arr));
+  } catch {
+    // best-effort only
+  }
 
   return { naiveTokens, graphTokens, saved, savedPct };
 }
 
-export function getCumulativeStats(store: GraphStore): CumulativeStats {
-  const totalSessions = store.getStatNum("total_sessions");
-  const totalNaiveTokens = store.getStatNum("total_naive_tokens");
-  const totalGraphTokens = store.getStatNum("total_graph_tokens");
-  const totalSaved = store.getStatNum("total_tokens_saved");
+/**
+ * Read cumulative token stats. If projectRoot is provided, favors
+ * project-scoped keys (project:<b64root>:<key>) and falls back to the
+ * global keys when absent.
+ */
+export function getCumulativeStats(store: GraphStore, projectRoot?: string): CumulativeStats {
+  const root = projectRoot ? resolvePath(projectRoot) : undefined;
+  const makeKey = (k: string) => (root ? projectStatKey(root, k) : k);
+
+  const totalSessions = store.getStatNum(makeKey("total_sessions"));
+  const totalNaiveTokens = store.getStatNum(makeKey("total_naive_tokens"));
+  const totalGraphTokens = store.getStatNum(makeKey("total_graph_tokens"));
+  const totalSaved = store.getStatNum(makeKey("total_tokens_saved"));
   // avgReduction is a percentage (0-100). E.g., 88.4 means 88.4% fewer tokens
   // consumed when engram intercepts vs the naive full-read baseline.
   const avgReduction = totalNaiveTokens > 0
diff --git a/src/intercept/auto-memory.ts b/src/intercept/auto-memory.ts
new file mode 100644
index 0000000..4d2a540
--- /dev/null
+++ b/src/intercept/auto-memory.ts
@@ -0,0 +1,173 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, relative, extname } from "node:path";
+import { createHash } from "node:crypto";
+import { getStore, learn, projectStatKey } from "../core.js";
+import { readConfig } from "../tuner/config.js";
+import { isContentUnsafeForIntercept } from "./context.js";
+
+// Conservative caps to avoid storing huge blobs
+const MAX_CONTENT_CHARS = 16_000;
+const MIN_CONTENT_CHARS = 20;
+
+function truncateContent(s: string): string {
+  if (!s) return "";
+  return s.length > MAX_CONTENT_CHARS ? s.slice(0, MAX_CONTENT_CHARS) : s;
+}
+
+function sha1Hex(s: string): string {
+  return createHash("sha1").update(s).digest("hex");
+}
+
+function isLikelyTextFile(filePath: string): boolean {
+  const ext = extname(filePath || "").toLowerCase();
+  return ext === ".md" || ext === ".markdown" || ext === ".txt" || ext === ".rst" || ext === ".mdown" || ext === ".adoc" || ext === ".html" || ext === ".htm";
+}
+
+/**
+ * Perform auto-learn for a piece of textual content into the engram store.
+ * Dedupe by hashing the content per-scope+relPath so identical content
+ * isn't re-inserted repeatedly. Uses project's global DB via getStore.
+ *
+ * Non-throwing: any internal error is swallowed so callers can fire-and-forget.
+ */
+export async function performAutoLearnForContent(
+  projectRoot: string,
+  content: string,
+  relPath?: string,
+  sourceLabel?: string
+): Promise<void> {
+  try {
+    if (!projectRoot || !content || typeof content !== "string") return;
+    const cfg = readConfig(projectRoot);
+
+    // Aggressive default: if config doesn't mention autoMemory fields,
+    // treat as enabled across all scopes. For safety, tests can override
+    // readConfig to set different defaults.
+    const autoEnabled = (cfg as any).autoMemoryEnabled !== undefined ? (cfg as any).autoMemoryEnabled : true;
+    if (!autoEnabled) return;
+
+    const scopes: string[] = (cfg as any).autoMemoryScopes ?? ["project", "global", "entity"];
+
+    // Trim + sanity
+    const trimmed = truncateContent(content).trim();
+    if (trimmed.length < MIN_CONTENT_CHARS) return;
+
+    // If a relPath is given and the file looks unsafe (binary / secrets), skip
+    if (relPath && isContentUnsafeForIntercept(relPath)) return;
+
+    // Simple entity-detection: first Markdown/H1 heading or first line
+    const firstLine = trimmed.split(/\r?\n/)[0] || "";
+    const entityMatch = firstLine.match(/^#{1,3}\s+(.{2,200})/) ?? firstLine.match(/^(.{2,100})$/);
+    const entityName = entityMatch ? (entityMatch[1] || entityMatch[0]).trim() : null;
+
+    // For each configured scope, dedupe by stat key and call learn
+    for (const scope of scopes) {
+      // entity scope: require an entity name to avoid noise
+      if (scope === "entity" && !entityName) continue;
+
+      // Build a stat key to track last-ingested hash for this relPath+scope
+      const keySuffix = `auto_mem_hash:${scope}:${encodeURIComponent(relPath ?? "session")}`;
+      const statKey = projectStatKey(projectRoot, keySuffix);
+
+      const hash = sha1Hex(trimmed + "|" + scope);
+
+      // Check existing hash
+      let store;
+      try {
+        store = await getStore(projectRoot);
+        const existing = store.getStat(statKey);
+        if (existing === hash) {
+          // Nothing new to learn for this scope
+          continue;
+        }
+      } finally {
+        if (store) store.close();
+      }
+
+      // Build a sensible source label
+      const src = sourceLabel ?? `auto:${relPath ?? "session"}`;
+
+      // For entity scope, craft a focused payload that emphasizes the entity
+      const payload = scope === "entity" && entityName
+        ? `entity: ${entityName}\n\n${trimmed}`
+        : trimmed;
+
+      try {
+        await learn(projectRoot, payload, src, scope);
+      } catch {
+        // swallow learn errors
+      }
+
+      // After successful learn attempt, record the new hash
+      try {
+        const s = await getStore(projectRoot);
+        try {
+          s.setStat(statKey, hash);
+        } finally {
+          s.close();
+        }
+      } catch {
+        // swallow
+      }
+    }
+  } catch {
+    // swallow any unexpected error; this module must be silent
+  }
+}
+
+/**
+ * Convenience wrapper used at SessionStart: learns the session brief
+ * across configured scopes. Fire-and-forget by callers.
+ */
+export async function onSessionStart(projectRoot: string, fullText: string): Promise<void> {
+  try {
+    await performAutoLearnForContent(projectRoot, fullText, "session-start", "session-start");
+  } catch {
+    // swallow
+  }
+}
+
+/**
+ * Convenience wrapper for PostToolUse Read/Edit/Write handling.
+ * If the tool provided textual output, prefer that; otherwise attempt
+ * to read the file from disk and ingest.
+ */
+export async function onPostToolFile(
+  projectRoot: string,
+  cwd: string,
+  filePath: string | undefined,
+  toolResponse: unknown
+): Promise<void> {
+  try {
+    if (!filePath) return;
+    // Prefer toolResponse string if available
+    let maybeText: string | null = null;
+    if (typeof toolResponse === "string") maybeText = toolResponse;
+    else if (toolResponse && typeof toolResponse === "object") {
+      const t = toolResponse as Record<string, unknown>;
+      if (typeof t.output === "string") maybeText = t.output;
+      else if (typeof t.stdout === "string") maybeText = t.stdout;
+      else if (typeof t.content === "string") maybeText = t.content;
+    }
+
+    // If we don't have textual toolResponse, read file from disk
+    if (!maybeText) {
+      try {
+        const resolved = filePath.startsWith("/") ? filePath : require("node:path").resolve(cwd, filePath);
+        if (existsSync(resolved) && !isContentUnsafeForIntercept(resolved)) {
+          maybeText = readFileSync(resolved, "utf8");
+          // use project-relative path for relPath
+          filePath = relative(projectRoot, resolved).replaceAll("\\", "/");
+        }
+      } catch {
+        maybeText = null;
+      }
+    }
+
+    if (maybeText && typeof maybeText === "string") {
+      await performAutoLearnForContent(projectRoot, maybeText, filePath, `auto:posttool`);
+    }
+  } catch {
+    // swallow
+  }
+}
diff --git a/src/intercept/dispatch.ts b/src/intercept/dispatch.ts
index f8ad281..e51f128 100644
--- a/src/intercept/dispatch.ts
+++ b/src/intercept/dispatch.ts
@@ -52,7 +52,11 @@ import {
   handleCwdChanged,
   type CwdChangedHookPayload,
 } from "./handlers/cwd-changed.js";
+import { handleAssistantMessage, type AssistantMessagePayload } from "./handlers/assistant-message.js";
 import { findProjectRoot, isValidCwd } from "./context.js";
+import { resolve as resolvePath } from "node:path";
+import { getStore } from "../core.js";
+import { recordSession } from "../intelligence/token-tracker.js";
 import { logHookEvent } from "../intelligence/hook-log.js";
 import { composeCostFields } from "../cost/instrument.js";
 
@@ -147,6 +151,11 @@ export async function dispatchHook(
         handleCwdChanged(payload as unknown as CwdChangedHookPayload)
       );
 
+    case "AssistantMessage":
+      return runHandler(() =>
+        handleAssistantMessage(payload as unknown as AssistantMessagePayload)
+      );
+
     default:
       return PASSTHROUGH;
   }
@@ -208,18 +217,47 @@ async function dispatchPreToolUse(
       const projectRoot = findProjectRoot(cwd);
       if (projectRoot) {
         const decision = extractPreToolDecision(result);
-        const filePath =
-          typeof handlerPayload.tool_input?.file_path === "string"
-            ? handlerPayload.tool_input.file_path
-            : undefined;
-        const cost = composeCostFields(tool, filePath, result);
+        const rawFilePath = typeof handlerPayload.tool_input?.file_path === "string"
+          ? handlerPayload.tool_input.file_path
+          : undefined;
+        // Resolve a candidate absolute path for cost estimation. Many hook
+        // payloads provide project-relative paths; statSync requires an
+        // absolute path so we resolve relative to the hook's cwd.
+        const absForCost = (rawFilePath && typeof rawFilePath === "string")
+          ? (rawFilePath.startsWith("/") ? rawFilePath : resolvePath(cwd, rawFilePath))
+          : undefined;
+        const cost = composeCostFields(tool, absForCost, result);
         logHookEvent(projectRoot, {
           event: "PreToolUse",
           tool,
-          path: filePath,
+          path: rawFilePath,
           decision,
           ...cost,
         });
+
+        // Record session-level token stats (best-effort, async). We use
+        // wouldHaveRead as the naive baseline and injected as the graph
+        // tokens consumed. Fire-and-forget so we don't block hook handling.
+        try {
+          (async () => {
+            try {
+              const naive = Number((cost && (cost as any).wouldHaveRead) || 0);
+              const graph = Number((cost && (cost as any).injected) || 0);
+              if (naive > 0 || graph > 0) {
+                const s = await getStore(projectRoot);
+                try {
+                  recordSession(s, naive, graph, projectRoot);
+                } finally {
+                  s.close();
+                }
+              }
+            } catch {
+              /* swallow */
+            }
+          })();
+        } catch {
+          /* swallow */
+        }
       }
     }
   } catch {
diff --git a/src/intercept/handlers/assistant-message.ts b/src/intercept/handlers/assistant-message.ts
new file mode 100644
index 0000000..e42d9fa
--- /dev/null
+++ b/src/intercept/handlers/assistant-message.ts
@@ -0,0 +1,74 @@
+import { findProjectRoot, isValidCwd } from "../context.js";
+import { isHookDisabled, PASSTHROUGH, type HandlerResult } from "../safety.js";
+import { learn } from "../../core.js";
+import { logHookEvent } from "../../intelligence/hook-log.js";
+
+export interface AssistantMessagePayload {
+  readonly hook_event_name: "AssistantMessage" | string;
+  readonly cwd: string;
+  readonly content?: string;
+  readonly summary?: string;
+  readonly memoryScope?: string; // project | global | entity
+  readonly sourceLabel?: string;
+}
+
+/**
+ * Handle an AssistantMessage hook payload. This is an opt-in hook that
+ * external clients (the agent host) can call to tell engram that the
+ * assistant produced content that should be persisted as memory.
+ *
+ * Behaviour:
+ *  - Validates cwd and project root
+ *  - If a textual `content` or `summary` is provided, calls core.learn()
+ *    asynchronously to persist conclusions/fragments into the graph.
+ *  - Returns PASSTHROUGH (observer-only). Any internal error is swallowed.
+ */
+export async function handleAssistantMessage(
+  payload: AssistantMessagePayload
+): Promise<HandlerResult> {
+  if (payload.hook_event_name !== "AssistantMessage") return PASSTHROUGH;
+
+  try {
+    const cwd = payload.cwd;
+    if (!isValidCwd(cwd)) return PASSTHROUGH;
+
+    const projectRoot = findProjectRoot(cwd);
+    if (projectRoot === null) return PASSTHROUGH;
+
+    if (isHookDisabled(projectRoot)) return PASSTHROUGH;
+
+    const raw = typeof payload.content === "string" && payload.content.trim().length > 0
+      ? payload.content
+      : typeof payload.summary === "string" && payload.summary.trim().length > 0
+        ? payload.summary
+        : null;
+
+    if (!raw) return PASSTHROUGH;
+
+    // Short-circuit tiny fragments — require at least a short sentence.
+    const trimmed = raw.trim();
+    if (trimmed.length < 20) return PASSTHROUGH;
+
+    const scope = (typeof payload.memoryScope === "string" && payload.memoryScope) ? payload.memoryScope : "project";
+    const src = payload.sourceLabel ?? "assistant";
+
+    // Fire-and-forget: persist the assistant's content as a learned memory.
+    try {
+      void learn(projectRoot, trimmed, src, scope).catch(() => {});
+    } catch {
+      /* swallow */
+    }
+
+    try {
+      // Dashboard-friendly lightweight event log. Do NOT include the
+      // learned content in the log to avoid accidental leakage.
+      logHookEvent(projectRoot, { event: "Learn", tool: "Assistant", path: null, tokensSaved: 0 });
+    } catch {
+      // best-effort
+    }
+  } catch {
+    // swallow
+  }
+
+  return PASSTHROUGH;
+}
diff --git a/src/intercept/handlers/cwd-changed.ts b/src/intercept/handlers/cwd-changed.ts
index 398ab4a..2e519c4 100644
--- a/src/intercept/handlers/cwd-changed.ts
+++ b/src/intercept/handlers/cwd-changed.ts
@@ -65,7 +65,7 @@ export async function handleCwdChanged(
     const projectName = basename(resolve(projectRoot));
     const lines: string[] = [];
     lines.push(
-      `[engram] Project switched to ${projectName} (${graphStats.nodes} nodes, ${graphStats.edges} edges)`
+      `[engramx] Project switched to ${projectName} (${graphStats.nodes} nodes, ${graphStats.edges} edges)`
     );
     if (gods.length > 0) {
       lines.push("Core entities:");
diff --git a/src/intercept/handlers/mistake-guard.ts b/src/intercept/handlers/mistake-guard.ts
index 265d0bd..745f964 100644
--- a/src/intercept/handlers/mistake-guard.ts
+++ b/src/intercept/handlers/mistake-guard.ts
@@ -8,7 +8,7 @@
  *   - `2`           → strict:     tool is denied with the warning as reason
  *
  * Only fires for PreToolUse events on Edit / Write / Bash. Read events
- * already surface mistakes via the engram:mistakes context provider —
+ * already surface mistakes via the engramx:mistakes context provider —
  * duplicating the warning at tool-call time would be noise.
  *
  * Matching algorithm:
@@ -107,10 +107,10 @@ export async function findMatchingMistakesAsync(
         // the miner could have stored either shape depending on how the
         // miner was invoked. Dedupe by node id.
         const candidates = [
-          ...store.getNodesByFile(normalized),
+          ...store.getNodesByFile(normalized, 500, projectRoot),
           ...(normalized === target.filePath
             ? []
-            : store.getNodesByFile(target.filePath)),
+            : store.getNodesByFile(target.filePath, 500, projectRoot)),
         ];
         const seenIds = new Set<string>();
         for (const m of candidates) {
@@ -129,7 +129,7 @@ export async function findMatchingMistakesAsync(
         // filtered to mistake-kind nodes. Bounded by project size; this
         // only runs when ENGRAM_MISTAKE_GUARD is explicitly enabled.
         const allMistakes = store
-          .getAllNodes()
+          .getAllNodes(projectRoot)
           .filter((n) => n.kind === "mistake")
           .filter((n) => n.validUntil === undefined || n.validUntil > now);
 
diff --git a/src/intercept/handlers/post-tool.ts b/src/intercept/handlers/post-tool.ts
index 418294b..896cc16 100644
--- a/src/intercept/handlers/post-tool.ts
+++ b/src/intercept/handlers/post-tool.ts
@@ -19,6 +19,7 @@ import { isHookDisabled, PASSTHROUGH, type HandlerResult } from "../safety.js";
 import { logHookEvent } from "../../intelligence/hook-log.js";
 import { handleBashPostTool, type FileOp } from "./bash-postool.js";
 import { syncFile } from "../../watcher.js";
+import { onPostToolFile } from "../auto-memory.js";
 
 export interface PostToolHookPayload {
   readonly hook_event_name: "PostToolUse" | string;
@@ -129,6 +130,19 @@ export async function handlePostTool(
         /* silent */
       });
     }
+
+    // Aggressive auto: ingest textual tool outputs / files into memory.
+    // Fire-and-forget — must not block the hook response.
+    try {
+      if (
+        (toolName === "Read" || toolName === "Edit" || toolName === "Write") &&
+        typeof filePath === "string"
+      ) {
+        void onPostToolFile(projectRoot, cwd, filePath, payload.tool_response).catch(() => {});
+      }
+    } catch {
+      /* swallow */
+    }
   } catch {
     // Observer errors are never surfaced.
   }
diff --git a/src/intercept/handlers/pre-compact.ts b/src/intercept/handlers/pre-compact.ts
index 06250a1..67399f2 100644
--- a/src/intercept/handlers/pre-compact.ts
+++ b/src/intercept/handlers/pre-compact.ts
@@ -50,7 +50,7 @@ function formatCompactBrief(args: {
   const lines: string[] = [];
 
   lines.push(
-    `[engram] Compaction survival — ${args.projectName} (${args.nodeCount} nodes, ${args.edgeCount} edges)`
+    `[engramx] Compaction survival — ${args.projectName} (${args.nodeCount} nodes, ${args.edgeCount} edges)`
   );
 
   if (args.godNodes.length > 0) {
diff --git a/src/intercept/handlers/read.ts b/src/intercept/handlers/read.ts
index 07828fd..ce2f2f1 100644
--- a/src/intercept/handlers/read.ts
+++ b/src/intercept/handlers/read.ts
@@ -134,8 +134,8 @@ export async function handleRead(
     // Skip the structure provider — we already have the summary. Only
     // resolve the enrichment providers.
     const enrichmentProviders = [
-      "engram:mistakes",
-      "engram:git",
+      "engramx:mistakes",
+      "engramx:git",
       "mempalace",
       "context7",
       "obsidian",
@@ -168,8 +168,8 @@ async function buildNodeContext(
 ): Promise<NodeContext> {
   const store = await getStore(projectRoot);
   try {
-    const nodes = store.getNodesByFile(relPath);
-    const edges = store.getEdgesForNodes(nodes.map((n) => n.id));
+    const nodes = store.getNodesByFile(relPath, 500, projectRoot);
+    const edges = store.getEdgesForNodes(nodes.map((n) => n.id), projectRoot);
 
     // Extract import package names from import edges
     const imports = edges
@@ -188,7 +188,7 @@ async function buildNodeContext(
       `tests/${baseName.split("/").pop()}`,
     ];
     const hasTests = testPatterns.some((pattern) =>
-      store.searchNodes(pattern, 1).length > 0
+      store.searchNodes(pattern, 1, projectRoot).length > 0
     );
 
     // Get churn rate from git metadata if available
diff --git a/src/intercept/handlers/session-start.ts b/src/intercept/handlers/session-start.ts
index 3248b51..592aeb0 100644
--- a/src/intercept/handlers/session-start.ts
+++ b/src/intercept/handlers/session-start.ts
@@ -29,6 +29,7 @@ import { findProjectRoot, isValidCwd } from "../context.js";
 import { isHookDisabled, PASSTHROUGH, type HandlerResult } from "../safety.js";
 import { buildSessionContextResponse } from "../formatter.js";
 import { warmAllProviders } from "../../providers/resolver.js";
+import { onSessionStart } from "../auto-memory.js";
 
 export interface SessionStartHookPayload {
   readonly hook_event_name: "SessionStart" | string;
@@ -108,7 +109,7 @@ function formatBrief(args: {
       ? describeAgo(Date.now() - args.stats.lastMined)
       : "unknown";
   const branchStr = args.branch ? ` (branch: ${args.branch})` : "";
-  lines.push(`[engram] Project brief for ${args.projectName}${branchStr}`);
+  lines.push(`[engramx] Project brief for ${args.projectName}${branchStr}`);
   lines.push(
     `Graph: ${args.stats.nodes} nodes, ${args.stats.edges} edges, ${args.stats.extractedPct}% extracted. Last mined: ${minedAgo}.`
   );
@@ -231,9 +232,11 @@ export async function handleSessionStart(
 ): Promise<HandlerResult> {
   if (payload.hook_event_name !== "SessionStart") return PASSTHROUGH;
 
-  // Skip resumed sessions — they already have prior context.
+  // Include resumed sessions too — inject the brief even on resume so
+  // session context is always available to the agent. onSessionStart is
+  // idempotent / dedupes, so repeated injections are safe.
   const source = payload.source ?? "startup";
-  if (source === "resume") return PASSTHROUGH;
+  // fall through for 'resume' — inject on resume as well.
 
   // cwd must be a real absolute directory. Anything else causes
   // findProjectRoot to walk from the ambient process cwd, which could
@@ -310,6 +313,14 @@ export async function handleSessionStart(
       // resolution with per-provider timeouts and graceful degradation.
     });
 
+    // Aggressive auto: learn the session brief into memory across scopes.
+    // Fire-and-forget — must never block session start.
+    try {
+      void onSessionStart(projectRoot, fullText).catch(() => {});
+    } catch {
+      /* swallow */
+    }
+
     return buildSessionContextResponse("SessionStart", fullText);
   } catch {
     // Any composition error → passthrough. Sessions must never fail
diff --git a/src/intercept/handlers/user-prompt.ts b/src/intercept/handlers/user-prompt.ts
index 6107a14..491f3f4 100644
--- a/src/intercept/handlers/user-prompt.ts
+++ b/src/intercept/handlers/user-prompt.ts
@@ -21,7 +21,7 @@
  * any other persistent storage. Only metadata about the injection
  * decision (yes/no) may be logged.
  */
-import { query, computeKeywordIDF } from "../../core.js";
+import { query, computeKeywordIDF, learn } from "../../core.js";
 import { findProjectRoot, isValidCwd } from "../context.js";
 import { isHookDisabled, PASSTHROUGH, type HandlerResult } from "../safety.js";
 import { buildSessionContextResponse } from "../formatter.js";
@@ -163,6 +163,19 @@ export async function handleUserPromptSubmit(
 
   if (isHookDisabled(projectRoot)) return PASSTHROUGH;
 
+  // Explicit memory requests: if the user explicitly asks the agent to
+  // remember/save/store this prompt, persist it to the project's memory.
+  // Fire-and-forget so we don't delay the hook response. We bypass the
+  // autoMemoryEnabled flag for explicit user requests.
+  try {
+    const explicitRemember = /^\s*(?:remember|save|store|dont forget|don't forget|note)\b/i;
+    if (explicitRemember.test(prompt)) {
+      void learn(projectRoot, prompt, "user:remember", "project").catch(() => {});
+    }
+  } catch {
+    /* swallow */
+  }
+
   // v0.3.1: TF-IDF common-term filter.
   //
   // The gate logic has two layers:
@@ -230,7 +243,7 @@ export async function handleUserPromptSubmit(
 
   // Format the injection. Include a short header so Claude knows this
   // is engram-provided context and not part of the user's message.
-  const header = `[engram] Pre-query context for this message (matched ${result.nodesFound} graph nodes):`;
+  const header = `[engramx] Pre-query context for this message (matched ${result.nodesFound} graph nodes):`;
   const text = `${header}\n\n${result.text}`;
 
   return buildSessionContextResponse("UserPromptSubmit", text);
diff --git a/src/intercept/memory-md.ts b/src/intercept/memory-md.ts
index 2f54db1..c07f3df 100644
--- a/src/intercept/memory-md.ts
+++ b/src/intercept/memory-md.ts
@@ -38,8 +38,8 @@ import {
 import { join } from "node:path";
 
 /** The marker block engram owns in MEMORY.md. */
-const ENGRAM_MARKER_START = "<!-- engram:structural-facts:start -->";
-const ENGRAM_MARKER_END = "<!-- engram:structural-facts:end -->";
+const ENGRAM_MARKER_START = "<!-- engramx:structural-facts:start -->";
+const ENGRAM_MARKER_END = "<!-- engramx:structural-facts:end -->";
 
 /** Sanity cap on MEMORY.md file size. */
 const MAX_MEMORY_FILE_BYTES = 1_000_000;
@@ -155,18 +155,19 @@ export function upsertEngramSection(
  * Never throws. Returns true on successful write, false on any kind
  * of failure (file too large, write error, etc.).
  */
-export function writeEngramSectionToMemoryMd(
-  projectRoot: string,
-  engramSection: string
-): boolean {
-  if (!projectRoot || typeof projectRoot !== "string") return false;
+export function writeEngramSectionToPath(memoryPath: string, engramSection: string): boolean {
+  // Allow global opt-out of automatic MEMORY.md writes. Set
+  // ENGRAM_DISABLE_AUTO_MEMORY_MD=1 in environments where writes must be
+  // suppressed. This keeps the code present for manual operations or for
+  // later re-enabling without removing the implementation.
+  if (process.env.ENGRAM_DISABLE_AUTO_MEMORY_MD === "1") return false;
+
+  if (!memoryPath || typeof memoryPath !== "string") return false;
   if (engramSection.length > MAX_ENGRAM_SECTION_BYTES) {
     // Refuse to write a section that would blow through the budget
     return false;
   }
 
-  const memoryPath = join(projectRoot, "MEMORY.md");
-
   try {
     // Read existing content if any
     let existing = "";
@@ -191,4 +192,11 @@ export function writeEngramSectionToMemoryMd(
   }
 }
 
+export function writeEngramSectionToMemoryMd(projectRoot: string, engramSection: string): boolean {
+  if (process.env.ENGRAM_DISABLE_AUTO_MEMORY_MD === "1") return false;
+  if (!projectRoot || typeof projectRoot !== "string") return false;
+  const memoryPath = join(projectRoot, "MEMORY.md");
+  return writeEngramSectionToPath(memoryPath, engramSection);
+}
+
 export { ENGRAM_MARKER_START, ENGRAM_MARKER_END, MAX_ENGRAM_SECTION_BYTES };
diff --git a/src/miners/conclusions-miner.ts b/src/miners/conclusions-miner.ts
new file mode 100644
index 0000000..47d7906
--- /dev/null
+++ b/src/miners/conclusions-miner.ts
@@ -0,0 +1,90 @@
+import type { GraphNode, GraphEdge } from "../graph/schema.js";
+
+import { computeCanonicalId } from "../graph/canonical.js";
+
+function makeId(...parts: string[]): string {
+  return parts
+    .filter(Boolean)
+    .join("_")
+    .replace(/[^a-zA-Z0-9]+/g, "_")
+    .replace(/^_|_$/g, "")
+    .toLowerCase()
+    .slice(0, 60);
+}
+
+function firstSentence(s: string): string {
+  if (!s) return "";
+  const m = s.trim().match(/([\s\S]{1,200}?[\.\!?])(\s|$)/);
+  if (m) return m[1].trim();
+  const line = s.split(/\r?\n/)[0] || s;
+  return line.trim().slice(0, 200);
+}
+
+export function generateConclusionNodes(text: string, sourceLabel = "session-summary") {
+  const nodes: GraphNode[] = [];
+  const edges: GraphEdge[] = [];
+  if (!text || typeof text !== "string") return { nodes, edges };
+
+  const now = Date.now();
+  // Build a high-level conclusion node (pattern) using the first sentence.
+  const conclLabel = (firstSentence(text) || "Conclusion from session");
+  // Use a canonical id for conclusions so repeated summaries map to the same
+  // conceptual node across sessions.
+  const conclId = computeCanonicalId(`Conclusion: ${conclLabel}`, "pattern", "project", null);
+  const conclusionNode: GraphNode = {
+    id: conclId,
+    label: `Conclusion: ${conclLabel}`,
+    kind: "pattern",
+    sourceFile: sourceLabel,
+    sourceLocation: null,
+    confidence: "INFERRED",
+    confidenceScore: 0.75,
+    lastVerified: now,
+    queryCount: 0,
+    metadata: { miner: "conclusion", sourceLabel },
+  };
+  nodes.push(conclusionNode);
+
+  // Split into fragments (sentences), cap at 20 fragments.
+  const fragments = text
+    .split(/[\n\.\!\?]+/) // naive split on sentence terminators/newlines
+    .map((f) => f.trim())
+    .filter((f) => f.length >= 20)
+    .slice(0, 20);
+
+  for (let i = 0; i < fragments.length; i++) {
+    const frag = fragments[i];
+    // Fragments are smaller and semantically transient; still use a
+    // canonical id so identical fragments across summaries dedupe.
+    const fragId = computeCanonicalId(frag.slice(0, 200), "concept", "project", null);
+    const node: GraphNode = {
+      id: fragId,
+      label: frag.length > 300 ? frag.slice(0, 297) + "..." : frag,
+      kind: "concept",
+      sourceFile: sourceLabel,
+      sourceLocation: null,
+      confidence: "INFERRED",
+      confidenceScore: 0.6,
+      lastVerified: now,
+      queryCount: 0,
+      metadata: { miner: "conclusion-fragment", index: i, sourceLabel },
+    };
+    nodes.push(node);
+
+    // Link fragment -> conclusion as rationale_for
+    const edge: GraphEdge = {
+      source: node.id,
+      target: conclusionNode.id,
+      relation: "rationale_for",
+      confidence: "INFERRED",
+      confidenceScore: 0.6,
+      sourceFile: sourceLabel,
+      sourceLocation: null,
+      lastVerified: now,
+      metadata: { auto: true },
+    };
+    edges.push(edge);
+  }
+
+  return { nodes, edges };
+}
diff --git a/src/miners/git-miner.ts b/src/miners/git-miner.ts
index ddd2d93..4a422be 100644
--- a/src/miners/git-miner.ts
+++ b/src/miners/git-miner.ts
@@ -22,7 +22,7 @@ function runGit(args: string[], cwd: string): string {
   } catch (err: unknown) {
     const msg = err instanceof Error ? err.message : String(err);
     if (msg.includes("TIMEOUT") || msg.includes("timed out")) {
-      console.error(`[engram] git command timed out: git ${args.join(" ")}`);
+      console.error(`[engramx] git command timed out: git ${args.join(" ")}`);
     }
     return "";
   }
diff --git a/src/miners/linking-helpers.ts b/src/miners/linking-helpers.ts
new file mode 100644
index 0000000..1be22da
--- /dev/null
+++ b/src/miners/linking-helpers.ts
@@ -0,0 +1,104 @@
+/**
+ * Heuristic helpers for extracting linking candidates from free text.
+ * Used by core.learn to create inferred edges between summary/conclusion
+ * fragments and existing graph nodes (files, identifiers, commands).
+ */
+import { basename } from "node:path";
+
+function splitCamelCaseToken(tok: string): string[] {
+  // Split camelCase and PascalCase: fooBar -> [foo, Bar]
+  const s = tok.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
+  // Replace non-word separators with spaces then split
+  return s.split(/[^A-Za-z0-9]+/).filter(Boolean).map((t) => t.toLowerCase());
+}
+
+export function extractKeywords(text: string, minLength = 4, maxTokens = 60): string[] {
+  if (!text) return [];
+  const seen = new Set<string>();
+
+  // 1) inline code/backtick spans are high-value — include them
+  for (const m of text.matchAll(/`([^`]+)`/g)) {
+    const t = String(m[1]).trim();
+    for (const part of t.split(/[^A-Za-z0-9_]/).filter(Boolean)) {
+      if (part.length >= 2) {
+        for (const p of splitCamelCaseToken(part)) {
+          if (p.length >= minLength) seen.add(p);
+        }
+      }
+    }
+  }
+
+  // 2) identifiers / words from plain text
+  for (const m of text.matchAll(/\b[A-Za-z_][A-Za-z0-9_]{2,}\b/g)) {
+    const tok = String(m[0]);
+    for (const p of splitCamelCaseToken(tok)) {
+      if (p.length >= minLength) seen.add(p);
+    }
+    if (seen.size >= maxTokens) break;
+  }
+
+  // 3) bigrams of nouns (naive): two adjacent words of alpha chars
+  if (seen.size < maxTokens) {
+    for (const m of text.matchAll(/\b([A-Za-z]{3,})\s+([A-Za-z]{3,})\b/g)) {
+      const bigram = (m[1] + " " + m[2]).toLowerCase();
+      if (bigram.length >= minLength && bigram.split(/\s+/).every((s) => s.length >= 3)) seen.add(bigram);
+      if (seen.size >= maxTokens) break;
+    }
+  }
+
+  return Array.from(seen).slice(0, maxTokens);
+}
+
+export function extractFilePaths(text: string): string[] {
+  if (!text) return [];
+  const out: string[] = [];
+  // Match explicit paths like src/foo/bar.ts or ./module/index.js or README.md
+  const pathRe = /(?:`([^`]+)`)|((?:\.\/?|\/?)[\w\-\.\/]+\.[a-z0-9]{1,6})/gi;
+  for (const m of text.matchAll(pathRe)) {
+    const candidate = (m[1] || m[2] || "").trim();
+    if (!candidate) continue;
+    // Strip surrounding ./ prefixes
+    let c = candidate.replace(/^\.\//, "");
+    // Normalize windows drive like C:/foo -> foo (best-effort)
+    c = c.replace(/^[A-Z]:\\/i, "");
+    if (c.length > 0) out.push(c);
+  }
+  // Dedupe while preserving order
+  return Array.from(new Set(out));
+}
+
+export function extractCommands(text: string): string[] {
+  if (!text) return [];
+  const cmds = new Set<string>();
+  // Prefer backticked commands e.g. `git commit` or `npx tsx ...`
+  for (const m of text.matchAll(/`([^`]{2,200})`/g)) {
+    const t = String(m[1]).trim();
+    if (t.length > 0) cmds.add(t);
+  }
+
+  // Look for common command names followed by args, up to punctuation
+  const common = ["git", "npm", "npx", "yarn", "pnpm", "node", "engram", "pi", "make"];
+  const re = new RegExp(`\\b(${common.join("|")})\\b[^\\n\\,;\.]{0,80}`, "gi");
+  for (const m of text.matchAll(re)) {
+    const t = String(m[0]).trim();
+    if (t.length > 0) cmds.add(t);
+  }
+
+  return Array.from(cmds);
+}
+
+export function basenameFromPath(p: string): string | null {
+  try {
+    return basename(p);
+  } catch {
+    return null;
+  }
+}
+
+export function extractLinkCandidates(text: string) {
+  return {
+    keywords: extractKeywords(text),
+    filePaths: extractFilePaths(text),
+    commands: extractCommands(text),
+  };
+}
diff --git a/src/miners/pdf-miner.ts b/src/miners/pdf-miner.ts
new file mode 100644
index 0000000..b8973d0
--- /dev/null
+++ b/src/miners/pdf-miner.ts
@@ -0,0 +1,64 @@
+import { readFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileP = promisify(execFile as any) as (file: string, args: string[]) => Promise<{ stdout: string; stderr: string }>;
+
+/**
+ * Try to extract text from a PDF.
+ * - Prefer `pdf-parse` if available via node_modules (async import).
+ * - Fallback to `pdftotext` binary if present (`pdftotext file -`).
+ * - Returns extracted text or null on failure.
+ */
+export async function extractTextFromPdf(filePath: string): Promise<string | null> {
+  // 1) Try dynamic import of pdf-parse (npm module)
+  try {
+    // pdf-parse is a CommonJS module; dynamic import may return a namespace
+    // where the default export is the function we want.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const m = await import("pdf-parse");
+    const pdfParse = (m && (m.default ?? m)) as any;
+    if (typeof pdfParse === "function") {
+      const data = readFileSync(filePath);
+      try {
+        const r = await pdfParse(data as any);
+        if (r && typeof r.text === "string") return r.text;
+      } catch {
+        // fallthrough to other methods
+      }
+    }
+  } catch {
+    // dynamic import failed — try pdftotext
+  }
+
+  // 2) Try pdftotext CLI
+  try {
+    const { stdout } = await execFileP("pdftotext", [filePath, "-"]);
+    if (stdout && stdout.length > 0) return stdout;
+  } catch {
+    // can't run pdftotext or it failed
+  }
+
+  return null;
+}
+
+/**
+ * Wrapper for extracting text from a file. For PDF paths, calls extractTextFromPdf.
+ * For other files, reads UTF-8 text. Returns null if extraction failed.
+ */
+export async function extractTextFromFile(filePath: string): Promise<string | null> {
+  const ext = (filePath.split(".").pop() || "").toLowerCase();
+  try {
+    if (ext === "pdf") {
+      return await extractTextFromPdf(filePath);
+    }
+    // Plain text fallback
+    try {
+      return readFileSync(filePath, "utf-8");
+    } catch {
+      return null;
+    }
+  } catch {
+    return null;
+  }
+}
diff --git a/src/miners/session-miner.ts b/src/miners/session-miner.ts
index 72b8fc2..10ca698 100644
--- a/src/miners/session-miner.ts
+++ b/src/miners/session-miner.ts
@@ -28,6 +28,8 @@ const PATTERN_PATTERNS = [
   /(?:we use|our approach|the way we|standard is)\s+(.{10,60})/gi,
 ];
 
+import { computeCanonicalId } from "../graph/canonical.js";
+
 function makeId(...parts: string[]): string {
   return parts
     .filter(Boolean)
@@ -47,8 +49,11 @@ function mineText(text: string, sourceFile: string): SessionMineResult {
     const normalized = label.trim().toLowerCase();
     if (seenLabels.has(normalized) || normalized.length < 5) return;
     seenLabels.add(normalized);
+    // Compute canonical id for learned session-level concepts so duplicates
+    // across sessions and summaries map to the same entity.
+    const canonical = computeCanonicalId(label.trim(), kind, "project", null);
     nodes.push({
-      id: makeId("session", kind, normalized),
+      id: canonical,
       label: label.trim(),
       kind,
       sourceFile,
diff --git a/src/providers/ast.ts b/src/providers/ast.ts
index c130020..1edc537 100644
--- a/src/providers/ast.ts
+++ b/src/providers/ast.ts
@@ -1,10 +1,10 @@
 /**
- * engram:ast provider — real AST-based symbol extraction via web-tree-sitter.
+ * engramx:ast provider — real AST-based symbol extraction via web-tree-sitter.
  *
  * Confidence 1.0 (exact, not estimated). Tier 1. 200ms timeout.
  *
  * Falls back gracefully to null on any error so the resolver can continue
- * with the regex-based engram:structure provider.
+ * with the regex-based engramx:structure provider.
  */
 import { readFileSync } from "node:fs";
 import type { Node } from "web-tree-sitter";
@@ -161,7 +161,7 @@ function formatSymbols(symbols: Symbol[], tokenBudget: number): string {
 // ─── Provider ────────────────────────────────────────────────────────────────
 
 export const astProvider: ContextProvider = {
-  name: "engram:ast",
+  name: "engramx:ast",
   label: "AST STRUCTURE",
   tier: 1,
   tokenBudget: 300,
@@ -185,7 +185,7 @@ export const astProvider: ContextProvider = {
       if (symbols.length === 0) return null;
 
       return {
-        provider: "engram:ast",
+        provider: "engramx:ast",
         content: formatSymbols(symbols, this.tokenBudget),
         confidence: 1.0,
         cached: false,
diff --git a/src/providers/engram-git.ts b/src/providers/engram-git.ts
index a27bf4f..6c8be3a 100644
--- a/src/providers/engram-git.ts
+++ b/src/providers/engram-git.ts
@@ -1,5 +1,5 @@
 /**
- * engram:git provider — surfaces recent changes, churn rate, and last
+ * engramx:git provider — surfaces recent changes, churn rate, and last
  * author for a file from git history.
  *
  * Tier 1: internal, available when in a git repo (<100ms).
@@ -10,7 +10,7 @@ import { execFileSync } from "node:child_process";
 import type { ContextProvider, NodeContext, ProviderResult } from "./types.js";
 
 export const gitProvider: ContextProvider = {
-  name: "engram:git",
+  name: "engramx:git",
   label: "CHANGES",
   tier: 1,
   tokenBudget: 50,
@@ -58,7 +58,7 @@ export const gitProvider: ContextProvider = {
       ];
 
       return {
-        provider: "engram:git",
+        provider: "engramx:git",
         content: parts.join("\n"),
         confidence: 0.9,
         cached: false,
diff --git a/src/providers/engram-mistakes.ts b/src/providers/engram-mistakes.ts
index c1363c6..0fccade 100644
--- a/src/providers/engram-mistakes.ts
+++ b/src/providers/engram-mistakes.ts
@@ -1,5 +1,5 @@
 /**
- * engram:mistakes provider — surfaces known issues and past failures
+ * engramx:mistakes provider — surfaces known issues and past failures
  * from the mistake memory system.
  *
  * Tier 1: internal, always available, no cache needed (<10ms).
@@ -8,7 +8,7 @@ import { getStore } from "../core.js";
 import type { ContextProvider, NodeContext, ProviderResult } from "./types.js";
 
 export const mistakesProvider: ContextProvider = {
-  name: "engram:mistakes",
+  name: "engramx:mistakes",
   label: "KNOWN ISSUES",
   tier: 1,
   tokenBudget: 50,
@@ -23,7 +23,7 @@ export const mistakesProvider: ContextProvider = {
       try {
         const now = Date.now();
         const allMistakes = store
-          .getNodesByFile(filePath)
+          .getNodesByFile(filePath, 500, context.projectRoot)
           .filter((n) => n.kind === "mistake")
           // v3.0 bi-temporal: hide mistakes whose source code has been
           // refactored away (`validUntil` set by the git miner when it
@@ -39,7 +39,7 @@ export const mistakesProvider: ContextProvider = {
           .join("\n");
 
         return {
-          provider: "engram:mistakes",
+          provider: "engramx:mistakes",
           content: lines,
           confidence: 0.95,
           cached: false,
diff --git a/src/providers/engram-structure.ts b/src/providers/engram-structure.ts
index 675e7b0..73f62df 100644
--- a/src/providers/engram-structure.ts
+++ b/src/providers/engram-structure.ts
@@ -1,5 +1,5 @@
 /**
- * engram:structure provider — serves the structural summary from the
+ * engramx:structure provider — serves the structural summary from the
  * local graph. This is the existing renderFileStructure behavior
  * wrapped in the ContextProvider interface.
  *
@@ -10,7 +10,7 @@ import { getStore } from "../core.js";
 import type { ContextProvider, NodeContext, ProviderResult } from "./types.js";
 
 export const structureProvider: ContextProvider = {
-  name: "engram:structure",
+  name: "engramx:structure",
   label: "STRUCTURE",
   tier: 1,
   tokenBudget: 250,
@@ -27,7 +27,7 @@ export const structureProvider: ContextProvider = {
         if (!result || result.nodeCount === 0) return null;
 
         return {
-          provider: "engram:structure",
+          provider: "engramx:structure",
           content: result.text,
           confidence: result.avgConfidence,
           cached: false,
diff --git a/src/providers/lsp.ts b/src/providers/lsp.ts
index 50d50c9..7dc4e59 100644
--- a/src/providers/lsp.ts
+++ b/src/providers/lsp.ts
@@ -38,7 +38,7 @@ async function getConnection(): Promise<LspConnection | null> {
 }
 
 export const lspProvider: ContextProvider = {
-  name: "engram:lsp",
+  name: "engramx:lsp",
   label: "LSP CONTEXT",
   tier: 1,
   tokenBudget: 100,
@@ -68,7 +68,7 @@ export const lspProvider: ContextProvider = {
           : content;
 
       return {
-        provider: "engram:lsp",
+        provider: "engramx:lsp",
         content: truncated,
         confidence: 0.95,
         cached: false,
diff --git a/src/providers/resolver.ts b/src/providers/resolver.ts
index 5f070b9..7e7ec9a 100644
--- a/src/providers/resolver.ts
+++ b/src/providers/resolver.ts
@@ -65,7 +65,7 @@ async function getMcpProviders(): Promise<readonly ContextProvider[]> {
         // One-line stderr warning per bad entry — don't crash, don't
         // noop-swallow. Users need to know their config didn't take.
         process.stderr.write(
-          `[engram] mcp-providers.json entry ${f.index}: ${f.reason}\n`
+          `[engramx] mcp-providers.json entry ${f.index}: ${f.reason}\n`
         );
       }
     }
@@ -171,11 +171,11 @@ export async function resolveRichPacket(
 
   if (results.length === 0) return null;
 
-  // When engram:ast succeeds (confidence 1.0), drop the lower-confidence
-  // engram:structure result to avoid duplicate structural content.
-  const hasAst = results.some((r) => r.provider === "engram:ast");
+  // When engramx:ast succeeds (confidence 1.0), drop the lower-confidence
+  // engramx:structure result to avoid duplicate structural content.
+  const hasAst = results.some((r) => r.provider === "engramx:ast");
   const deduped = hasAst
-    ? results.filter((r) => r.provider !== "engram:structure")
+    ? results.filter((r) => r.provider !== "engramx:structure")
     : results;
 
   // v3.0 — per-provider budget backstop. Providers are supposed to
@@ -185,7 +185,7 @@ export async function resolveRichPacket(
   const budgetedResults = enforcePerProviderBudget(deduped, allProviders);
 
   // v3.0 — mistakes-boost reranking. Results that mention a label from
-  // the engram:mistakes provider get their confidence boosted (capped
+  // the engramx:mistakes provider get their confidence boosted (capped
   // at 1.0) so they sort up within their priority tier. This surfaces
   // structural context that touches known-broken areas ahead of other
   // structural context of equal priority.
@@ -232,10 +232,10 @@ export async function resolveRichPacket(
     .map((r) => r.provider);
 
   // When called as enrichment (structure excluded), use a lighter header
-  const isEnrichment = enabledProviders && !enabledProviders.includes("engram:structure");
+  const isEnrichment = enabledProviders && !enabledProviders.includes("engramx:structure");
   const header = isEnrichment
-    ? `[engram] Additional context (${providerNames.length} providers, ~${totalTokens} tokens)`
-    : `[engram] Rich context for ${filePath} (${providerNames.length} providers, ~${totalTokens} tokens)`;
+    ? `[engramx] Additional context (${providerNames.length} providers, ~${totalTokens} tokens)`
+    : `[engramx] Rich context for ${filePath} (${providerNames.length} providers, ~${totalTokens} tokens)`;
   const text = `${header}\n\n${sections.join("\n\n")}`;
 
   return {
@@ -371,7 +371,8 @@ export async function warmAllProviders(
             store.warmCache(
               result.provider,
               [...result.entries],
-              result.provider === "context7" ? 4 * 3600 : 3600
+              result.provider === "context7" ? 4 * 3600 : 3600,
+              projectRoot
             );
             store.save();
           } finally {
@@ -429,7 +430,7 @@ export function enforcePerProviderBudget(
 }
 
 /**
- * Extract mistake labels from an engram:mistakes provider result. The
+ * Extract mistake labels from an engramx:mistakes provider result. The
  * provider formats mistakes as `  ! <label> (flagged <age>)` — one per
  * line. Returns the labels only, trimmed, lowercased for case-insensitive
  * matching.
@@ -447,7 +448,7 @@ function extractMistakeLabels(mistakesContent: string): string[] {
 
 /**
  * Boost the confidence of results whose content mentions a known-mistake
- * label from the engram:mistakes provider. Boost = 1.5x, capped at 1.0.
+ * label from the engramx:mistakes provider. Boost = 1.5x, capped at 1.0.
  * The mistakes result itself is NOT boosted (it's already at confidence
  * 0.95 — boosting would flatten the distinction between the signal and
  * the signal-holders).
@@ -458,14 +459,14 @@ function extractMistakeLabels(mistakesContent: string): string[] {
 export function boostByMistakes(
   results: readonly ProviderResult[]
 ): ProviderResult[] {
-  const mistakesResult = results.find((r) => r.provider === "engram:mistakes");
+  const mistakesResult = results.find((r) => r.provider === "engramx:mistakes");
   if (!mistakesResult) return [...results];
 
   const labels = extractMistakeLabels(mistakesResult.content);
   if (labels.length === 0) return [...results];
 
   return results.map((r) => {
-    if (r.provider === "engram:mistakes") return r;
+    if (r.provider === "engramx:mistakes") return r;
     const lower = r.content.toLowerCase();
     const matched = labels.some((label) => lower.includes(label));
     if (!matched) return r;
diff --git a/src/providers/types.ts b/src/providers/types.ts
index 0847e76..d744b86 100644
--- a/src/providers/types.ts
+++ b/src/providers/types.ts
@@ -74,7 +74,7 @@ export interface CachedContext {
  * - Providers MUST NOT throw — return null on any error
  */
 export interface ContextProvider {
-  /** Provider identifier (e.g., 'mempalace', 'engram:structure'). */
+  /** Provider identifier (e.g., 'mempalace', 'engramx:structure'). */
   readonly name: string;
   /** Display label for the rich packet section header. */
   readonly label: string;
@@ -161,9 +161,9 @@ export type RawPluginShape = Partial<ContextProvider> & {
 
 /** Provider priority order (highest first). Used when total output exceeds budget. */
 export const PROVIDER_PRIORITY: readonly string[] = [
-  "engram:ast",
-  "engram:structure",
-  "engram:mistakes",
+  "engramx:ast",
+  "engramx:structure",
+  "engramx:mistakes",
   // anthropic:memory sits between mistakes and mempalace — it's cheap
   // (tier 1, single local file read), strictly relevant when present,
   // and complements mistakes (mistakes = 'this broke'; anthropic:memory
@@ -172,9 +172,9 @@ export const PROVIDER_PRIORITY: readonly string[] = [
   "anthropic:memory",
   "mempalace",
   "context7",
-  "engram:git",
+  "engramx:git",
   "obsidian",
-  "engram:lsp",
+  "engramx:lsp",
 ];
 
 /** Default TTL for cached provider results (1 hour). */
diff --git a/src/server/http.ts b/src/server/http.ts
index d029c7c..d4f8192 100644
--- a/src/server/http.ts
+++ b/src/server/http.ts
@@ -22,12 +22,12 @@
  *   removed on shutdown. Checked by component-status.ts for HUD display.
  */
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
-import { writeFileSync, unlinkSync, mkdirSync, existsSync, statSync } from "node:fs";
-import { join } from "node:path";
-import { query, stats, learn, getStore } from "../core.js";
-import { readHookLog } from "../intelligence/hook-log.js";
+import { writeFileSync, unlinkSync, mkdirSync, existsSync, statSync, appendFileSync } from "node:fs"; import { homedir } from "node:os";
+import { join, resolve, relative, basename } from "node:path";
+import { query, stats, learn, init, getStore, projectStatKey } from "../core.js";
+import { readHookLog, logHookEvent } from "../intelligence/hook-log.js";
 import { summarizeHookLog } from "../intercept/stats.js";
-import { getCumulativeStats } from "../intelligence/token-tracker.js";
+import { getCumulativeStats, recordSession } from "../intelligence/token-tracker.js";
 import { getContextCache, ContextCache } from "../intelligence/cache.js";
 import { getComponentStatus } from "../intercept/component-status.js";
 import { buildDashboardHtml } from "./ui.js";
@@ -39,9 +39,11 @@ import {
   safeEqual,
   type TokenInfo,
 } from "./auth.js";
+import { extractTextFromFile } from "../miners/pdf-miner.js";
 
 // Read version — try both paths (works from src/ in dev and dist/ when built).
 import { createRequire } from "node:module";
+import { createHash } from "node:crypto";
 const require = createRequire(import.meta.url);
 const PKG_VERSION = (() => {
   for (const p of ["../package.json", "../../package.json"]) {
@@ -131,6 +133,64 @@ function json(
   res.end(JSON.stringify(data));
 }
 
+// Helper: decode a base64 project id back into an absolute project root path.
+function decodeProjectId(projectId: string | null): string | null {
+  if (!projectId) return null;
+  try {
+    return Buffer.from(projectId, "base64").toString("utf-8");
+  } catch {
+    return null;
+  }
+}
+
+// Helper: enumerate known projects recorded in the stats table.
+// Returns array sorted by lastModified desc (newest first). Each entry has
+// { id, root, name, lastModified } where id is base64(root).
+async function listKnownProjects(store: any): Promise<Array<{ id: string; root: string; name: string; lastModified: number }>> {
+  try {
+    const stmt = store.prepare("SELECT value FROM stats WHERE key LIKE ?");
+    stmt.bind(["%:project_root"]);
+    const roots: string[] = [];
+    while (stmt.step()) {
+      try {
+        const row = stmt.getAsObject();
+        const v = row.value as string;
+        if (v) roots.push(v);
+      } catch {
+        // ignore malformed
+      }
+    }
+    stmt.free();
+
+    const uniq = Array.from(new Set(roots));
+    const projects = uniq.map((root) => {
+      let mtime = 0;
+      try {
+        mtime = statSync(root).mtimeMs;
+      } catch {
+        try {
+          const lm = store.getStat(projectStatKey(root, "last_mined"));
+          if (lm) mtime = Number(lm) || 0;
+        } catch {
+          mtime = 0;
+        }
+      }
+      const name = basename(root) || root;
+      return {
+        id: Buffer.from(root).toString("base64"),
+        root,
+        name: name.length > 40 ? name.slice(0, 40) : name,
+        lastModified: mtime || 0,
+      };
+    });
+
+    projects.sort((a, b) => b.lastModified - a.lastModified);
+    return projects;
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Fail-closed auth. Accepts `Authorization: Bearer <token>` (CLI/curl) or
  * `Cookie: engram_token=<token>` (same-origin dashboard). Returns 401 on
@@ -217,7 +277,7 @@ async function handleQuery(
  *
  *   id: 0
  *   event: provider
- *   data: {"provider":"engram:ast","content":"…","confidence":1.0,"cached":false}
+ *   data: {"provider":"engramx:ast","content":"…","confidence":1.0,"cached":false}
  *
  *   id: 1
  *   event: provider
@@ -316,13 +376,32 @@ async function handleContextStream(
 }
 
 async function handleStats(
-  _req: IncomingMessage,
+  req: IncomingMessage,
   res: ServerResponse,
   projectRoot: string
 ): Promise<void> {
   try {
-    const result = await stats(projectRoot);
-    json(res, 200, result);
+    const url = parseUrl(req);
+    const projectId = url.searchParams.get("projectId");
+    const scope = url.searchParams.get("scope");
+
+    // Open the global store (getStore ignores the arg for DB path) and
+    // call store.getStats with an optional projectRoot to scope results.
+    const store = await getStore(projectRoot);
+    try {
+      let target: string | undefined = projectRoot;
+      if (projectId) {
+        const decoded = decodeProjectId(projectId);
+        if (decoded) target = decoded;
+      } else if (scope === "accumulative") {
+        // undefined = no project filter (aggregate across all projects)
+        target = undefined;
+      }
+      const result = store.getStats(target as any);
+      json(res, 200, result);
+    } finally {
+      store.close();
+    }
   } catch (err) {
     json(res, 500, { error: "Stats failed", detail: String(err) });
   }
@@ -346,7 +425,7 @@ async function handleLearn(
     return;
   }
 
-  let parsed: { content?: string; kind?: string; file?: string };
+  let parsed: { content?: string; kind?: string; file?: string; scope?: string };
   try {
     parsed = JSON.parse(body) as typeof parsed;
   } catch {
@@ -354,23 +433,323 @@ async function handleLearn(
     return;
   }
 
+  // If content is missing but a file path was provided, try to read/extract it
+  if ((!parsed.content || typeof parsed.content !== "string" || parsed.content.trim() === "") && parsed.file && typeof parsed.file === "string") {
+    try {
+      const candidate = parsed.file;
+      const rootAbs = resolve(projectRoot);
+      const abs = candidate.startsWith("/") ? resolve(candidate) : resolve(join(projectRoot, candidate));
+
+      // Ensure the resolved file is inside the project root to avoid accidental disclosure
+      if (!abs.startsWith(rootAbs)) {
+        json(res, 400, { error: "File must be inside project root" });
+        return;
+      }
+
+      if (!existsSync(abs)) {
+        json(res, 404, { error: "File not found", path: parsed.file });
+        return;
+      }
+
+      const extracted = await extractTextFromFile(abs);
+      if (!extracted) {
+        json(res, 500, { error: "Failed to extract text from file", path: parsed.file });
+        return;
+      }
+
+      parsed.content = extracted;
+    } catch (err) {
+      json(res, 500, { error: "Failed to read/parse file", detail: String(err) });
+      return;
+    }
+  }
+
   if (!parsed.content || typeof parsed.content !== "string") {
     json(res, 400, { error: "Missing 'content' in request body" });
     return;
   }
 
+  // memory scope: project | global | entity (default: project)
+  const scope = typeof parsed.scope === "string" && parsed.scope ? parsed.scope : "project";
+
   try {
-    await learn(projectRoot, parsed.content, parsed.file ?? "http-api");
-    json(res, 201, { ok: true });
+    const result = await learn(projectRoot, parsed.content, parsed.file ?? "http-api", scope);
+    // Treat manual learn calls as a session event for dashboard metrics.
+    try {
+      const store = await getStore(projectRoot);
+      try {
+        // Record a session with zero token counts (we don't have query tokens here).
+        recordSession(store, 0, 0, projectRoot);
+      } finally {
+        store.close();
+      }
+    } catch {
+      // Non-fatal: metrics are best-effort
+    }
+
+    try {
+      // Log a lightweight hook-like event so the dashboard's Activity tab
+      // shows manual learn actions. Do NOT include the learned content.
+      logHookEvent(projectRoot, {
+        event: "Learn",
+        tool: "HTTP",
+        path: parsed.file ?? "http-api",
+        tokensSaved: 0,
+      });
+    } catch {
+      // best effort
+    }
+
+    json(res, 201, { ok: true, nodesAdded: result.nodesAdded });
   } catch (err) {
     json(res, 500, { error: "Learn failed", detail: String(err) });
   }
 }
 
+/**
+ * Classify a short assistant message for memory-worthiness using an
+ * optional configured LLM provider (OpenAI/Anthropic). If no provider
+ * is configured or the provider call fails, return a conservative
+ * heuristic-based result.
+ */
+async function handleClassify(
+  req: IncomingMessage,
+  res: ServerResponse,
+  projectRoot: string
+): Promise<void> {
+  let body: string;
+  try {
+    body = await readBody(req);
+  } catch {
+    json(res, 400, { error: "Failed to read request body" });
+    return;
+  }
+
+  let parsed: { content?: string };
+  try {
+    parsed = JSON.parse(body) as typeof parsed;
+  } catch {
+    json(res, 400, { error: "Invalid JSON body" });
+    return;
+  }
+
+  const content = (parsed.content ?? "").toString().trim();
+  if (!content) {
+    json(res, 400, { error: "Missing 'content' in request body" });
+    return;
+  }
+
+  // Local heuristic fallback (same as the PI-side detector but server-side)
+  function heuristic(text: string) {
+    const trimmed = text.trim();
+    const markerRegex = /\[engram:([a-z0-9_-]+)(?:\s*:\s*([^\]]+))?\]/i;
+    const markerMatch = trimmed.match(markerRegex);
+    if (markerMatch) {
+      const markerType = (markerMatch[1] || "remember").toLowerCase();
+      const metaStr = markerMatch[2] || "";
+      const meta: Record<string, string> = {};
+      if (metaStr) {
+        for (const part of metaStr.split(/[,\s]+/).map((s) => s.trim()).filter(Boolean)) {
+          const kv = part.split("=");
+          if (kv.length === 2) meta[kv[0].toLowerCase()] = kv[1];
+          else meta[part.toLowerCase()] = "true";
+        }
+      }
+      const scope = meta.scope || (markerType === "global" ? "global" : "project");
+      const summary = trimmed.replace(markerRegex, "").trim() || trimmed;
+      return { shouldSave: true, type: meta.type || markerType, scope, summary, confidence: 0.95, reason: "explicit-marker" };
+    }
+
+    const htmlMatch = trimmed.match(/<memory>([\s\S]*?)<\/memory>/i);
+    if (htmlMatch) {
+      const inner = (htmlMatch[1] || "").trim();
+      return { shouldSave: true, type: "assistant-tag", scope: "project", summary: inner || trimmed, confidence: 0.9, reason: "html-tag" };
+    }
+
+    const lines = trimmed.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    const headerRegex = /^(conclusion|summary|takeaway|decided|decision|recommendation|proposal|idea|problem|issue|note|observation)[:\s\-]/i;
+    for (const line of lines) {
+      const m = line.match(headerRegex);
+      if (m) {
+        const t = (m[1] || "summary").toLowerCase();
+        const scope = t === "idea" ? "entity" : "project";
+        return { shouldSave: true, type: t, scope, summary: line, confidence: 0.85, reason: "line-header" };
+      }
+    }
+
+    if (/\bI recommend\b|\bwe should\b|\bI suggest\b|\bmy recommendation\b|\bshould be refactored\b/i.test(trimmed)) {
+      return { shouldSave: true, type: "recommendation", scope: "project", summary: trimmed.slice(0, 1000), confidence: 0.8, reason: "recommendation-phrase" };
+    }
+
+    if (/in summary|overall|to summarize|in conclusion|takeaway[:\s]/i.test(trimmed)) {
+      return { shouldSave: true, type: "summary", scope: "project", summary: trimmed.slice(0, 1000), confidence: 0.8, reason: "summary-phrase" };
+    }
+
+    if (/\b(problem|bug|issue|regression)\b/i.test(trimmed) && /\breproduce|steps to reproduce|steps to repro|cause\b/i.test(trimmed)) {
+      return { shouldSave: true, type: "problem", scope: "project", summary: trimmed.slice(0, 1500), confidence: 0.85, reason: "problem-detailed" };
+    }
+
+    return { shouldSave: false, confidence: 0.0, reason: "heuristic-none" };
+  }
+
+  // If no AI backend configured, return heuristic result.
+  const openaiKey = process.env.OPENAI_API_KEY || process.env.OPENAI_KEY || null;
+  const anthropicKey = process.env.ANTHROPIC_API_KEY || null;
+  const providerEnv = (process.env.ENGRAM_AI_PROVIDER || "").toLowerCase();
+
+  const heuristicResult = heuristic(content);
+
+  if (!openaiKey && !anthropicKey) {
+    json(res, 200, heuristicResult);
+    return;
+  }
+
+  // Prefer OpenAI if configured or providerEnv explicitly set to openai
+  const useOpenAI = Boolean(openaiKey) && (providerEnv === "openai" || !anthropicKey);
+
+  // Build a concise instruction for the LLM to emit JSON only.
+  const systemPrompt = `You are a concise classifier. Decide whether the given assistant message should be stored in project memory as a durable memory. Respond with a single JSON object only, no surrounding text. Fields: shouldSave (boolean), type (one of: conclusion, summary, recommendation, idea, problem, note, other), scope (one of: project, global, entity), summary (short one-line <=160 chars), confidence (0.0-1.0).`;
+  const userPrompt = `Message:\n${content}\n\nReturn the JSON object only.`;
+
+  try {
+    if (useOpenAI) {
+      // Call OpenAI Chat Completions
+      const model = process.env.OPENAI_MODEL || "gpt-4o-mini";
+      const controller = new AbortController();
+      const to = Number(process.env.ENGRAM_AI_TIMEOUT_MS ?? 8000);
+      const timer = setTimeout(() => controller.abort(), to);
+      try {
+        const resp = await fetch("https://api.openai.com/v1/chat/completions", {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${openaiKey}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            model,
+            messages: [
+              { role: "system", content: systemPrompt },
+              { role: "user", content: userPrompt },
+            ],
+            max_tokens: 512,
+            temperature: 0.0,
+          }),
+          signal: controller.signal,
+        });
+        clearTimeout(timer);
+
+        if (!resp.ok) {
+          const txt = await resp.text();
+          // On failure, return heuristic
+          json(res, 200, { ...heuristicResult, note: `openai_error:${resp.status}` });
+          return;
+        }
+
+        const data = await resp.json();
+        const text = (data.choices && data.choices[0] && (data.choices[0].message?.content ?? data.choices[0].text)) || "";
+        // Extract first JSON object in the text
+        const jsMatch = text.match(/\{[\s\S]*\}/);
+        if (!jsMatch) {
+          json(res, 200, heuristicResult);
+          return;
+        }
+        try {
+          const parsedJson = JSON.parse(jsMatch[0]);
+          // sanitize fields
+          parsedJson.confidence = Number(parsedJson.confidence) || 0.0;
+          parsedJson.shouldSave = Boolean(parsedJson.shouldSave);
+          parsedJson.type = parsedJson.type || "other";
+          parsedJson.scope = parsedJson.scope || "project";
+          parsedJson.summary = (parsedJson.summary || content.slice(0, 300)).toString().slice(0, 200);
+          json(res, 200, parsedJson);
+          return;
+        } catch {
+          json(res, 200, heuristicResult);
+          return;
+        }
+      } finally {
+        clearTimeout(timer);
+      }
+    } else {
+      // Anthropic path (best-effort)
+      const model = process.env.ANTHROPIC_MODEL || "claude-v1";
+      const controller = new AbortController();
+      const to = Number(process.env.ENGRAM_AI_TIMEOUT_MS ?? 8000);
+      const timer = setTimeout(() => controller.abort(), to);
+      try {
+        const prompt = `${systemPrompt}\n\n${userPrompt}`;
+        const resp = await fetch("https://api.anthropic.com/v1/complete", {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${anthropicKey}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({ model, prompt, max_tokens_to_sample: 512, temperature: 0.0 }),
+          signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (!resp.ok) {
+          json(res, 200, { ...heuristicResult, note: `anthropic_error:${resp.status}` });
+          return;
+        }
+        const data = await resp.json();
+        const text = data?.completion ?? "";
+        const jsMatch = text.match(/\{[\s\S]*\}/);
+        if (!jsMatch) {
+          json(res, 200, heuristicResult);
+          return;
+        }
+        try {
+          const parsedJson = JSON.parse(jsMatch[0]);
+          parsedJson.confidence = Number(parsedJson.confidence) || 0.0;
+          parsedJson.shouldSave = Boolean(parsedJson.shouldSave);
+          parsedJson.type = parsedJson.type || "other";
+          parsedJson.scope = parsedJson.scope || "project";
+          parsedJson.summary = (parsedJson.summary || content.slice(0, 300)).toString().slice(0, 200);
+          json(res, 200, parsedJson);
+          return;
+        } catch {
+          json(res, 200, heuristicResult);
+          return;
+        }
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+  } catch (err) {
+    // Any classifier failure falls back to heuristic
+    json(res, 200, { ...heuristicResult, note: `classifier_error:${String(err)}` });
+    return;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Dashboard API handlers
 // ---------------------------------------------------------------------------
 
+async function handleScopes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  projectRoot: string
+): Promise<void> {
+  try {
+    const store = await getStore(projectRoot);
+    try {
+      const projects = await listKnownProjects(store);
+      const scopes = [
+        { id: "accumulative", label: "ACCUMMULATIVE MEMORIES" },
+        { id: "global", label: "GLOBAL MEMORIES" },
+        { id: "personal", label: "PERSONAL MEMORIES" },
+      ];
+      json(res, 200, { scopes, projects });
+    } finally {
+      store.close();
+    }
+  } catch (err) {
+    json(res, 500, { error: "Scopes failed", detail: String(err) });
+  }
+}
+
 async function handleHookLog(
   req: IncomingMessage,
   res: ServerResponse,
@@ -380,21 +759,169 @@ async function handleHookLog(
     const url = parseUrl(req);
     const limit = parseInt(url.searchParams.get("limit") ?? "100", 10);
     const offset = parseInt(url.searchParams.get("offset") ?? "0", 10);
-    const entries = readHookLog(projectRoot);
-    const paginated = entries.slice(offset, offset + limit);
-    json(res, 200, { entries: paginated, total: entries.length });
+    const projectId = url.searchParams.get("projectId");
+    const scope = url.searchParams.get("scope");
+
+    let entries: any[] = [];
+
+    if (projectId) {
+      const decoded = decodeProjectId(projectId) || projectRoot;
+      entries = readHookLog(decoded);
+
+      // Fallback to session_log for that project if no file exists
+      if ((!entries || entries.length === 0)) {
+        try {
+          const store = await getStore(projectRoot);
+          try {
+            const raw = store.getStat(projectStatKey(decoded, "session_log"));
+            if (raw) {
+              const parsed = JSON.parse(raw);
+              if (Array.isArray(parsed) && parsed.length > 0) {
+                entries = parsed.map((s: any) => ({
+                  event: "Session",
+                  tool: "learn",
+                  path: null,
+                  tokensSaved: s.saved ?? 0,
+                  naiveTokens: s.naiveTokens ?? 0,
+                  graphTokens: s.graphTokens ?? 0,
+                  ts: new Date(s.ts).toISOString(),
+                }));
+              }
+            }
+          } finally {
+            store.close();
+          }
+        } catch {
+          // ignore
+        }
+      }
+    } else if (scope === "accumulative") {
+      // Aggregate hook logs across all known projects
+      const store = await getStore(projectRoot);
+      try {
+        const projects = await listKnownProjects(store);
+        let combined: any[] = [];
+        for (const p of projects) {
+          try {
+            const e = readHookLog(p.root);
+            if (e && e.length > 0) {
+              combined = combined.concat(e);
+            } else {
+              const raw = store.getStat(projectStatKey(p.root, "session_log"));
+              if (raw) {
+                const parsed = JSON.parse(raw);
+                if (Array.isArray(parsed)) {
+                  combined = combined.concat(parsed.map((s: any) => ({
+                    event: "Session",
+                    tool: "learn",
+                    path: null,
+                    tokensSaved: s.saved ?? 0,
+                    naiveTokens: s.naiveTokens ?? 0,
+                    graphTokens: s.graphTokens ?? 0,
+                    ts: new Date(s.ts).toISOString(),
+                  })));
+                }
+              }
+            }
+          } catch {
+            // ignore per-project failures
+          }
+        }
+        // Sort by timestamp desc
+        combined.sort((a, b) => {
+          const ta = a.ts ? new Date(a.ts).getTime() : 0;
+          const tb = b.ts ? new Date(b.ts).getTime() : 0;
+          return tb - ta;
+        });
+        entries = combined;
+      } finally {
+        store.close();
+      }
+    } else {
+      entries = readHookLog(projectRoot);
+
+      // If no hook-log exists, fall back to session log entries (best-effort)
+      if ((!entries || entries.length === 0)) {
+        try {
+          const store = await getStore(projectRoot);
+          try {
+            const raw = store.getStat(projectStatKey(projectRoot, "session_log"));
+            if (raw) {
+              const parsed = JSON.parse(raw);
+              if (Array.isArray(parsed) && parsed.length > 0) {
+                entries = parsed.map((s: any) => ({
+                  event: "Session",
+                  tool: "learn",
+                  path: null,
+                  tokensSaved: s.saved ?? 0,
+                  naiveTokens: s.naiveTokens ?? 0,
+                  graphTokens: s.graphTokens ?? 0,
+                  ts: new Date(s.ts).toISOString(),
+                }));
+              }
+            }
+          } finally {
+            store.close();
+          }
+        } catch {
+          // ignore
+        }
+      }
+    }
+
+    const paginated = (entries || []).slice(offset, offset + limit);
+    json(res, 200, { entries: paginated, total: (entries || []).length });
   } catch (err) {
     json(res, 500, { error: "Hook log read failed", detail: String(err) });
   }
 }
 
 function handleHookLogSummary(
-  _req: IncomingMessage,
+  req: IncomingMessage,
   res: ServerResponse,
   projectRoot: string
 ): void {
   try {
-    const entries = readHookLog(projectRoot);
+    const url = parseUrl(req);
+    const projectId = url.searchParams.get("projectId");
+    const scope = url.searchParams.get("scope");
+
+    let entries: any[] = [];
+
+    if (projectId) {
+      const decoded = decodeProjectId(projectId) || projectRoot;
+      entries = readHookLog(decoded);
+    } else if (scope === "accumulative") {
+      // aggregate across projects
+      (async () => {
+        const store = await getStore(projectRoot);
+        try {
+          const projects = await listKnownProjects(store);
+          let combined: any[] = [];
+          for (const p of projects) {
+            try {
+              const e = readHookLog(p.root);
+              if (e && e.length > 0) combined = combined.concat(e);
+            } catch {}
+          }
+          combined.sort((a, b) => {
+            const ta = a.ts ? new Date(a.ts).getTime() : 0;
+            const tb = b.ts ? new Date(b.ts).getTime() : 0;
+            return tb - ta;
+          });
+          const summary = summarizeHookLog(combined);
+          json(res, 200, summary);
+        } catch (err) {
+          json(res, 500, { error: "Summary failed", detail: String(err) });
+        } finally {
+          try { store.close(); } catch {}
+        }
+      })();
+      return;
+    } else {
+      entries = readHookLog(projectRoot);
+    }
+
     const summary = summarizeHookLog(entries);
     json(res, 200, summary);
   } catch (err) {
@@ -403,15 +930,86 @@ function handleHookLogSummary(
 }
 
 async function handleTokens(
-  _req: IncomingMessage,
+  req: IncomingMessage,
   res: ServerResponse,
   projectRoot: string
 ): Promise<void> {
   try {
+    const url = parseUrl(req);
+    const projectId = url.searchParams.get("projectId");
+    const scope = url.searchParams.get("scope");
+
     const store = await getStore(projectRoot);
     try {
-      const tokenStats = getCumulativeStats(store);
-      json(res, 200, tokenStats);
+      if (projectId) {
+        const decoded = decodeProjectId(projectId) || projectRoot;
+        const tokenStats = getCumulativeStats(store, decoded);
+        let sessions: any[] = [];
+        try {
+          const raw = store.getStat(projectStatKey(decoded, "session_log"));
+          if (raw) {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed)) sessions = parsed.slice(-200);
+          }
+        } catch {}
+        json(res, 200, { ...tokenStats, sessions });
+        return;
+      }
+
+      if (scope === "accumulative") {
+        // Sum per-project stats across all known projects
+        const projects = await listKnownProjects(store);
+        let totalSessions = 0;
+        let totalNaiveTokens = 0;
+        let totalGraphTokens = 0;
+        let totalSaved = 0;
+        let sessionsArr: any[] = [];
+        for (const p of projects) {
+          try {
+            const s = getCumulativeStats(store, p.root);
+            totalSessions += s.totalSessions;
+            totalNaiveTokens += s.totalNaiveTokens;
+            totalGraphTokens += s.totalGraphTokens;
+            totalSaved += s.totalSaved;
+            const raw = store.getStat(projectStatKey(p.root, "session_log"));
+            if (raw) {
+              try {
+                const parsed = JSON.parse(raw);
+                if (Array.isArray(parsed)) sessionsArr = sessionsArr.concat(parsed);
+              } catch {}
+            }
+          } catch {
+            // per-project failures are best-effort
+          }
+        }
+        // Sort sessions by ts desc and keep last 200
+        sessionsArr.sort((a, b) => (b.ts || 0) - (a.ts || 0));
+        const sessions = sessionsArr.slice(0, 200);
+        const avgReduction = totalNaiveTokens > 0 ? Math.round((totalSaved / totalNaiveTokens) * 1000) / 10 : 0;
+        const estimatedCostSaved = Math.round((totalSaved / 1_000_000) * 3 * 100) / 100;
+        json(res, 200, {
+          totalSessions,
+          totalNaiveTokens,
+          totalGraphTokens,
+          totalSaved,
+          avgReduction,
+          estimatedCostSaved,
+          sessions,
+        });
+        return;
+      }
+
+      // Default: per-server projectRoot
+      const tokenStats = getCumulativeStats(store, projectRoot);
+      let sessions: any[] = [];
+      try {
+        const raw = store.getStat(projectStatKey(projectRoot, "session_log"));
+        if (raw) {
+          const parsed = JSON.parse(raw);
+          if (Array.isArray(parsed)) sessions = parsed.slice(-200);
+        }
+      } catch {}
+      json(res, 200, { ...tokenStats, sessions });
     } finally {
       store.close();
     }
@@ -428,17 +1026,94 @@ async function handleFilesHeatmap(
   try {
     const url = parseUrl(req);
     const limit = parseInt(url.searchParams.get("limit") ?? "20", 10);
-    const entries = readHookLog(projectRoot);
-
-    // Aggregate by file path
-    const fileMap = new Map<string, { count: number; tokensSaved: number }>();
-    for (const entry of entries) {
-      if (!entry.path) continue;
-      const existing = fileMap.get(entry.path) ?? { count: 0, tokensSaved: 0 };
-      fileMap.set(entry.path, {
-        count: existing.count + 1,
-        tokensSaved: existing.tokensSaved + (entry.tokensSaved ?? 0),
-      });
+    const projectId = url.searchParams.get("projectId");
+    const scope = url.searchParams.get("scope");
+
+    let fileMap = new Map<string, { count: number; tokensSaved: number }>();
+
+    if (projectId) {
+      const decoded = decodeProjectId(projectId) || projectRoot;
+      const entries = readHookLog(decoded);
+      for (const entry of entries) {
+        if (!entry.path) continue;
+        const existing = fileMap.get(entry.path) ?? { count: 0, tokensSaved: 0 };
+        fileMap.set(entry.path, {
+          count: existing.count + 1,
+          tokensSaved: existing.tokensSaved + (entry.tokensSaved ?? 0),
+        });
+      }
+
+      if (fileMap.size === 0) {
+        const store = await getStore(projectRoot);
+        try {
+          const allNodes = store.getAllNodes(decoded);
+          for (const n of allNodes) {
+            if (!n.sourceFile) continue;
+            const existing = fileMap.get(n.sourceFile) ?? { count: 0, tokensSaved: 0 };
+            fileMap.set(n.sourceFile, { count: existing.count + 1, tokensSaved: existing.tokensSaved });
+          }
+        } finally {
+          store.close();
+        }
+      }
+    } else if (scope === "accumulative") {
+      const store = await getStore(projectRoot);
+      try {
+        // Aggregate across all nodes in DB
+        const allNodes = store.getAllNodes();
+        for (const n of allNodes) {
+          if (!n.sourceFile) continue;
+          const existing = fileMap.get(n.sourceFile) ?? { count: 0, tokensSaved: 0 };
+          fileMap.set(n.sourceFile, { count: existing.count + 1, tokensSaved: existing.tokensSaved });
+        }
+      } finally {
+        store.close();
+      }
+    } else if (scope === "global" || scope === "personal") {
+      // Filter files by nodes' memory scope across all projects
+      const desired = scope === "global" ? "global" : "entity";
+      const store = await getStore(projectRoot);
+      try {
+        const allNodes = store.getAllNodes();
+        for (const n of allNodes) {
+          try {
+            const meta = n.metadata || {};
+            const ms = (meta.memoryScope || meta.memory_scope) || "project";
+            if (ms !== desired) continue;
+            if (!n.sourceFile) continue;
+            const existing = fileMap.get(n.sourceFile) ?? { count: 0, tokensSaved: 0 };
+            fileMap.set(n.sourceFile, { count: existing.count + 1, tokensSaved: existing.tokensSaved });
+          } catch {
+            // ignore node-level parse errors
+          }
+        }
+      } finally {
+        store.close();
+      }
+    } else {
+      const entries = readHookLog(projectRoot);
+      for (const entry of entries) {
+        if (!entry.path) continue;
+        const existing = fileMap.get(entry.path) ?? { count: 0, tokensSaved: 0 };
+        fileMap.set(entry.path, {
+          count: existing.count + 1,
+          tokensSaved: existing.tokensSaved + (entry.tokensSaved ?? 0),
+        });
+      }
+
+      if (fileMap.size === 0) {
+        const store = await getStore(projectRoot);
+        try {
+          const allNodes = store.getAllNodes(projectRoot);
+          for (const n of allNodes) {
+            if (!n.sourceFile) continue;
+            const existing = fileMap.get(n.sourceFile) ?? { count: 0, tokensSaved: 0 };
+            fileMap.set(n.sourceFile, { count: existing.count + 1, tokensSaved: existing.tokensSaved });
+          }
+        } finally {
+          store.close();
+        }
+      }
     }
 
     // Sort by count descending, take top N
@@ -512,9 +1187,37 @@ async function handleGraphNodes(
     const url = parseUrl(req);
     const limit = parseInt(url.searchParams.get("limit") ?? "100", 10);
     const offset = parseInt(url.searchParams.get("offset") ?? "0", 10);
+    const projectId = url.searchParams.get("projectId");
+    const scope = url.searchParams.get("scope");
+
     const store = await getStore(projectRoot);
     try {
-      const allNodes = store.getAllNodes();
+      // Special-case memory-scope filters across all projects
+      if (scope === "global" || scope === "personal") {
+        const desired = scope === "global" ? "global" : "entity";
+        const all = store.getAllNodes();
+        const filtered = all.filter((n) => {
+          try {
+            const meta = n.metadata || {};
+            const ms = (meta.memoryScope || meta.memory_scope) || "project";
+            return ms === desired;
+          } catch {
+            return false;
+          }
+        });
+        const paginated = filtered.slice(offset, offset + limit);
+        json(res, 200, { nodes: paginated, total: filtered.length });
+        return;
+      }
+
+      let target: string | undefined = projectRoot;
+      if (projectId) {
+        const decoded = decodeProjectId(projectId);
+        if (decoded) target = decoded;
+      } else if (scope === "accumulative") {
+        target = undefined; // all nodes
+      }
+      const allNodes = store.getAllNodes(target as any);
       const paginated = allNodes.slice(offset, offset + limit);
       json(res, 200, { nodes: paginated, total: allNodes.length });
     } finally {
@@ -525,15 +1228,77 @@ async function handleGraphNodes(
   }
 }
 
+async function handleGraphEdges(
+  req: IncomingMessage,
+  res: ServerResponse,
+  projectRoot: string
+): Promise<void> {
+  try {
+    const url = parseUrl(req);
+    const idsParam = url.searchParams.get("ids");
+    if (!idsParam) {
+      json(res, 400, { error: "Missing 'ids' query parameter (comma-separated)" });
+      return;
+    }
+    const projectId = url.searchParams.get("projectId");
+    const scope = url.searchParams.get("scope");
+    // decodeURIComponent isn't needed for comma-separated ids generated by join
+    const ids = idsParam.split(",").filter((s) => s.trim().length > 0);
+    const store = await getStore(projectRoot);
+    try {
+      let target: string | undefined = projectRoot;
+      if (projectId) {
+        const decoded = decodeProjectId(projectId);
+        if (decoded) target = decoded;
+      } else if (scope === "accumulative") {
+        target = undefined;
+      }
+      const edges = store.getEdgesForNodes(ids, target as any);
+      json(res, 200, { edges });
+    } finally {
+      store.close();
+    }
+  } catch (err) {
+    json(res, 500, { error: "Graph edges failed", detail: String(err) });
+  }
+}
+
 async function handleGraphGodNodes(
-  _req: IncomingMessage,
+  req: IncomingMessage,
   res: ServerResponse,
   projectRoot: string
 ): Promise<void> {
   try {
+    const url = parseUrl(req);
+    const projectId = url.searchParams.get("projectId");
+    const scope = url.searchParams.get("scope");
     const store = await getStore(projectRoot);
     try {
-      const godNodes = store.getGodNodes(10);
+      // If memory-scope filter requested, compute across all projects
+      if (scope === "global" || scope === "personal") {
+        const desired = scope === "global" ? "global" : "entity";
+        const allGods = store.getGodNodes(200); // larger pool to choose from
+        const filtered = allGods.filter((g: any) => {
+          try {
+            const meta = g.node.metadata || {};
+            const ms = (meta.memoryScope || meta.memory_scope) || "project";
+            return ms === desired;
+          } catch {
+            return false;
+          }
+        });
+        json(res, 200, filtered.slice(0, 10));
+        return;
+      }
+
+      let target: string | undefined = projectRoot;
+      if (projectId) {
+        const decoded = decodeProjectId(projectId);
+        if (decoded) target = decoded;
+      } else if (scope === "accumulative") {
+        target = undefined;
+      }
+      const godNodes = store.getGodNodes(10, target as any);
       json(res, 200, godNodes);
     } finally {
       store.close();
@@ -566,35 +1331,40 @@ function handleSSE(
   res.write("data: {\"type\":\"connected\"}\n\n");
   sseClients.add(res);
 
-  // Start watching hook log if not already
+  // Start watching hook log if not already. Always install a periodic
+  // watcher — the log file may be created later and we still want to
+  // detect new events. Initialize lastSize to current file size or 0.
   if (!hookLogWatcher) {
     const logPath = join(projectRoot, ".engram", "hook-log.jsonl");
-    if (existsSync(logPath)) {
-      let lastSize = statSync(logPath).size;
+    let lastSize = 0;
+    try {
+      if (existsSync(logPath)) lastSize = statSync(logPath).size;
+    } catch {
+      lastSize = 0;
+    }
 
-      const checkFile = (): void => {
-        try {
-          const currentSize = statSync(logPath).size;
-          if (currentSize > lastSize) {
-            lastSize = currentSize;
-            // Broadcast to all SSE clients
-            const msg = JSON.stringify({ type: "hook-event", timestamp: Date.now() });
-            for (const client of sseClients) {
-              try {
-                client.write(`data: ${msg}\n\n`);
-              } catch {
-                sseClients.delete(client);
-              }
+    const checkFile = (): void => {
+      try {
+        const currentSize = existsSync(logPath) ? statSync(logPath).size : 0;
+        if (currentSize > lastSize) {
+          lastSize = currentSize;
+          // Broadcast to all SSE clients
+          const msg = JSON.stringify({ type: "hook-event", timestamp: Date.now() });
+          for (const client of sseClients) {
+            try {
+              client.write(`data: ${msg}\n\n`);
+            } catch {
+              sseClients.delete(client);
             }
           }
-        } catch {
-          // Log file gone or unreadable
         }
-      };
+      } catch {
+        // Log file gone or unreadable
+      }
+    };
 
-      const interval = setInterval(checkFile, 1000);
-      hookLogWatcher = () => clearInterval(interval);
-    }
+    const interval = setInterval(checkFile, 1000);
+    hookLogWatcher = () => clearInterval(interval);
   }
 
   // Cleanup on disconnect
@@ -614,7 +1384,29 @@ function handleSSE(
 function writePid(projectRoot: string): void {
   const dir = join(projectRoot, ".engram");
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, "http-server.pid"), String(process.pid), "utf-8");
+  const pidPath = join(dir, "http-server.pid");
+  writeFileSync(pidPath, String(process.pid), "utf-8");
+
+  // Audit log: append a short startup line with timestamp, pid, port, and project.
+  // Write both to a project-scoped audit file and the user-level ~/.engram/http-server.log
+  try {
+    const ts = new Date().toISOString();
+    const line = `${ts} START pid=${process.pid} port=${serverPort} project=${projectRoot}\n`;
+    try {
+      appendFileSync(join(dir, "http-server.start.log"), line, "utf-8");
+    } catch {
+      // best-effort — don't fail startup
+    }
+    try {
+      const homeLogDir = join(homedir(), ".engram");
+      if (!existsSync(homeLogDir)) mkdirSync(homeLogDir, { recursive: true });
+      appendFileSync(join(homeLogDir, "http-server.log"), line, "utf-8");
+    } catch {
+      // best-effort
+    }
+  } catch {
+    // swallow audit failures
+  }
 }
 
 function removePid(projectRoot: string): void {
@@ -754,11 +1546,15 @@ export function createHttpServer(
           handleProviders(req, res);
         } else if (req.method === "POST" && path === "/learn") {
           await handleLearn(req, res, projectRoot);
+        } else if (req.method === "POST" && path === "/classify") {
+          await handleClassify(req, res, projectRoot);
         // Dashboard API routes
         } else if (req.method === "GET" && path === "/api/hook-log") {
           await handleHookLog(req, res, projectRoot);
         } else if (req.method === "GET" && path === "/api/hook-log/summary") {
           handleHookLogSummary(req, res, projectRoot);
+        } else if (req.method === "GET" && path === "/api/scopes") {
+          await handleScopes(req, res, projectRoot);
         } else if (req.method === "GET" && path === "/api/tokens") {
           await handleTokens(req, res, projectRoot);
         } else if (req.method === "GET" && path === "/api/files/heatmap") {
@@ -769,6 +1565,8 @@ export function createHttpServer(
           await handleCacheStats(req, res, projectRoot);
         } else if (req.method === "GET" && path === "/api/graph/nodes") {
           await handleGraphNodes(req, res, projectRoot);
+        } else if (req.method === "GET" && path === "/api/graph/edges") {
+          await handleGraphEdges(req, res, projectRoot);
         } else if (req.method === "GET" && path === "/api/graph/god-nodes") {
           await handleGraphGodNodes(req, res, projectRoot);
         } else if (req.method === "GET" && path === "/api/sse") {
@@ -788,6 +1586,46 @@ export function createHttpServer(
             "X-Content-Type-Options": "nosniff",
           });
           res.end(buildDashboardHtml());
+        } else if (req.method === "POST" && path === "/hook") {
+          // Hook dispatch endpoint: accept a Hook payload (SessionStart,
+          // UserPromptSubmit, PreToolUse, etc.) and run the same dispatcher
+          // used by the `engram intercept` entry point. This lets external
+          // clients (pi, CLIs, tests) invoke engram's hook handlers over
+          // the local HTTP server securely.
+          let bodyStr: string;
+          try {
+            bodyStr = await readBody(req);
+          } catch {
+            json(res, 400, { error: "Failed to read request body" });
+            return;
+          }
+
+          let parsed: unknown;
+          try {
+            parsed = JSON.parse(bodyStr);
+          } catch {
+            json(res, 400, { error: "Invalid JSON body" });
+            return;
+          }
+
+          try {
+            const { dispatchHook } = await import("../intercept/dispatch.js");
+            const result = await dispatchHook(parsed);
+            if (result === null) {
+              // PASSTHROUGH — indicate with 204 No Content so callers know
+              // engram opted out.
+              res.writeHead(204, { ...corsHeaders(req) });
+              res.end();
+              return;
+            }
+
+            // Return the handler's result as JSON.
+            json(res, 200, result);
+            return;
+          } catch (err) {
+            json(res, 500, { error: "Hook dispatch failed", detail: String(err) });
+            return;
+          }
         } else {
           json(res, 404, { error: "Not found" });
         }
@@ -796,6 +1634,81 @@ export function createHttpServer(
       }
     });
 
+    // Upgrade handler — accept WebSocket connections for streaming ingest
+    // Path: /learn-ws
+    server.on("upgrade", (req, socket, head) => {
+      try {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+        if (url.pathname !== "/learn-ws") {
+          socket.destroy();
+          return;
+        }
+
+        // Basic host + origin checks (same as HTTP handlers)
+        if (!isHostValid(req.headers.host, port)) {
+          socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+          socket.destroy();
+          return;
+        }
+        const origin = req.headers.origin as string | undefined;
+        if (origin && !isOriginAllowed(origin, port)) {
+          socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+          socket.destroy();
+          return;
+        }
+
+        // Auth: accept Authorization: Bearer <token> or cookie engram_token
+        let ok = false;
+        const authHeader = (req.headers.authorization ?? "") as string;
+        if (typeof authHeader === "string" && authHeader.startsWith("Bearer ")) {
+          const presented = authHeader.slice(7).trim();
+          if (safeEqual(presented, currentToken())) ok = true;
+        }
+        if (!ok) {
+          const cookies = parseCookies(req.headers.cookie);
+          if (cookies.engram_token && safeEqual(cookies.engram_token, currentToken())) ok = true;
+        }
+        if (!ok) {
+          socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+          socket.destroy();
+          return;
+        }
+
+        const key = req.headers["sec-websocket-key"];
+        if (!key || typeof key !== "string") {
+          socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+          socket.destroy();
+          return;
+        }
+
+        // Compute accept key per RFC6455
+        const accept = createHash("sha1")
+          .update(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11")
+          .digest("base64");
+
+        const headers = [
+          "HTTP/1.1 101 Switching Protocols",
+          "Upgrade: websocket",
+          "Connection: Upgrade",
+          `Sec-WebSocket-Accept: ${accept}`,
+        ];
+        socket.write(headers.join("\r\n") + "\r\n\r\n");
+        socket.setNoDelay(true);
+
+        // Hand off to the WebSocket frame handler module (dynamic import so
+        // we don't add a hard dependency at module init). The handler runs
+        // the learned ingestion in background and notifies the socket with
+        // per-chunk results.
+        import("./learn-ws.js")
+          .then((m) => m.handleWebSocket(socket, projectRoot))
+          .catch(() => {
+            try { socket.destroy(); } catch { /* ignore */ }
+          });
+      } catch (e) {
+        try { socket.destroy(); } catch { /* ignore */ }
+      }
+    });
+
     server.on("error", (err) => {
       removePid(projectRoot);
       reject(err);
@@ -812,6 +1725,37 @@ export function createHttpServer(
       process.on("SIGTERM", cleanup);
 
       resolve(tokenInfo);
+
+      // Background initialization: remove kill-switch if present, trigger
+      // DB migrations by opening the store, and run an incremental init to
+      // ensure the graph is scanned so the dashboard has "Files" data.
+      // Best-effort only; failures must not crash the server.
+      (async () => {
+        try {
+          const flagPath = join(projectRoot, ".engram", "hook-disabled");
+          try {
+            if (existsSync(flagPath)) unlinkSync(flagPath);
+          } catch {
+            // ignore
+          }
+
+          // Trigger migrations and quick store open
+          try {
+            const s = await getStore(projectRoot);
+            try { s.close(); } catch {}
+          } catch {}
+
+          // Run incremental init to scan files but avoid a full heavy sweep
+          try {
+            await init(projectRoot, { incremental: true });
+          } catch {
+            // ignore
+          }
+        } catch {
+          // ignore
+        }
+      })();
+
       // Keep the process alive — the Promise resolves once the server is
       // listening, but the server continues running until a signal arrives.
     });
diff --git a/src/server/index.ts b/src/server/index.ts
index dd38300..7b974f1 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -29,15 +29,15 @@ export async function startHttpServer(
   // HttpOnly cookie set on GET /ui.
   if (tokenInfo.source === "env") {
     process.stderr.write(
-      "engram: auth token from ENGRAM_API_TOKEN env var\n"
+      "engramx: auth token from ENGRAM_API_TOKEN env var\n"
     );
   } else if (tokenInfo.source === "file") {
     process.stderr.write(
-      `engram: auth token at ${tokenInfo.path}\n`
+      `engramx: auth token at ${tokenInfo.path}\n`
     );
   } else {
     process.stderr.write(
-      `engram: auth token generated at ${tokenInfo.path} (0600)\n` +
+      `engramx: auth token generated at ${tokenInfo.path} (0600)\n` +
       `        curl -H "Authorization: Bearer $(cat ${tokenInfo.path})" ${url}/stats\n`
     );
   }
diff --git a/src/server/learn-ws.ts b/src/server/learn-ws.ts
new file mode 100644
index 0000000..bc0cb81
--- /dev/null
+++ b/src/server/learn-ws.ts
@@ -0,0 +1,152 @@
+import type { Socket } from "node:net";
+import { learn } from "../core.js";
+
+/**
+ * Build a server-to-client WebSocket frame (unmasked). Supports text/binary payloads.
+ */
+function createWsFrame(payload: Buffer, opcode = 0x1): Buffer {
+  const finAndOp = 0x80 | (opcode & 0x0f);
+  let header: Buffer;
+  const len = payload.length;
+  if (len < 126) {
+    header = Buffer.alloc(2);
+    header[0] = finAndOp;
+    header[1] = len;
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = finAndOp;
+    header[1] = 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = finAndOp;
+    header[1] = 127;
+    // write 64-bit length (high 32 bits = 0)
+    header.writeUInt32BE(0, 2);
+    header.writeUInt32BE(len, 6);
+  }
+  return Buffer.concat([header, payload]);
+}
+
+/**
+ * Handle a WebSocket connection over the provided socket. The protocol is
+ * intentionally tiny:
+ *  - Client may send either plain text (string chunk) or JSON objects.
+ *  - If JSON, expected shape: { content: string, scope?: string, file?: string, source?: string }
+ *  - Server replies immediately with { type: 'accepted', chunkId }
+ *  - When learn completes, server sends { type: 'done', chunkId, nodesAdded }
+ *  - On error: { type: 'error', chunkId, error }
+ *
+ * Writes to the graph store happen in the background (core.learn is awaited
+ * but GraphStore.save writes to disk asynchronously) so the socket/agent
+ * remains responsive.
+ */
+export function handleWebSocket(socket: Socket, projectRoot: string): void {
+  let buffer = Buffer.alloc(0);
+  let nextChunkId = 1;
+  let closed = false;
+
+  function sendObj(obj: unknown): void {
+    try {
+      const text = JSON.stringify(obj);
+      const frame = createWsFrame(Buffer.from(text, "utf8"));
+      socket.write(frame);
+    } catch {
+      // ignore send errors
+    }
+  }
+
+  socket.on("data", (chunk: Buffer) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (true) {
+      if (buffer.length < 2) break;
+      const first = buffer[0];
+      const second = buffer[1];
+      const opcode = first & 0x0f;
+      const masked = (second & 0x80) !== 0;
+      let payloadLen = second & 0x7f;
+      let offset = 2;
+
+      if (payloadLen === 126) {
+        if (buffer.length < offset + 2) break;
+        payloadLen = buffer.readUInt16BE(offset);
+        offset += 2;
+      } else if (payloadLen === 127) {
+        if (buffer.length < offset + 8) break;
+        const high = buffer.readUInt32BE(offset);
+        const low = buffer.readUInt32BE(offset + 4);
+        if (high !== 0) {
+          socket.destroy();
+          return;
+        }
+        payloadLen = low;
+        offset += 8;
+      }
+
+      if (masked) {
+        if (buffer.length < offset + 4) break;
+      }
+
+      const maskKey = masked ? buffer.slice(offset, offset + 4) : null;
+      if (masked) offset += 4;
+
+      if (buffer.length < offset + payloadLen) break;
+
+      const payload = buffer.slice(offset, offset + payloadLen);
+      if (maskKey) {
+        for (let i = 0; i < payload.length; i++) payload[i] = payload[i] ^ maskKey[i % 4];
+      }
+
+      if (opcode === 0x1) {
+        const text = payload.toString("utf8");
+        let dataObj: any;
+        try {
+          dataObj = JSON.parse(text);
+        } catch {
+          dataObj = { content: text };
+        }
+
+        const chunkId = nextChunkId++;
+        sendObj({ type: "accepted", chunkId });
+
+        const content = typeof dataObj === "object" && dataObj !== null && typeof dataObj.content === "string"
+          ? dataObj.content
+          : String(dataObj);
+        const scope = typeof dataObj === "object" && dataObj !== null && typeof dataObj.scope === "string"
+          ? dataObj.scope
+          : "project";
+        const file = typeof dataObj === "object" && dataObj !== null && typeof dataObj.file === "string"
+          ? dataObj.file
+          : undefined;
+        const sourceLabel = typeof dataObj === "object" && dataObj !== null && typeof dataObj.source === "string"
+          ? dataObj.source
+          : `ws`;
+
+        // Background ingestion — fire-and-forget but report result back
+        (async () => {
+          try {
+            const result = await learn(projectRoot, content, file ?? sourceLabel, scope);
+            if (!closed) sendObj({ type: "done", chunkId, nodesAdded: result.nodesAdded });
+          } catch (err) {
+            if (!closed) sendObj({ type: "error", chunkId, error: String(err) });
+          }
+        })();
+      } else if (opcode === 0x8) {
+        // Close frame — echo and close
+        try { socket.write(Buffer.from([0x88, 0x00])); } catch { /* ignore */ }
+        closed = true;
+        socket.destroy();
+        return;
+      } else if (opcode === 0x9) {
+        // Ping -> Pong
+        const pong = createWsFrame(payload, 0xA);
+        socket.write(pong);
+      }
+
+      buffer = buffer.slice(offset + payloadLen);
+    }
+  });
+
+  socket.on("close", () => { closed = true; });
+  socket.on("error", () => { closed = true; });
+}
diff --git a/src/server/ui-graph.ts b/src/server/ui-graph.ts
index 250780e..5225916 100644
--- a/src/server/ui-graph.ts
+++ b/src/server/ui-graph.ts
@@ -17,6 +17,9 @@
 
 export function buildGraphScript(): string {
   return `
+// ─── Global graph stop handle (ensures re-rendering doesn't leak loops) ───
+window.__engram_graph_stop = window.__engram_graph_stop || null;
+
 // ─── Node color by kind (match the graph schema) ───────────────
 const NODE_COLORS = {
   file: "#3b82f6",
@@ -28,11 +31,50 @@ const NODE_COLORS = {
   default: "#71717a",
 };
 
+// Memory scope mapping: color + shape + label. These represent the three
+// memory types we care about: project, global, and personal/entity.
+const MEMORY_SCOPE_CONFIG = {
+  project: { color: "#3b82f6", shape: "circle", label: "Project" },
+  global: { color: "#a855f7", shape: "diamond", label: "Global" },
+  entity: { color: "#f59e0b", shape: "square", label: "Personal" },
+  default: { color: "#71717a", shape: "circle", label: "Unknown" },
+};
+
+// Visual consolidation & distribution knobs
+const TOTAL_VISUAL_BUDGET = 200;    // combined visual budget baseline (nodes + edges)
+const NODE_PROP = 2 / 3;            // fraction of budget aimed at nodes
+const EDGE_PROP = 1 - NODE_PROP;    // fraction for edges
+const SCOPE_RATIOS = { project: 0.5, global: 0.25, entity: 0.25 };
+const MINORITY_THRESHOLD = 0.05;    // scopes under 5% are treated as "minorities" and preserved
+
+function pathShape(ctx, x, y, r, shape) {
+  ctx.beginPath();
+  if (shape === "circle") {
+    ctx.arc(x, y, r, 0, Math.PI * 2);
+  } else if (shape === "square") {
+    ctx.rect(x - r, y - r, r * 2, r * 2);
+  } else if (shape === "diamond") {
+    ctx.moveTo(x, y - r);
+    ctx.lineTo(x + r, y);
+    ctx.lineTo(x, y + r);
+    ctx.lineTo(x - r, y);
+    ctx.closePath();
+  } else {
+    // fallback to circle
+    ctx.arc(x, y, r, 0, Math.PI * 2);
+  }
+}
+
 /**
  * Main entry point. Given a canvas element and node/edge data from
  * /api/graph/nodes and /api/graph/god-nodes, starts the simulation.
  */
-function renderGraph(canvas, nodes, godNodes) {
+function renderGraph(canvas, nodes, godNodes, edges) {
+  // Stop any previous running simulation to avoid animation/handler leaks
+  if (typeof window.__engram_graph_stop === 'function') {
+    try { window.__engram_graph_stop(); } catch {}
+    window.__engram_graph_stop = null;
+  }
   const ctx = canvas.getContext("2d");
   const rect = canvas.getBoundingClientRect();
   canvas.width = rect.width * window.devicePixelRatio;
@@ -45,16 +87,269 @@ function renderGraph(canvas, nodes, godNodes) {
   // God node IDs (for emphasis). godNodes shape: [{node, degree}]
   const godIds = new Set((godNodes || []).map((g) => g.node?.id).filter(Boolean));
 
-  // Build simulation nodes with random starting positions near center
-  const sim = (nodes || []).slice(0, 300).map((n) => ({
-    id: n.id,
-    label: n.label || n.id,
-    kind: n.kind || "default",
-    isGod: godIds.has(n.id),
-    x: W / 2 + (Math.random() - 0.5) * 400,
-    y: H / 2 + (Math.random() - 0.5) * 400,
-    vx: 0, vy: 0,
-  }));
+  // Build simulation nodes with random starting positions near center.
+  // Default memoryScope to 'project' when missing so code files show as
+  // project-scope nodes by default.
+
+  // Build a map of nodes (include placeholders for any edge endpoints
+  // that the server didn't return). This ensures springs can be wired
+  // even when the node list is paginated or truncated.
+  const baseNodes = Array.isArray(nodes) ? nodes.slice() : [];
+  const nodeMapAll = new Map();
+  for (const n of baseNodes) nodeMapAll.set(n.id, n);
+
+  // Compute degree map from provided edges so we can bias placement
+  const degreeMap = new Map();
+  if (Array.isArray(edges)) {
+    for (const ed of edges) {
+      degreeMap.set(ed.source, (degreeMap.get(ed.source) || 0) + 1);
+      degreeMap.set(ed.target, (degreeMap.get(ed.target) || 0) + 1);
+      if (!nodeMapAll.has(ed.source)) {
+        nodeMapAll.set(ed.source, { id: ed.source, label: ed.source, kind: 'default', metadata: {} });
+      }
+      if (!nodeMapAll.has(ed.target)) {
+        nodeMapAll.set(ed.target, { id: ed.target, label: ed.target, kind: 'default', metadata: {} });
+      }
+    }
+  }
+
+  // Consolidation helper: choose a subset of nodes/edges to render that
+  // respects a global visual budget, scope distribution, and minority
+  // preservation.
+  function consolidateNodesAndEdges(allNodesArr, allEdgesArr, godIdsSet) {
+    const totalAvailable = allNodesArr.length;
+    const nodesBudget = Math.max(10, Math.floor(TOTAL_VISUAL_BUDGET * NODE_PROP));
+    const edgesBudget = Math.max(5, TOTAL_VISUAL_BUDGET - nodesBudget);
+
+    // If the data is already small, return fast
+    if (totalAvailable <= nodesBudget) {
+      const keptNodes = allNodesArr.slice();
+      const keptNodeIds = new Set(keptNodes.map(n => n.id));
+      let keptEdges = (Array.isArray(allEdgesArr) ? allEdgesArr.slice() : []).filter(e => keptNodeIds.has(e.source) && keptNodeIds.has(e.target));
+      // score & trim edges if needed
+      if (keptEdges.length > edgesBudget) {
+        keptEdges.sort((a, b) => edgeScore(b) - edgeScore(a));
+        keptEdges = keptEdges.slice(0, edgesBudget);
+      }
+      return { nodes: keptNodes, edges: keptEdges };
+    }
+
+    // Bucket nodes by memory scope
+    const buckets = { project: [], global: [], entity: [] };
+    for (const n of allNodesArr) {
+      try {
+        const meta = n.metadata || {};
+        const ms = (meta.memoryScope || meta.memory_scope) || 'project';
+        if (ms === 'global') buckets.global.push(n);
+        else if (ms === 'entity' || ms === 'personal') buckets.entity.push(n);
+        else buckets.project.push(n);
+      } catch {
+        buckets.project.push(n);
+      }
+    }
+
+    // initial allocation by configured ratios
+    const initialAlloc = {
+      project: Math.floor(nodesBudget * SCOPE_RATIOS.project),
+      global: Math.floor(nodesBudget * SCOPE_RATIOS.global),
+      entity: Math.floor(nodesBudget * SCOPE_RATIOS.entity),
+    };
+
+    const minMinorityCount = Math.max(1, Math.floor(totalAvailable * MINORITY_THRESHOLD));
+
+    const alloc = { project: 0, global: 0, entity: 0 };
+    for (const k of Object.keys(initialAlloc)) {
+      const avail = buckets[k].length;
+      if (avail <= initialAlloc[k] || avail <= minMinorityCount) {
+        alloc[k] = avail; // preserve small groups entirely
+      } else {
+        alloc[k] = initialAlloc[k];
+      }
+    }
+
+    // Redistribute any remaining budget to scopes that still need nodes
+    let remaining = nodesBudget - (alloc.project + alloc.global + alloc.entity);
+    while (remaining > 0) {
+      const needs = {
+        project: Math.max(0, buckets.project.length - alloc.project),
+        global: Math.max(0, buckets.global.length - alloc.global),
+        entity: Math.max(0, buckets.entity.length - alloc.entity),
+      };
+      const totalNeed = needs.project + needs.global + needs.entity;
+      if (totalNeed === 0) break;
+      let assigned = 0;
+      for (const k of ['project', 'global', 'entity']) {
+        if (needs[k] <= 0) continue;
+        const extra = Math.max(1, Math.floor(remaining * (needs[k] / totalNeed)));
+        const give = Math.min(extra, needs[k]);
+        alloc[k] += give;
+        assigned += give;
+      }
+      if (assigned === 0) {
+        // fallback: assign one-by-one round-robin
+        for (const k of ['project', 'global', 'entity']) {
+          if (alloc[k] < buckets[k].length && remaining > 0) { alloc[k]++; remaining--; }
+        }
+        break;
+      }
+      remaining -= assigned;
+    }
+
+    // Score function for nodes: prefer god nodes and higher degree
+    function nodeScore(n) {
+      const deg = degreeMap.get(n.id) || 0;
+      const godBoost = godIdsSet && godIdsSet.has(n.id) ? 2000 : 0;
+      return godBoost + deg;
+    }
+
+    // Pick top nodes per bucket by nodeScore
+    const keptNodes = [];
+    for (const k of ['project', 'global', 'entity']) {
+      const arr = buckets[k].slice();
+      arr.sort((a, b) => nodeScore(b) - nodeScore(a));
+      const take = Math.min(arr.length, alloc[k]);
+      for (let i = 0; i < take; i++) keptNodes.push(arr[i]);
+    }
+
+    // If we still have leftover slots (due to rounding), fill with highest-scoring remaining nodes
+    if (keptNodes.length < nodesBudget) {
+      const keptIds = new Set(keptNodes.map(n => n.id));
+      const rem = allNodesArr.filter(n => !keptIds.has(n.id));
+      rem.sort((a, b) => nodeScore(b) - nodeScore(a));
+      for (let i = 0; i < Math.min(rem.length, nodesBudget - keptNodes.length); i++) keptNodes.push(rem[i]);
+    }
+
+    const keptNodeIds = new Set(keptNodes.map(n => n.id));
+
+    // Edge score: prefer edges between high-degree nodes, god-involving edges, and keep minority-scope edges slightly boosted
+    function edgeScore(e) {
+      const sDeg = degreeMap.get(e.source) || 0;
+      const tDeg = degreeMap.get(e.target) || 0;
+      const godBoost = (godIdsSet && (godIdsSet.has(e.source) || godIdsSet.has(e.target))) ? 200 : 0;
+      let scopeBoost = 0;
+      try {
+        const sScope = (nodeMapAll.get(e.source) && ((nodeMapAll.get(e.source).metadata && (nodeMapAll.get(e.source).metadata.memoryScope || nodeMapAll.get(e.source).metadata.memory_scope)))) || 'project';
+        const tScope = (nodeMapAll.get(e.target) && ((nodeMapAll.get(e.target).metadata && (nodeMapAll.get(e.target).metadata.memoryScope || nodeMapAll.get(e.target).metadata.memory_scope)))) || 'project';
+        const total = allNodesArr.length || 1;
+        // If either endpoint belongs to a small/minority scope, slightly boost the edge
+        if ((sScope === 'global' && buckets.global.length / total < MINORITY_THRESHOLD) ||
+            (tScope === 'global' && buckets.global.length / total < MINORITY_THRESHOLD) ||
+            (sScope === 'entity' && buckets.entity.length / total < MINORITY_THRESHOLD) ||
+            (tScope === 'entity' && buckets.entity.length / total < MINORITY_THRESHOLD)) {
+          scopeBoost = 20;
+        }
+      } catch (ex) {}
+      return sDeg + tDeg + godBoost + scopeBoost;
+    }
+
+    // Collect candidate edges that connect kept nodes
+    let keptEdges = (Array.isArray(allEdgesArr) ? allEdgesArr.slice() : []).filter(e => keptNodeIds.has(e.source) && keptNodeIds.has(e.target));
+    if (keptEdges.length > edgesBudget) {
+      keptEdges.sort((a, b) => edgeScore(b) - edgeScore(a));
+      keptEdges = keptEdges.slice(0, edgesBudget);
+    }
+
+    return { nodes: keptNodes, edges: keptEdges };
+  }
+
+  // Use consolidation to produce the simulated subset (this keeps layout responsive)
+  const combined = consolidateNodesAndEdges(Array.from(nodeMapAll.values()), Array.isArray(edges) ? edges : [], godIds);
+  const candidateNodes = combined.nodes.slice(0, 600); // safety cap for layout
+
+  // Cluster by project when multiple projectRoots are present (useful
+  // for the 'global' memory-scope view where nodes come from many projects).
+  const projectBuckets = new Map();
+  for (const n of candidateNodes) {
+    try {
+      const root = (n.metadata && (n.metadata.projectRoot || n.metadata.project_root)) || "__no_project__";
+      const arr = projectBuckets.get(root) || [];
+      arr.push(n);
+      projectBuckets.set(root, arr);
+    } catch {
+      const arr = projectBuckets.get("__no_project__") || [];
+      arr.push(n);
+      projectBuckets.set("__no_project__", arr);
+    }
+  }
+
+  let sim = [];
+  if (projectBuckets.size > 1) {
+    // Place each project's cluster around a ring and distribute nodes
+    // in that project's local neighborhood. Use the project's god node
+    // as the cluster center when available.
+    const roots = Array.from(projectBuckets.keys());
+    const clusterRingRadius = Math.min(W, H) * 0.35;
+
+    // Map god node id by projectRoot so we can center clusters on them
+    const godByProject = new Map();
+    (godNodes || []).forEach((g) => {
+      try {
+        const pr = (g.node && (g.node.metadata && (g.node.metadata.projectRoot || g.node.metadata.project_root))) || "__no_project__";
+        if (g.node && g.node.id) godByProject.set(pr, g.node.id);
+      } catch {}
+    });
+
+    for (let i = 0; i < roots.length; i++) {
+      const root = roots[i];
+      const nodesInCluster = projectBuckets.get(root) || [];
+      const clusterAngle = (i / roots.length) * Math.PI * 2;
+      const cx = W / 2 + Math.cos(clusterAngle) * clusterRingRadius;
+      const cy = H / 2 + Math.sin(clusterAngle) * clusterRingRadius;
+      // Sort by degree so hubs are placed closer to center
+      nodesInCluster.sort((a, b) => (degreeMap.get(b.id) || 0) - (degreeMap.get(a.id) || 0));
+      const godIdForProject = godByProject.get(root);
+      for (let j = 0; j < nodesInCluster.length; j++) {
+        const n = nodesInCluster[j];
+        const deg = degreeMap.get(n.id) || 0;
+        const weight = Math.min(1, deg / Math.max(1, (Array.from(degreeMap.values()).reduce((s, v) => s + v, 0) / Math.max(1, degreeMap.size))));
+        let x, y;
+        if (godIdForProject && n.id === godIdForProject) {
+          // Place god node at cluster center
+          x = cx;
+          y = cy;
+        } else {
+          const localR = Math.max(10, (1 - weight) * 120 * (0.4 + Math.random() * 0.8));
+          const ang = Math.random() * Math.PI * 2;
+          x = cx + Math.cos(ang) * localR + (Math.random() - 0.5) * 8;
+          y = cy + Math.sin(ang) * localR + (Math.random() - 0.5) * 8;
+        }
+        sim.push({
+          id: n.id,
+          label: n.label || n.id,
+          kind: n.kind || "default",
+          memoryScope: (n.metadata && (n.metadata.memoryScope || n.metadata.memory_scope)) || "project",
+          isGod: godIds.has(n.id),
+          x: Math.max(20, Math.min(W - 20, x)),
+          y: Math.max(20, Math.min(H - 20, y)),
+          vx: 0, vy: 0,
+        });
+      }
+    }
+  } else {
+    sim = candidateNodes.map((n, idx) => {
+      const deg = degreeMap.get(n.id) || 0;
+      // pick an angle and radius biased by degree
+      const angle = (idx / Math.max(1, candidateNodes.length)) * Math.PI * 2 + (Math.random() - 0.5) * 0.4;
+      const avgDeg = degreeMap.size > 0 ? (Array.from(degreeMap.values()).reduce((s, v) => s + v, 0) / degreeMap.size) : 1;
+      const weight = Math.min(1, deg / Math.max(1, avgDeg));
+      // nodes with higher degree sit closer to center
+      const radiusOuter = Math.min(W, H) * 0.45;
+      const radiusInner = Math.min(W, H) * 0.08;
+      const r = radiusInner + (1 - weight) * (radiusOuter - radiusInner) * (0.25 + Math.random() * 0.75);
+      const x = W / 2 + Math.cos(angle) * r + (Math.random() - 0.5) * 20;
+      const y = H / 2 + Math.sin(angle) * r + (Math.random() - 0.5) * 20;
+      return {
+        id: n.id,
+        label: n.label || n.id,
+        kind: n.kind || "default",
+        memoryScope: (n.metadata && (n.metadata.memoryScope || n.metadata.memory_scope)) || "project",
+        isGod: godIds.has(n.id),
+        x: Math.max(20, Math.min(W - 20, x)),
+        y: Math.max(20, Math.min(H - 20, y)),
+        vx: 0, vy: 0,
+      };
+    });
+  }
 
   if (sim.length === 0) {
     ctx.fillStyle = "#71717a";
@@ -64,49 +359,166 @@ function renderGraph(canvas, nodes, godNodes) {
     return;
   }
 
+  // Build a quick id->node map for edge wiring
+  const nodeById = new Map(sim.map((n) => [n.id, n]));
+  const springs = [];
+  if (Array.isArray(edges)) {
+    for (const e of edges) {
+      const a = nodeById.get(e.source);
+      const b = nodeById.get(e.target);
+      if (a && b) springs.push({ a, b, relation: e.relation });
+    }
+  }
+
+  // Expose visible nodes/edges so other UI pieces (legend) can summarize
+  try {
+    window.__engram_graph_visibleNodes = sim.map(n => n.id);
+    window.__engram_graph_visibleEdges = springs.map(s => ({ source: s.a.id, target: s.b.id, relation: s.relation }));
+  } catch (e) {}
+
   // Viewport transform (pan + zoom)
   let viewX = 0, viewY = 0, zoom = 1;
   let draggingView = false, dragStartX = 0, dragStartY = 0;
   let selectedId = null;
+  let selectedEdge = null;
+  let lastMouseX = null, lastMouseY = null;
 
-  // ─── Physics step ────────────────────────────────────────────
-  const REPULSION = 1200;
-  const SPRING_K = 0.02;
-  const SPRING_LENGTH = 80;
-  const DAMPING = 0.85;
+  // ─── Physics step (tuned to settle faster and avoid long oscillations) ───
+  // REPULSION scales down for large graphs (so springs can pull clusters together)
+  const REPULSION = Math.max(75, Math.floor(900 * Math.min(1, 300 / Math.max(1, sim.length))));
+  // Stronger spring constant to favor edge clustering over global repulsion
+  const SPRING_K = 0.22;
+  // Spring length tuned by viewport size (keeps connected nodes reasonably close)
+  const SPRING_LENGTH = Math.max(40, Math.min(100, Math.floor(Math.sqrt(W * H) / 8)));
+  const DAMPING = 0.90;
   const CENTER_GRAVITY = 0.003;
+  const MAX_SPEED = 12;
 
   function step() {
-    // Pairwise repulsion (O(n^2) but fine up to ~500 nodes)
-    for (let i = 0; i < sim.length; i++) {
-      const a = sim[i];
-      for (let j = i + 1; j < sim.length; j++) {
-        const b = sim[j];
-        const dx = b.x - a.x;
-        const dy = b.y - a.y;
-        const dist2 = dx * dx + dy * dy + 1;
-        const force = REPULSION / dist2;
-        const dist = Math.sqrt(dist2);
-        const fx = (dx / dist) * force;
-        const fy = (dy / dist) * force;
-        a.vx -= fx; a.vy -= fy;
-        b.vx += fx; b.vy += fy;
-      }
-    }
-
-    // Gravity toward viewport center — keeps disconnected components visible
+    // Large graphs: approximate pairwise repulsion using spatial hashing
+    // (grid buckets). This reduces O(n^2) to near-linear by only checking
+    // nearby cells. For small graphs we keep exact pairwise repulsion.
+    let maxSpeed = 0;
+    const N = sim.length;
+    if (N > 400) {
+      const cellSize = SPRING_LENGTH * 1.5;
+      const buckets = new Map();
+      const nodeIndex = new Map();
+      for (let i = 0; i < N; i++) {
+        const n = sim[i];
+        nodeIndex.set(n.id, i);
+        const cx = Math.floor(n.x / cellSize);
+        const cy = Math.floor(n.y / cellSize);
+        const key = cx + ',' + cy;
+        const arr = buckets.get(key) || [];
+        arr.push(n);
+        buckets.set(key, arr);
+      }
+
+      for (let i = 0; i < N; i++) {
+        const a = sim[i];
+        const acx = Math.floor(a.x / cellSize);
+        const acy = Math.floor(a.y / cellSize);
+        for (let dx = -1; dx <= 1; dx++) {
+          for (let dy = -1; dy <= 1; dy++) {
+            const key = (acx + dx) + ',' + (acy + dy);
+            const arr = buckets.get(key);
+            if (!arr) continue;
+            for (const b of arr) {
+              const j = nodeIndex.get(b.id);
+              if (j <= i) continue; // symmetric update only once
+              const dx_ = b.x - a.x;
+              const dy_ = b.y - a.y;
+              const dist2 = dx_ * dx_ + dy_ * dy_ + 0.01;
+              const force = REPULSION / dist2;
+              const dist = Math.sqrt(dist2);
+              const fx = (dx_ / dist) * force;
+              const fy = (dy_ / dist) * force;
+              a.vx -= fx; a.vy -= fy;
+              b.vx += fx; b.vy += fy;
+            }
+          }
+        }
+      }
+    } else {
+      // Exact pairwise repulsion
+      for (let i = 0; i < sim.length; i++) {
+        const a = sim[i];
+        for (let j = i + 1; j < sim.length; j++) {
+          const b = sim[j];
+          const dx = b.x - a.x;
+          const dy = b.y - a.y;
+          const dist2 = dx * dx + dy * dy + 0.01;
+          const force = REPULSION / dist2;
+          const dist = Math.sqrt(dist2);
+          const fx = (dx / dist) * force;
+          const fy = (dy / dist) * force;
+          a.vx -= fx; a.vy -= fy;
+          b.vx += fx; b.vy += fy;
+        }
+      }
+    }
+
+    // Spring attraction along edges
+    for (const s of springs) {
+      const a = s.a;
+      const b = s.b;
+      const dx = b.x - a.x;
+      const dy = b.y - a.y;
+      const dist = Math.sqrt(dx * dx + dy * dy) || 1;
+      const target = SPRING_LENGTH;
+      const f = SPRING_K * (dist - target);
+      const fx = (dx / dist) * f;
+      const fy = (dy / dist) * f;
+      a.vx += fx; a.vy += fy;
+      b.vx -= fx; b.vy -= fy;
+    }
+
+    // Gravity toward viewport center — keeps components visible
     for (const n of sim) {
       n.vx += (W / 2 - n.x) * CENTER_GRAVITY;
       n.vy += (H / 2 - n.y) * CENTER_GRAVITY;
     }
 
-    // Apply velocity with damping
+    // Apply damping, clamp velocities, and update positions
     for (const n of sim) {
       n.vx *= DAMPING;
       n.vy *= DAMPING;
+
+      // Clamp speeds to avoid large oscillations
+      if (n.vx > MAX_SPEED) n.vx = MAX_SPEED;
+      if (n.vx < -MAX_SPEED) n.vx = -MAX_SPEED;
+      if (n.vy > MAX_SPEED) n.vy = MAX_SPEED;
+      if (n.vy < -MAX_SPEED) n.vy = -MAX_SPEED;
+
       n.x += n.vx;
       n.y += n.vy;
+
+      // Keep nodes roughly within viewport bounds to avoid runaway
+      const pad = 50;
+      n.x = Math.max(-pad, Math.min(W + pad, n.x));
+      n.y = Math.max(-pad, Math.min(H + pad, n.y));
+
+      const speed = Math.sqrt(n.vx * n.vx + n.vy * n.vy);
+      if (speed > maxSpeed) maxSpeed = speed;
     }
+
+    return maxSpeed;
+  }
+
+  // Pre-relaxation: run a short synchronous settle pass to reduce visible bouncing.
+  // Stop early when velocities have settled to a low threshold. Cap iterations
+  // to avoid excessive blocking on huge graphs. For very dense graphs we use
+  // more iterations to let springs pull clusters together.
+  try {
+    const base = Math.floor(80000 / Math.max(1, sim.length));
+    const maxIters = Math.min(2000, Math.max(120, base));
+    for (let i = 0; i < maxIters; i++) {
+      const maxSpeed = step();
+      if (maxSpeed < 0.02 && i > 20) break;
+    }
+  } catch (e) {
+    // If the browser is very constrained, skip pre-relax and continue
   }
 
   // ─── Render ─────────────────────────────────────────────────
@@ -116,15 +528,44 @@ function renderGraph(canvas, nodes, godNodes) {
     ctx.translate(viewX, viewY);
     ctx.scale(zoom, zoom);
 
+    // Draw edges (lines) first
+    const RELATION_STYLES = {
+      contains: { color: '#9CA3AF', width: 1, dash: [] },
+      imports: { color: '#60A5FA', width: 1, dash: [6,4] },
+      similar_to: { color: '#FBBF24', width: 1, dash: [2,4] },
+      depends_on: { color: '#10B981', width: 1.25, dash: [] },
+      triggered_by: { color: '#A78BFA', width: 1, dash: [4,3] },
+      rationale_for: { color: '#EF4444', width: 1, dash: [2,2] },
+      default: { color: '#6B7280', width: 0.9, dash: [] },
+    };
+
+    for (const s of springs) {
+      const a = s.a;
+      const b = s.b;
+      const style = RELATION_STYLES[s.relation] || RELATION_STYLES.default;
+      ctx.beginPath();
+      if (style.dash && ctx.setLineDash) ctx.setLineDash(style.dash);
+      ctx.moveTo(a.x, a.y);
+      ctx.lineTo(b.x, b.y);
+      ctx.strokeStyle = style.color;
+      // Ensure edge stroke is visible even when zoomed out
+      ctx.lineWidth = Math.max(0.8, style.width) / Math.max(zoom, 0.5);
+      ctx.globalAlpha = 0.95;
+      ctx.stroke();
+      if (ctx.setLineDash) ctx.setLineDash([]);
+    }
+
     // Draw nodes
     for (const n of sim) {
       const radius = n.isGod ? 7 : 4;
-      const color = NODE_COLORS[n.kind] || NODE_COLORS.default;
+      const scopeCfg = MEMORY_SCOPE_CONFIG[n.memoryScope] || MEMORY_SCOPE_CONFIG.default;
+      const color = scopeCfg.color || NODE_COLORS[n.kind] || NODE_COLORS.default;
+      const shape = scopeCfg.shape || "circle";
 
-      ctx.beginPath();
-      ctx.arc(n.x, n.y, radius, 0, Math.PI * 2);
+      // Draw shape path
+      pathShape(ctx, n.x, n.y, radius, shape);
       ctx.fillStyle = color;
-      ctx.globalAlpha = n.id === selectedId ? 1.0 : (n.isGod ? 0.95 : 0.75);
+      ctx.globalAlpha = n.id === selectedId ? 1.0 : (n.isGod ? 0.95 : 0.85);
       ctx.fill();
 
       if (n.id === selectedId) {
@@ -155,6 +596,10 @@ function renderGraph(canvas, nodes, godNodes) {
   let frames = 0;
   let running = true;
 
+  // Expose a stop handle so subsequent renders can cleanly terminate
+  const stop = () => { running = false; };
+  window.__engram_graph_stop = stop;
+
   function tick() {
     if (!running) return;
     if (frames < 300) step();  // run physics until settled
@@ -164,7 +609,7 @@ function renderGraph(canvas, nodes, godNodes) {
   }
   tick();
 
-  // ─── Interaction: pan ───────────────────────────────────────
+  // ─── Interaction: pan + selection ───────────────────────────────────────
   canvas.addEventListener("mousedown", (e) => {
     const x = e.offsetX;
     const y = e.offsetY;
@@ -172,31 +617,66 @@ function renderGraph(canvas, nodes, godNodes) {
     // Hit test for node click (world coords)
     const worldX = (x - viewX) / zoom;
     const worldY = (y - viewY) / zoom;
-    let clicked = null;
+    let clickedNode = null;
     for (const n of sim) {
       const dx = n.x - worldX;
       const dy = n.y - worldY;
       const radius = n.isGod ? 7 : 4;
       if (dx * dx + dy * dy < (radius + 3) * (radius + 3)) {
-        clicked = n;
+        clickedNode = n;
         break;
       }
     }
 
-    if (clicked) {
-      selectedId = clicked.id;
+    if (clickedNode) {
+      selectedId = clickedNode.id;
+      selectedEdge = null;
       const info = document.getElementById("graph-info");
       if (info) {
-        info.textContent = clicked.kind + " · " + clicked.label + (clicked.isGod ? " (god node)" : "");
+        info.textContent = clickedNode.kind + " · " + clickedNode.label + (clickedNode.isGod ? " (god node)" : "");
       }
     } else {
-      draggingView = true;
-      dragStartX = x - viewX;
-      dragStartY = y - viewY;
+      // If no node clicked, attempt an edge hit-test (pick the nearest segment)
+      let clickedEdge = null;
+      let bestDist = Infinity;
+      for (const s of springs) {
+        // distance from point to segment AB
+        const ax = s.a.x, ay = s.a.y, bx = s.b.x, by = s.b.y;
+        const px = worldX, py = worldY;
+        const dx = bx - ax, dy = by - ay;
+        const l2 = dx * dx + dy * dy;
+        let t = 0;
+        if (l2 > 0) t = ((px - ax) * dx + (py - ay) * dy) / l2;
+        t = Math.max(0, Math.min(1, t));
+        const projx = ax + t * dx, projy = ay + t * dy;
+        const dist2 = (projx - px) * (projx - px) + (projy - py) * (projy - py);
+        if (dist2 < bestDist) {
+          bestDist = dist2;
+          clickedEdge = s;
+        }
+      }
+      // threshold in world coords (approx)
+      if (clickedEdge && bestDist < (12 * 12)) {
+        selectedEdge = clickedEdge;
+        selectedId = null;
+        const info = document.getElementById("graph-info");
+        if (info) {
+          info.textContent = (selectedEdge.relation || 'edge') + ' · ' + selectedEdge.a.label + ' ↔ ' + selectedEdge.b.label;
+        }
+      } else {
+        // Start panning
+        draggingView = true;
+        dragStartX = x - viewX;
+        dragStartY = y - viewY;
+        selectedId = null;
+        selectedEdge = null;
+      }
     }
   });
 
   canvas.addEventListener("mousemove", (e) => {
+    lastMouseX = e.offsetX;
+    lastMouseY = e.offsetY;
     if (draggingView) {
       viewX = e.offsetX - dragStartX;
       viewY = e.offsetY - dragStartY;
@@ -206,7 +686,7 @@ function renderGraph(canvas, nodes, godNodes) {
   canvas.addEventListener("mouseup", () => { draggingView = false; });
   canvas.addEventListener("mouseleave", () => { draggingView = false; });
 
-  // ─── Interaction: zoom ──────────────────────────────────────
+  // ─── Interaction: zoom (wheel + keyboard) ──────────────────────────────────────
   canvas.addEventListener("wheel", (e) => {
     e.preventDefault();
     const zoomDelta = e.deltaY > 0 ? 0.9 : 1.1;
@@ -219,6 +699,52 @@ function renderGraph(canvas, nodes, godNodes) {
     viewY = my - ((my - viewY) * newZoom) / zoom;
     zoom = newZoom;
   }, { passive: false });
+
+  // Keyboard zoom: - / = keys. Center on selected node/edge if any, else on
+  // the last mouse cursor position.
+  function keyboardZoom(zoomDelta) {
+    const newZoom = Math.max(0.2, Math.min(3, zoom * zoomDelta));
+    if (selectedId) {
+      const n = nodeById.get(selectedId);
+      if (n) {
+        // center selected node in viewport at newZoom
+        viewX = (W / 2) - (n.x * newZoom);
+        viewY = (H / 2) - (n.y * newZoom);
+        zoom = newZoom;
+        return;
+      }
+    }
+    if (selectedEdge) {
+      const a = selectedEdge.a, b = selectedEdge.b;
+      const cx = (a.x + b.x) / 2;
+      const cy = (a.y + b.y) / 2;
+      viewX = (W / 2) - (cx * newZoom);
+      viewY = (H / 2) - (cy * newZoom);
+      zoom = newZoom;
+      return;
+    }
+    // Anchor on mouse cursor screen coords if available
+    if (lastMouseX != null && lastMouseY != null) {
+      const mx = lastMouseX;
+      const my = lastMouseY;
+      viewX = mx - ((mx - viewX) * newZoom) / zoom;
+      viewY = my - ((my - viewY) * newZoom) / zoom;
+      zoom = newZoom;
+      return;
+    }
+    // fallback: center viewport
+    viewX = (W / 2) - ((W / 2 - viewX) * newZoom) / zoom;
+    viewY = (H / 2) - ((H / 2 - viewY) * newZoom) / zoom;
+    zoom = newZoom;
+  }
+
+  window.addEventListener('keydown', (ev) => {
+    if (ev.key === '-' || ev.key === '_') {
+      keyboardZoom(0.9);
+    } else if (ev.key === '=' || ev.key === '+' ) {
+      keyboardZoom(1.1);
+    }
+  });
 }
 `;
 }
diff --git a/src/server/ui.ts b/src/server/ui.ts
index c5d3700..58364bc 100644
--- a/src/server/ui.ts
+++ b/src/server/ui.ts
@@ -1,4 +1,4 @@
-/**
+/*
  * engram Web Dashboard — served at GET /ui by the HTTP server.
  *
  * Zero external dependencies. HTML, CSS, and JS are template literals
@@ -51,6 +51,7 @@ body {
 }
 
 header {
+  position: relative;
   display: flex;
   align-items: center;
   justify-content: space-between;
@@ -71,6 +72,27 @@ header .brand {
 header .brand .diamond { color: var(--accent); font-size: 18px; }
 header .brand .version { color: var(--text-dim); font-size: 12px; font-weight: 400; }
 
+/* Centered scope/project selector */
+header .center {
+  position: absolute;
+  left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+header .center select {
+  background: var(--bg-panel);
+  color: var(--text);
+  border: 1px solid var(--border);
+  padding: 6px 10px;
+  border-radius: 6px;
+  font-family: var(--mono);
+  font-size: 12px;
+  min-width: 320px;
+  max-width: 520px;
+}
+
 header .status {
   display: flex; align-items: center; gap: 16px;
   font-family: var(--mono); font-size: 12px; color: var(--text-dim);
@@ -213,6 +235,31 @@ td.dim { color: var(--text-dim); }
 }
 
 #graph-canvas:active { cursor: grabbing; }
+
+/* Toast notifications */
+.toast {
+  position: fixed;
+  bottom: 24px;
+  right: 24px;
+  background: var(--bg-panel);
+  border: 1px solid var(--border);
+  padding: 10px 14px;
+  border-radius: 8px;
+  color: var(--text);
+  font-family: var(--mono);
+  font-size: 13px;
+  box-shadow: 0 8px 24px rgba(0,0,0,0.6);
+  opacity: 0; transform: translateY(8px);
+  transition: opacity .18s ease, transform .18s ease;
+  z-index: 9999;
+}
+.toast.show { opacity: 1; transform: translateY(0); }
+
+/* Small refresh button used next to tokens */
+.refresh-btn { background: none; border: none; color: var(--text-dim); cursor: pointer; font-family: var(--mono); font-size: 12px; padding: 2px 6px; border-radius: 4px; margin-left: 8px; }
+.refresh-btn:hover { color: var(--text); background: var(--bg-hover); }
+
+.ov-chart { margin-top: 12px; height: 120px; }
 `;
 
 const HTML_HEAD = `<!DOCTYPE html>
@@ -234,6 +281,11 @@ const HTML_BODY = `
       <span>engram</span>
       <span class="version" id="version">loading...</span>
     </div>
+    <div class="center">
+      <select id="scope-select" aria-label="Memory scope">
+        <option>Loading…</option>
+      </select>
+    </div>
     <div class="status">
       <span><span class="dot"></span>connected</span>
       <span id="uptime">&mdash;</span>
@@ -252,7 +304,7 @@ const HTML_BODY = `
   <main>
     <section class="tab active" id="tab-overview">
       <div class="grid grid-4">
-        <div class="card"><h3>Tokens Saved</h3><div class="big-number accent" id="ov-tokens">&mdash;</div><div class="subtext" id="ov-tokens-sub">cumulative</div></div>
+        <div class="card"><h3>Tokens Saved <button id="tokens-refresh" class="refresh-btn" title="Refresh tokens">⟳</button></h3><div class="big-number accent" id="ov-tokens">&mdash;</div><div class="subtext" id="ov-tokens-sub">cumulative</div><div id="ov-tokens-chart" class="ov-chart"></div></div>
         <div class="card"><h3>Cost Saved</h3><div class="big-number" id="ov-cost">&mdash;</div><div class="subtext">at $3/M tokens</div></div>
         <div class="card"><h3>Hit Rate</h3><div class="big-number" id="ov-hitrate">&mdash;</div><div class="subtext" id="ov-hitrate-sub">hook interceptions</div></div>
         <div class="card"><h3>Sessions</h3><div class="big-number" id="ov-sessions">&mdash;</div><div class="subtext">tracked</div></div>
@@ -293,6 +345,7 @@ const HTML_BODY = `
         <h2>Knowledge Graph Visualization</h2>
         <div class="subtext" style="margin-bottom: 12px;">Drag to pan &middot; Scroll to zoom &middot; Click nodes for details</div>
         <canvas id="graph-canvas"></canvas>
+        <div id="graph-legend" class="subtext" style="margin-top: 12px; display:flex; justify-content:center; gap:16px; align-items:center; flex-wrap:wrap; padding:6px 8px;"></div>
         <div id="graph-info" class="subtext" style="margin-top: 10px;"></div>
       </div>
     </section>
@@ -356,6 +409,24 @@ async function api(path) {
   } catch { return null; }
 }
 
+async function scopedApi(path) {
+  try {
+    const sel = document.getElementById('scope-select');
+    let query = '';
+    if (sel && sel.value) {
+      const val = sel.value;
+      if (val.startsWith('proj:')) {
+        const pid = val.slice(5);
+        query = (path.includes('?') ? '&' : '?') + 'projectId=' + encodeURIComponent(pid);
+      } else if (val.startsWith('scope:')) {
+        const scopeId = val.slice(6);
+        query = (path.includes('?') ? '&' : '?') + 'scope=' + encodeURIComponent(scopeId);
+      }
+    }
+    return await api(path + query);
+  } catch { return null; }
+}
+
 function formatNumber(n) {
   if (n === null || n === undefined) return "—";
   if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + "M";
@@ -375,19 +446,87 @@ function formatUptime(seconds) {
   return Math.floor(seconds / 3600) + "h " + Math.floor((seconds % 3600) / 60) + "m";
 }
 
+// small UI helpers: toast
+function showToast(msg, duration = 3000) {
+  try {
+    const t = document.createElement('div');
+    t.className = 'toast';
+    t.textContent = msg;
+    document.body.appendChild(t);
+    // allow CSS transition
+    setTimeout(() => t.classList.add('show'), 20);
+    setTimeout(() => { t.classList.remove('show'); setTimeout(() => t.remove(), 220); }, duration);
+  } catch (e) {
+    console.warn('toast failed', e);
+  }
+}
+
 // ─── Components library (SVG charts — data-agnostic) ──────────
 __COMPONENTS__
 
 // ─── Graph canvas module ──────────────────────────────────────
 __GRAPH__
 
+// ─── Scopes / Projects selector ───────────────────────────────
+async function loadScopes() {
+  const data = await api('/api/scopes');
+  const sel = document.getElementById('scope-select');
+  if (!sel) return;
+  sel.innerHTML = '';
+  try {
+    if (data && data.scopes && Array.isArray(data.scopes)) {
+      for (const s of data.scopes) {
+        const opt = document.createElement('option');
+        opt.value = 'scope:' + s.id;
+        opt.textContent = s.label;
+        sel.appendChild(opt);
+      }
+    }
+    if (data && data.projects && Array.isArray(data.projects)) {
+      // Insert a disabled divider option for visual separation (selects can't render true separators reliably)
+      if (data.projects.length > 0) {
+        const divider = document.createElement('option');
+        divider.textContent = '--- Projects ---';
+        divider.disabled = true;
+        sel.appendChild(divider);
+      }
+      for (const p of data.projects) {
+        const opt = document.createElement('option');
+        opt.value = 'proj:' + p.id;
+        const name = (p.name || p.root || '').toString();
+        opt.textContent = name.length > 40 ? name.slice(0, 40) : name;
+        sel.appendChild(opt);
+      }
+    }
+  } catch (e) {
+    // best-effort — leave the select as-is
+  }
+
+  // Default: if there's at least one project, select the first project
+  if (sel.options.length > 0) {
+    // If the first option is a scope entry, that's fine; otherwise choose the first project entry
+    sel.selectedIndex = 0;
+  }
+
+  sel.addEventListener('change', () => {
+    // refresh active tab(s)
+    loadOverview();
+    if (document.querySelector('.tab-btn[data-tab="graph"].active')) loadGraph();
+    if (document.querySelector('.tab-btn[data-tab="sessions"].active')) loadSessions();
+    if (document.querySelector('.tab-btn[data-tab="files"].active')) loadFiles();
+    if (document.querySelector('.tab-btn[data-tab="providers"].active')) loadProviders();
+    if (document.querySelector('.tab-btn[data-tab="activity"].active')) loadActivity();
+    showToast('View updated', 1200);
+  });
+}
+
 // ─── Tab: Overview ────────────────────────────────────────────
 async function loadOverview() {
   const [tokens, summary, cache, graphStats, health] = await Promise.all([
-    api("/api/tokens"),
-    api("/api/hook-log/summary"),
-    api("/api/cache/stats"),
-    api("/stats"),
+    scopedApi("/api/tokens"),
+    scopedApi("/api/hook-log/summary"),
+    scopedApi("/api/cache/stats"),
+    scopedApi("/stats"),
     api("/health"),
   ]);
 
@@ -396,6 +535,16 @@ async function loadOverview() {
     setText("ov-cost", formatCost(tokens.totalSaved ?? 0));
     setText("ov-sessions", formatNumber(tokens.totalSessions ?? 0));
     setText("ov-tokens-sub", (Number(tokens.avgReduction ?? 0).toFixed(1) + "%") + " avg reduction");
+
+    // Render time-series if available
+    const chartEl = document.getElementById('ov-tokens-chart');
+    if (chartEl) {
+      if (tokens.sessions && Array.isArray(tokens.sessions) && tokens.sessions.length > 0) {
+        chartEl.innerHTML = renderTokenTimeSeries(tokens.sessions.slice(-200));
+      } else {
+        chartEl.innerHTML = '<div class="empty-state">No session history yet</div>';
+      }
+    }
   }
 
   if (summary) {
@@ -428,9 +577,43 @@ async function loadOverview() {
   }
 }
 
+// Render a small dual-line time-series showing naive vs graph tokens
+function renderTokenTimeSeries(sessions) {
+  try {
+    if (!sessions || sessions.length === 0) return '<div class="empty-state">No session data yet</div>';
+    const last = sessions.slice(-50);
+    const width = 800; const height = 120; const pad = 12;
+    const naive = last.map((s) => Number(s.naiveTokens || 0));
+    const graph = last.map((s) => Number(s.graphTokens || 0));
+    const maxVal = Math.max(1, ...naive, ...graph);
+    const innerW = width - pad * 2; const innerH = height - pad * 2;
+    const step = last.length === 1 ? 0 : innerW / (last.length - 1);
+
+    const points = (arr) => arr.map((v, i) => [pad + i * step, pad + innerH - (v / maxVal) * innerH]);
+    const np = points(naive); const gp = points(graph);
+    const pathD = (pts) => pts.length === 1 ? ('M' + pts[0][0] + ' ' + pts[0][1] + ' l 0 0') : ('M' + pts.map((p) => p[0].toFixed(1) + ' ' + p[1].toFixed(1)).join(' L '));
+    const naivePath = pathD(np); const graphPath = pathD(gp);
+
+    // Area between naive and graph (saved) if naive >= graph
+    let areaD = '';
+    if (np.length > 1) {
+      const areaPts = np.concat(gp.slice().reverse());
+      areaD = 'M' + areaPts.map((p) => p[0].toFixed(1) + ' ' + p[1].toFixed(1)).join(' L ') + ' Z';
+    }
+
+    return '<svg viewBox="0 0 ' + width + ' ' + height + '" width="100%">' +
+      (areaD ? ('<defs><linearGradient id="gSaved" x1="0" x2="0" y1="0" y2="1"><stop offset="0" stop-color="' + COLOR_ACCENT + '" stop-opacity="0.12"/><stop offset="1" stop-color="' + COLOR_ACCENT + '" stop-opacity="0"/></linearGradient></defs><path d="' + areaD + '" fill="url(#gSaved)"/>') : '') +
+      ('<path d="' + naivePath + '" stroke="' + COLOR_DIM + '" stroke-width="1.5" fill="none" stroke-linecap="round" stroke-linejoin="round" />') +
+      ('<path d="' + graphPath + '" stroke="' + COLOR_ACCENT + '" stroke-width="2" fill="none" stroke-linecap="round" stroke-linejoin="round" />') +
+      '</svg>';
+  } catch (e) {
+    return '<div class="empty-state">Chart failed</div>';
+  }
+}
+
 // ─── Tab: Sessions ────────────────────────────────────────────
 async function loadSessions() {
-  const tokens = await api("/api/tokens");
+  const tokens = await scopedApi("/api/tokens");
   if (!tokens) return;
 
   const sparkline = document.getElementById("sessions-sparkline");
@@ -457,11 +640,61 @@ async function loadSessions() {
 
 // ─── Tab: Activity (live via SSE) ─────────────────────────────
 let sseSource = null;
+let ssePending = false;
 
-async function loadActivity() {
-  if (sseSource) return;
+async function refreshGraph() {
+  const [nodes, godNodes] = await Promise.all([
+    scopedApi("/api/graph/nodes?limit=300"),
+    scopedApi("/api/graph/god-nodes"),
+  ]);
+  if (!nodes) return;
+  const canvas = document.getElementById("graph-canvas");
+  if (!canvas) return;
+  // Replace canvas element so we don't accumulate event listeners/animation loops
+  const fresh = canvas.cloneNode(true);
+  canvas.parentNode.replaceChild(fresh, canvas);
+  const nodeList = nodes.nodes ?? [];
+  // Fetch edges for the current node set in manageable chunks (best-effort).
+  // Some browsers/servers limit URL length, so request edges in chunks of up
+  // to 400 ids and concatenate results.
+  let edges = [];
+  try {
+    const CHUNK = 400;
+    for (let i = 0; i < nodeList.length; i += CHUNK) {
+      const chunk = nodeList.slice(i, i + CHUNK).map((n) => n.id).join(",");
+      const eResp = await scopedApi("/api/graph/edges?ids=" + encodeURIComponent(chunk));
+      if (eResp && Array.isArray(eResp.edges)) edges = edges.concat(eResp.edges);
+    }
+  } catch (e) {
+    edges = [];
+  }
 
-  const log = await api("/api/hook-log?limit=20");
+  // Augment nodeList with placeholder nodes for any edge endpoints that
+  // weren't included in the initial node fetch. This ensures edges can be
+  // rendered even when the server's nodes list is paginated/truncated.
+  try {
+    const nodeById = new Map(nodeList.map((n) => [n.id, n]));
+    const missingIds = new Set();
+    for (const ed of edges) {
+      if (!nodeById.has(ed.source)) missingIds.add(ed.source);
+      if (!nodeById.has(ed.target)) missingIds.add(ed.target);
+    }
+    for (const mid of missingIds) {
+      // create a lightweight placeholder
+      const p = { id: mid, label: mid, kind: 'default', metadata: { }, sourceFile: '', sourceLocation: null };
+      nodeList.push(p);
+    }
+  } catch (e) {
+    // ignore augmentation failures — fall back to drawing whatever we have
+  }
+
+  renderGraph(fresh, nodeList, godNodes ?? [], edges);
+  renderMemoryLegend(nodeList, edges, nodes.total ?? null);
+  setText("graph-info", (nodeList.length ?? 0) + " nodes, " + (edges.length ?? 0) + " edges — " + (nodes.total ?? 0) + " total");
+}
+
+async function loadActivity() {
+  const log = await scopedApi("/api/hook-log?limit=20");
   const streamEl = document.getElementById("activity-stream");
   if (streamEl) {
     if (log && log.entries && log.entries.length > 0) {
@@ -471,22 +704,58 @@ async function loadActivity() {
     }
   }
 
-  const summary = await api("/api/hook-log/summary");
+  const summary = await scopedApi("/api/hook-log/summary");
   const toolsEl = document.getElementById("activity-tools");
   if (toolsEl) {
     toolsEl.innerHTML = renderToolBreakdown((summary && summary.byTool) || {});
   }
 
+  // Ensure SSE connection exists
+  initSSE();
+}
+
+function initSSE() {
+  if (sseSource) return;
   try {
     sseSource = new EventSource("/api/sse");
-    sseSource.addEventListener("message", async () => {
-      const fresh = await api("/api/hook-log?limit=20");
-      if (fresh && fresh.entries && streamEl) {
-        streamEl.innerHTML = fresh.entries.slice().reverse().map(renderActivityRow).join("");
-      }
+    sseSource.addEventListener("message", async (ev) => {
+      // throttle bursty updates
+      if (ssePending) return;
+      ssePending = true;
+      setTimeout(async () => {
+        ssePending = false;
+        // update overview (always)
+        loadOverview();
+        // update active tab(s)
+        if (document.querySelector('.tab-btn[data-tab="activity"].active')) {
+          const streamEl = document.getElementById("activity-stream");
+          const fresh = await scopedApi("/api/hook-log?limit=20");
+          if (fresh && fresh.entries && streamEl) {
+            streamEl.innerHTML = fresh.entries.slice().reverse().map(renderActivityRow).join("");
+          }
+          const summary = await scopedApi("/api/hook-log/summary");
+          const toolsEl = document.getElementById("activity-tools");
+          if (toolsEl) toolsEl.innerHTML = renderToolBreakdown((summary && summary.byTool) || {});
+        }
+        if (document.querySelector('.tab-btn[data-tab="graph"].active')) {
+          await refreshGraph();
+        }
+        if (document.querySelector('.tab-btn[data-tab="files"].active')) {
+          loadFiles();
+        }
+        if (document.querySelector('.tab-btn[data-tab="providers"].active')) {
+          loadProviders();
+        }
+        if (document.querySelector('.tab-btn[data-tab="sessions"].active')) {
+          loadSessions();
+        }
+      }, 300);
+    });
+    sseSource.addEventListener("error", (e) => {
+      console.warn("SSE error", e);
     });
   } catch (e) {
-    console.warn("SSE failed", e);
+    console.warn("SSE init failed", e);
   }
 }
 
@@ -520,7 +789,7 @@ function renderToolBreakdown(byTool) {
 
 // ─── Tab: Files ───────────────────────────────────────────────
 async function loadFiles() {
-  const heatmap = await api("/api/files/heatmap?limit=30");
+  const heatmap = await scopedApi("/api/files/heatmap?limit=30");
   const tableEl = document.getElementById("files-table");
   if (!tableEl) return;
 
@@ -545,24 +814,162 @@ async function loadFiles() {
 // ─── Tab: Graph ───────────────────────────────────────────────
 let graphLoaded = false;
 
+function renderLegendIcon(shape, color) {
+  const size = 16;
+  if (shape === "circle") {
+    return '<svg width="' + size + '" height="' + size + '" viewBox="0 0 ' + size + ' ' + size + '" xmlns="http://www.w3.org/2000/svg"><circle cx="' + (size/2) + '" cy="' + (size/2) + '" r="' + (Math.floor(size/3)) + '" fill="' + esc(color) + '" /></svg>';
+  } else if (shape === "square") {
+    return '<svg width="' + size + '" height="' + size + '" viewBox="0 0 ' + size + ' ' + size + '" xmlns="http://www.w3.org/2000/svg"><rect x="2" y="2" width="' + (size-4) + '" height="' + (size-4) + '" fill="' + esc(color) + '" rx="2"/></svg>';
+  } else if (shape === "diamond") {
+    return '<svg width="' + size + '" height="' + size + '" viewBox="0 0 ' + size + ' ' + size + '" xmlns="http://www.w3.org/2000/svg"><polygon points="' + (size/2) + ',2 ' + (size-2) + ',' + (size/2) + ' ' + (size/2) + ',' + (size-2) + ' 2,' + (size/2) + '" fill="' + esc(color) + '"/></svg>';
+  } else {
+    return renderLegendIcon("circle", color);
+  }
+}
+
+function renderMemoryLegend(nodes, edges, nodesTotal) {
+  const el = document.getElementById("graph-legend");
+  if (!el || typeof MEMORY_SCOPE_CONFIG === "undefined") return;
+  const keys = ["project", "global", "entity"];
+
+  // Totals (best-effort) from provided nodes
+  const totalsNodes = { project: 0, global: 0, entity: 0 };
+  if (Array.isArray(nodes)) {
+    for (const n of nodes) {
+      try {
+        const meta = n.metadata || {};
+        const ms = (meta.memoryScope || meta.memory_scope) || "project";
+        if (ms === "global") totalsNodes.global++;
+        else if (ms === "entity") totalsNodes.entity++;
+        else totalsNodes.project++;
+      } catch {
+        totalsNodes.project++;
+      }
+    }
+  }
+
+  // Totals for edges (best-effort) — classify an edge by its endpoints' scope
+  const totalsEdges = { project: 0, global: 0, entity: 0, cross: 0 };
+  if (Array.isArray(edges)) {
+    // Build quick id->scope map from the provided nodes
+    const idToScope = new Map();
+    if (Array.isArray(nodes)) {
+      for (const n of nodes) {
+        const ms = (n.metadata && (n.metadata.memoryScope || n.metadata.memory_scope)) || 'project';
+        idToScope.set(n.id, ms);
+      }
+    }
+    for (const e of edges) {
+      const s = idToScope.get(e.source) || 'project';
+      const t = idToScope.get(e.target) || 'project';
+      if (s === t) totalsEdges[s] = (totalsEdges[s] || 0) + 1;
+      else totalsEdges.cross = (totalsEdges.cross || 0) + 1;
+    }
+  }
+
+  // Visible counts are provided by the running render (set on window)
+  const visibleIds = Array.isArray(window.__engram_graph_visibleNodes) ? window.__engram_graph_visibleNodes : [];
+  const visibleEdges = Array.isArray(window.__engram_graph_visibleEdges) ? window.__engram_graph_visibleEdges : [];
+
+  const idToScopeForVisible = new Map();
+  if (Array.isArray(nodes)) {
+    for (const n of nodes) {
+      const ms = (n.metadata && (n.metadata.memoryScope || n.metadata.memory_scope)) || 'project';
+      idToScopeForVisible.set(n.id, ms);
+    }
+  }
+
+  const visibleNodes = { project: 0, global: 0, entity: 0 };
+  for (const id of visibleIds) {
+    const ms = idToScopeForVisible.get(id) || 'project';
+    if (ms === 'global') visibleNodes.global++;
+    else if (ms === 'entity') visibleNodes.entity++;
+    else visibleNodes.project++;
+  }
+
+  const visibleEdgesCounts = { project: 0, global: 0, entity: 0, cross: 0 };
+  for (const e of visibleEdges) {
+    const s = idToScopeForVisible.get(e.source) || 'project';
+    const t = idToScopeForVisible.get(e.target) || 'project';
+    if (s === t) visibleEdgesCounts[s] = (visibleEdgesCounts[s] || 0) + 1;
+    else visibleEdgesCounts.cross = (visibleEdgesCounts.cross || 0) + 1;
+  }
+
+  // Render two rows: Total and Visible. Each row shows project/global/personal (nodes / edges)
+  const totalLabel = nodesTotal != null ? ('total: ' + nodesTotal) : '';
+  const rowBox = (label, nCount, eCount, accent) => {
+    const color = accent ? 'color: var(--accent);' : 'color: var(--text);';
+    return '<div style="display:flex;flex-direction:column;align-items:center;gap:6px;padding:6px 10px;border-radius:6px;min-width:120px;">' +
+      '<div style="font-family:var(--mono);font-size:12px;'+ color + '">' + esc(label) + '</div>' +
+      '<div style="font-family:var(--mono);font-size:12px;color:var(--text-dim);">' + esc(nCount) + ' nodes / ' + esc(eCount) + ' edges</div>' +
+      '</div>';
+  };
+
+  const projectBoxTotal = rowBox(MEMORY_SCOPE_CONFIG.project.label, totalsNodes.project || 0, totalsEdges.project || 0, false);
+  const globalBoxTotal = rowBox(MEMORY_SCOPE_CONFIG.global.label, totalsNodes.global || 0, totalsEdges.global || 0, false);
+  const personalBoxTotal = rowBox(MEMORY_SCOPE_CONFIG.entity.label, totalsNodes.entity || 0, totalsEdges.entity || 0, false);
+
+  const projectBoxVisible = rowBox(MEMORY_SCOPE_CONFIG.project.label, visibleNodes.project || 0, visibleEdgesCounts.project || 0, true);
+  const globalBoxVisible = rowBox(MEMORY_SCOPE_CONFIG.global.label, visibleNodes.global || 0, visibleEdgesCounts.global || 0, true);
+  const personalBoxVisible = rowBox(MEMORY_SCOPE_CONFIG.entity.label, visibleNodes.entity || 0, visibleEdgesCounts.entity || 0, true);
+
+  el.innerHTML = '<div style="display:flex;flex-direction:column;gap:8px;align-items:center;">' +
+    '<div style="font-family:var(--mono);font-size:12px;color:var(--text-dim);">' + esc(totalLabel) + '</div>' +
+    '<div style="display:flex;gap:12px;justify-content:center;align-items:center;">' + projectBoxTotal + globalBoxTotal + personalBoxTotal + '</div>' +
+    '<div style="display:flex;gap:12px;justify-content:center;align-items:center;">' + projectBoxVisible + globalBoxVisible + personalBoxVisible + '</div>' +
+    '</div>';
+}
+
 async function loadGraph() {
   if (graphLoaded) return;
   const [nodes, godNodes] = await Promise.all([
-    api("/api/graph/nodes?limit=300"),
-    api("/api/graph/god-nodes"),
+    scopedApi("/api/graph/nodes?limit=300"),
+    scopedApi("/api/graph/god-nodes"),
   ]);
   if (!nodes) return;
   graphLoaded = true;
   const canvas = document.getElementById("graph-canvas");
-  if (canvas) renderGraph(canvas, nodes.nodes ?? [], godNodes ?? []);
-  setText("graph-info", (nodes.nodes?.length ?? 0) + " of " + (nodes.total ?? 0) + " nodes shown");
+  if (canvas) {
+    const nodeList = nodes.nodes ?? [];
+    let edges = [];
+    try {
+      const CHUNK = 400;
+      for (let i = 0; i < nodeList.length; i += CHUNK) {
+        const ids = nodeList.slice(i, i + CHUNK).map((n) => n.id).join(",");
+        const eResp = await scopedApi("/api/graph/edges?ids=" + encodeURIComponent(ids));
+        if (eResp && Array.isArray(eResp.edges)) edges = edges.concat(eResp.edges);
+      }
+    } catch {
+      edges = [];
+    }
+
+    try {
+      const nodeById = new Map(nodeList.map((n) => [n.id, n]));
+      const missingIds = new Set();
+      for (const ed of edges) {
+        if (!nodeById.has(ed.source)) missingIds.add(ed.source);
+        if (!nodeById.has(ed.target)) missingIds.add(ed.target);
+      }
+      for (const mid of missingIds) {
+        const p = { id: mid, label: mid, kind: 'default', metadata: { }, sourceFile: '', sourceLocation: null };
+        nodeList.push(p);
+      }
+    } catch {
+      // ignore
+    }
+
+    renderGraph(canvas, nodeList, godNodes ?? [], edges);
+    setText("graph-info", (nodeList.length ?? 0) + " nodes, " + (edges.length ?? 0) + " edges — " + (nodes.total ?? 0) + " total");
+  }
+  // Render memory legend (colors/shapes)
+  renderMemoryLegend(nodeList, edges, nodes.total ?? null);
 }
 
 // ─── Tab: Providers ───────────────────────────────────────────
 async function loadProviders() {
   const [health, cache] = await Promise.all([
     api("/api/providers/health"),
-    api("/api/cache/stats"),
+    scopedApi("/api/cache/stats"),
   ]);
 
   let html = "";
@@ -596,8 +1003,22 @@ async function loadProviders() {
 }
 
 // ─── Initial load ─────────────────────────────────────────────
-loadOverview();
-setInterval(loadOverview, 5000);
+// Load scopes first, then bootstrap dashboard data so all requests carry the selected scope/project
+loadScopes().then(() => {
+  loadOverview();
+  setInterval(loadOverview, 5000);
+  initSSE();
+});
+
+// Attach refresh button handler
+const rbtn = document.getElementById('tokens-refresh');
+if (rbtn) {
+  rbtn.addEventListener('click', async () => {
+    showToast('Refreshing token metrics...');
+    await loadOverview();
+    showToast('Token metrics updated', 1400);
+  });
+}
 `;
 
 /**
diff --git a/src/setup/wizard.ts b/src/setup/wizard.ts
index 4f51d09..5ffe309 100644
--- a/src/setup/wizard.ts
+++ b/src/setup/wizard.ts
@@ -201,7 +201,7 @@ async function offerIdeAdapters(
     Windsurf: "engram gen-windsurfrules",
     Aider: "engram gen-aider",
     "Codex CLI": "engram gen --target agents",
-    Cline: "Add to cline_mcp_settings.json: { engram: { command: 'engram-serve', args: ['" + root + "'] } }",
+    Cline: "Add to cline_mcp_settings.json: { engramx: { command: 'engram-serve', args: ['" + root + "'] } }",
     "Continue.dev": "Add to ~/.continue/config.json: { contextProviders: [{ name: 'engramx-continue' }] }",
     Zed: "Register engram-serve as a Zed context server (see Docs/integrations/zed.md)",
   };
diff --git a/src/tuner/config.ts b/src/tuner/config.ts
index cc24831..80dd430 100644
--- a/src/tuner/config.ts
+++ b/src/tuner/config.ts
@@ -21,6 +21,10 @@ export interface EngramConfig {
   readonly confidenceThreshold: number;
   readonly totalTokenBudget: number;
   readonly providers: Readonly<Record<string, ProviderOverride>>;
+  /** Auto-memory ingestion: enabled (true) or disabled (false). */
+  readonly autoMemoryEnabled?: boolean;
+  /** Scopes to auto-ingest when autoMemoryEnabled is true. */
+  readonly autoMemoryScopes?: readonly ("project" | "global" | "entity")[];
 }
 
 /** Baseline defaults. Must match the hard-coded values in resolver.ts. */
@@ -28,6 +32,9 @@ const DEFAULTS: EngramConfig = {
   confidenceThreshold: 0.7,
   totalTokenBudget: 600,
   providers: {},
+  // Aggressive auto by default per user request
+  autoMemoryEnabled: true,
+  autoMemoryScopes: ["project", "global", "entity"],
 };
 
 /**
diff --git a/src/tuner/index.ts b/src/tuner/index.ts
index 8e2d198..133452a 100644
--- a/src/tuner/index.ts
+++ b/src/tuner/index.ts
@@ -95,7 +95,7 @@ export function analyzeTuning(projectRoot: string): TuneProposal {
   // ── Rule 2: Disable never-contributing providers ──────────────────
   // Only flag a provider if it appeared 0 times AND we have enough data
   if (deniedReads.length >= ALWAYS_ON_MIN_EVENTS) {
-    const knownProviders = ["engram:structure", "engram:mistakes", "engram:git", "mempalace", "context7", "obsidian"];
+    const knownProviders = ["engramx:structure", "engramx:mistakes", "engramx:git", "mempalace", "context7", "obsidian"];
     for (const pName of knownProviders) {
       const hits = providerHits.get(pName) ?? 0;
       const override = config.providers[pName];
diff --git a/src/watcher.ts b/src/watcher.ts
index 91fa3c0..4fdf6a1 100644
--- a/src/watcher.ts
+++ b/src/watcher.ts
@@ -76,9 +76,9 @@ export async function syncFile(
   if (!existsSync(absPath)) {
     const store = await getStore(projectRoot);
     try {
-      const prior = store.countBySourceFile(relPath);
+      const prior = store.countBySourceFile(relPath, projectRoot);
       if (prior === 0) return { action: "skipped", count: 0 };
-      store.deleteBySourceFile(relPath);
+      store.deleteBySourceFile(relPath, projectRoot);
       return { action: "pruned", count: prior };
     } finally {
       store.close();
@@ -93,10 +93,10 @@ export async function syncFile(
 
   const store = await getStore(projectRoot);
   try {
-    store.deleteBySourceFile(relPath);
+    store.deleteBySourceFile(relPath, projectRoot);
     const { nodes, edges } = extractFile(absPath, projectRoot);
     if (nodes.length > 0 || edges.length > 0) {
-      store.bulkUpsert(nodes, edges);
+      store.bulkUpsert(nodes, edges, projectRoot, undefined, "project");
     }
     return { action: "indexed", count: nodes.length };
   } finally {
@@ -114,10 +114,10 @@ export function formatReindexLine(
   displayPath: string
 ): string | null {
   if (result.action === "indexed") {
-    return `engram: reindexed ${displayPath} (${formatThousands(result.count)} nodes)`;
+    return `engramx: reindexed ${displayPath} (${formatThousands(result.count)} nodes)`;
   }
   if (result.action === "pruned") {
-    return `engram: pruned ${displayPath} (${formatThousands(result.count)} nodes)`;
+    return `engramx: pruned ${displayPath} (${formatThousands(result.count)} nodes)`;
   }
   return null;
 }
@@ -186,7 +186,7 @@ export function watchProject(
 
   if (!existsSync(getDbPath(root))) {
     throw new Error(
-      `engram: no graph found at ${root}. Run 'engram init' first.`
+      `engramx: no graph found at ${root}. Run 'engram init' first.`
     );
   }
 
diff --git a/tests/fixtures/hook-payloads/README.md b/tests/fixtures/hook-payloads/README.md
index d460375..9cf8b8a 100644
--- a/tests/fixtures/hook-payloads/README.md
+++ b/tests/fixtures/hook-payloads/README.md
@@ -24,7 +24,7 @@ The spike confirmed TWO response mechanisms work for PreToolUse:Read:
      "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "deny",
-       "permissionDecisionReason": "[engram] <summary>"
+       "permissionDecisionReason": "[engramx] <summary>"
      }
    }
    ```
@@ -36,7 +36,7 @@ The spike confirmed TWO response mechanisms work for PreToolUse:Read:
      "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "allow",
-       "additionalContext": "[engram] <warning>"
+       "additionalContext": "[engramx] <warning>"
      }
    }
    ```
diff --git a/tests/intercept/cli-intercept.test.ts b/tests/intercept/cli-intercept.test.ts
index d8b5db7..ffc4755 100644
--- a/tests/intercept/cli-intercept.test.ts
+++ b/tests/intercept/cli-intercept.test.ts
@@ -123,7 +123,7 @@ export function hashPassword(p: string) { return "h_" + p; }
     expect(parsed.hookSpecificOutput.permissionDecision).toBe("deny");
     expect(
       parsed.hookSpecificOutput.permissionDecisionReason
-    ).toContain("[engram] Structural summary");
+    ).toContain("[engramx] Structural summary");
   });
 
   it("produces no stdout (passthrough) for a file not in the graph", () => {
@@ -162,7 +162,7 @@ export function hashPassword(p: string) { return "h_" + p; }
     const parsed = JSON.parse(result.stdout);
     expect(parsed.hookSpecificOutput.hookEventName).toBe("SessionStart");
     expect(parsed.hookSpecificOutput.additionalContext).toContain(
-      "[engram] Project brief"
+      "[engramx] Project brief"
     );
   });
 
diff --git a/tests/intercept/formatter.test.ts b/tests/intercept/formatter.test.ts
index 2f3d7d9..22aea34 100644
--- a/tests/intercept/formatter.test.ts
+++ b/tests/intercept/formatter.test.ts
@@ -50,7 +50,7 @@ describe("formatter — truncateForHook", () => {
 
 describe("formatter — buildDenyResponse", () => {
   it("produces the verified PreToolUse deny+reason shape", () => {
-    const reason = "[engram] graph summary for src/cli.ts\n\nNODE foo [function]";
+    const reason = "[engramx] graph summary for src/cli.ts\n\nNODE foo [function]";
     const response = buildDenyResponse(reason);
     expect(response).toEqual({
       hookSpecificOutput: {
diff --git a/tests/intercept/handlers/bash.test.ts b/tests/intercept/handlers/bash.test.ts
index 0d5a32d..599cb94 100644
--- a/tests/intercept/handlers/bash.test.ts
+++ b/tests/intercept/handlers/bash.test.ts
@@ -227,7 +227,7 @@ export function hashPassword(p: string) { return "h_" + p; }
     };
     expect(wrapped.hookSpecificOutput.permissionDecision).toBe("deny");
     expect(wrapped.hookSpecificOutput.permissionDecisionReason).toContain(
-      "[engram] Structural summary for src/auth.ts"
+      "[engramx] Structural summary for src/auth.ts"
     );
   });
 
diff --git a/tests/intercept/handlers/cwd-changed.test.ts b/tests/intercept/handlers/cwd-changed.test.ts
index af5132e..d9f4e89 100644
--- a/tests/intercept/handlers/cwd-changed.test.ts
+++ b/tests/intercept/handlers/cwd-changed.test.ts
@@ -48,7 +48,7 @@ describe("handleCwdChanged", () => {
 
     const output = (result as Record<string, unknown>).hookSpecificOutput as Record<string, unknown>;
     const ctx = output.additionalContext as string;
-    expect(ctx).toContain("[engram] Project switched to project-alpha");
+    expect(ctx).toContain("[engramx] Project switched to project-alpha");
     expect(ctx).toContain("engram interception is active");
   });
 
diff --git a/tests/intercept/handlers/pre-compact.test.ts b/tests/intercept/handlers/pre-compact.test.ts
index b905af0..5374d4a 100644
--- a/tests/intercept/handlers/pre-compact.test.ts
+++ b/tests/intercept/handlers/pre-compact.test.ts
@@ -56,7 +56,7 @@ describe("handlePreCompact", () => {
     expect(output).toBeDefined();
     const ctx = output.additionalContext as string;
     expect(ctx).toBeDefined();
-    expect(ctx).toContain("[engram] Compaction survival");
+    expect(ctx).toContain("[engramx] Compaction survival");
     expect(ctx).toContain("myapp");
   });
 
diff --git a/tests/intercept/handlers/read.test.ts b/tests/intercept/handlers/read.test.ts
index 6fe93fa..1b7ebdb 100644
--- a/tests/intercept/handlers/read.test.ts
+++ b/tests/intercept/handlers/read.test.ts
@@ -135,7 +135,7 @@ export { svc };
 
     // The reason must contain the engram summary header.
     const reason = wrapped.hookSpecificOutput.permissionDecisionReason;
-    expect(reason).toContain("[engram] Structural summary for src/auth.ts");
+    expect(reason).toContain("[engramx] Structural summary for src/auth.ts");
     expect(reason).toContain("NODE");
     expect(reason).toContain("offset/limit"); // escape hatch footer
   });
diff --git a/tests/intercept/handlers/session-start.test.ts b/tests/intercept/handlers/session-start.test.ts
index b997407..39468c8 100644
--- a/tests/intercept/handlers/session-start.test.ts
+++ b/tests/intercept/handlers/session-start.test.ts
@@ -82,7 +82,7 @@ export function transaction(fn: () => void) { fn(); }
     };
     expect(wrapped.hookSpecificOutput.hookEventName).toBe("SessionStart");
     const text = wrapped.hookSpecificOutput.additionalContext;
-    expect(text).toContain("[engram] Project brief");
+    expect(text).toContain("[engramx] Project brief");
     expect(text).toContain("nodes");
     expect(text).toContain("edges");
   });
diff --git a/tests/intercept/handlers/user-prompt.test.ts b/tests/intercept/handlers/user-prompt.test.ts
index 9139456..ef5937a 100644
--- a/tests/intercept/handlers/user-prompt.test.ts
+++ b/tests/intercept/handlers/user-prompt.test.ts
@@ -142,7 +142,7 @@ export function closeConnection() {}
     };
     expect(wrapped.hookSpecificOutput.hookEventName).toBe("UserPromptSubmit");
     expect(wrapped.hookSpecificOutput.additionalContext).toContain(
-      "[engram] Pre-query context"
+      "[engramx] Pre-query context"
     );
   });
 
diff --git a/tests/intercept/render-file-structure.test.ts b/tests/intercept/render-file-structure.test.ts
index 75de01b..a1bf42e 100644
--- a/tests/intercept/render-file-structure.test.ts
+++ b/tests/intercept/render-file-structure.test.ts
@@ -94,7 +94,7 @@ export { svc };
     );
     try {
       const result = renderFileStructure(store, "src/auth.ts");
-      expect(result.text.startsWith("[engram] Structural summary for src/auth.ts")).toBe(true);
+      expect(result.text.startsWith("[engramx] Structural summary for src/auth.ts")).toBe(true);
     } finally {
       store.close();
     }
diff --git a/tests/intercept/spike-regression.test.ts b/tests/intercept/spike-regression.test.ts
index fb0a662..b747823 100644
--- a/tests/intercept/spike-regression.test.ts
+++ b/tests/intercept/spike-regression.test.ts
@@ -44,7 +44,7 @@ describe("spike regression — PreToolUse Read deny+reason", () => {
     // v4 spike: the hook returned deny + permissionDecisionReason, and
     // Claude Code delivered the reason to the agent as a system-reminder.
     const reason =
-      "[engram] graph summary for target-v2.txt\n\n" +
+      "[engramx] graph summary for target-v2.txt\n\n" +
       "NODE target [file] src=/tmp/engram-spike/test-project/target-v2.txt L1\n" +
       "Use this context instead of reading the file directly.";
     const response = buildDenyResponse(reason);
@@ -75,7 +75,7 @@ describe("spike regression — PreToolUse Edit allow+additionalContext", () => {
     // v5 spike: allow + additionalContext. Agent sees both tool result
     // AND the context injection as a system-reminder.
     const warning =
-      "[engram landmines] This file has 2 past mistakes:\n" +
+      "[engramx landmines] This file has 2 past mistakes:\n" +
       "  - bug: null pointer in validateToken (src/auth.ts)\n" +
       "  - fix: token refresh race condition (src/auth.ts)\n" +
       "Review before editing.";
@@ -124,7 +124,7 @@ describe("spike regression — UserPromptSubmit context injection", () => {
 
   it("produces a UserPromptSubmit additionalContext response", () => {
     const ctx =
-      "[engram pre-query] matches for 'authentication flow':\n" +
+      "[engramx pre-query] matches for 'authentication flow':\n" +
       "NODE authMiddleware [function] src=src/auth.ts";
     const response = buildSessionContextResponse("UserPromptSubmit", ctx);
     expect(response).not.toBe(null);
diff --git a/tests/memory-scope.test.ts b/tests/memory-scope.test.ts
new file mode 100644
index 0000000..a92d3cf
--- /dev/null
+++ b/tests/memory-scope.test.ts
@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { learn, getStore } from "../src/core.js";
+
+describe("memory scope recording and retrieval", () => {
+  let tmpDir: string;
+  let projectRoot: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "engram-test-"));
+    projectRoot = tmpDir;
+    // Ensure project root exists
+    mkdirSync(projectRoot, { recursive: true });
+    // Use an isolated global DB for this test run
+    process.env.ENGRAM_GLOBAL_DB_PATH = join(tmpDir, "memory.db");
+  });
+
+  afterEach(() => {
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ignore */ }
+    delete process.env.ENGRAM_GLOBAL_DB_PATH;
+  });
+
+  it("records ~100 memories for each scope and retrieves them by memoryScope", async () => {
+    const scopes = ["project", "global", "entity"];
+    // Insert 100 decision-like statements per scope in a single learn call per scope
+    for (const scope of scopes) {
+      const lines: string[] = [];
+      for (let i = 0; i < 100; i++) {
+        lines.push(`We chose ${scope}Choice${i} over legacy for testing`);
+      }
+      const text = lines.join("\n");
+      await learn(projectRoot, text, "test", scope);
+    }
+
+    const store = await getStore(projectRoot);
+    try {
+      const all = store.getAllNodes(projectRoot);
+      // Count by metadata.memoryScope
+      const counts: Record<string, number> = { project: 0, global: 0, entity: 0 };
+      for (const n of all) {
+        const ms = (n.metadata && (n.metadata as any).memoryScope) || "project";
+        if (counts[ms] !== undefined) counts[ms]++;
+      }
+
+      // Expect approx 100 entries per scope (some miners may produce extra nodes,
+      // but at least 100 per scope should be present)
+      expect(counts.project).toBeGreaterThanOrEqual(100);
+      expect(counts.global).toBeGreaterThanOrEqual(100);
+      expect(counts.entity).toBeGreaterThanOrEqual(100);
+    } finally {
+      store.close();
+    }
+  });
+});