engram-mcp-server 1.7.0 → 1.7.2

package/README.md

@@ -21,7 +21,8 @@
 - [Overview](#overview)
 - [Why Engram?](#why-engram)
 - [Installation (Auto & Manual)](#installation)
-- [✨ What's New in v1.7.0](#-whats-new-in-v170)
+- [✨ What's New in v1.7.2](#-whats-new-in-v172)
+- [What's New in v1.7.0](#-whats-new-in-v170)
 - [What's New in v1.6.0](#-whats-new-in-v160)
 - [Features](#features)
 - [Architecture](#architecture)
@@ -55,6 +56,45 @@ Engram solves this by providing a **persistent brain** using a native SQLite (WA
 
 ---
 
+## ✨ What's New in v1.7.2
+
+**v1.7.2** is a hotfix release addressing 20 bugs found during a systematic functional audit of the v1.7.0 tool surface.
+
+### 🔒 Enum Validation for Change, Task, and Scope Fields
+
+`record_change`, `create_task`, and related actions now enforce enum validation on `change_type`, `impact_scope`, and `priority`. Previously, arbitrary strings were silently accepted, corrupting query results and task filtering.
+
+- `change_type`: `created | modified | deleted | refactored | renamed | moved | config_changed`
+- `impact_scope`: `local | module | cross_module | global`
+- `priority`: `critical | high | medium | low`
+
+### 📡 Directed Broadcasts — `target_agent` Now Works
+
+`engram_memory(action:"broadcast", target_agent:"agent-name")` now correctly stores and filters directed messages. Previously the `target_agent` column was missing from the DB schema and the `agent_sync` query had no filter — all agents received all broadcasts regardless.
+
+### ⏱️ `what_changed { since: "session_start" }` Fixed
+
+The `"session_start"` sentinel value is now resolved to the current session's `started_at` timestamp before the SQL query. Previously it was passed literally, always returning zero results.
+
+### 🔧 Universal Mode Array Coercion Fixed
+
+`set_file_notes` with `dependencies` passed as a JSON string (e.g. `"[\"src/a.ts\"]"`) no longer crashes in Universal Mode. A `parseDepsField()` helper now handles both native arrays and JSON-encoded strings at the repository layer — compensating for the `HandlerCapturer` bypass of Zod preprocessing.
+
+### ✅ API Correctness Fixes (ISS-001 – ISS-015)
+
+- `generate_report` and `get_global_knowledge` return real data
+- `backup` no longer returns ENOENT
+- `get_tasks { status:"all" }` returns all tasks
+- `acknowledge_event { approved:false }` snoozes the event
+- `config { op:"get", key:X }` returns only that key's value
+- `record_milestone` version prefix no longer doubled
+- `dump` no longer creates a spurious change record
+- `NoActiveSessionError` message uses correct v1.7 syntax
+
+> Full changelog: [RELEASE_NOTES.md](RELEASE_NOTES.md)
+
+---
+
 ## ✨ What's New in v1.7.0
 
 **v1.7.0** is a precision token-efficiency release — six improvement tracks with zero breaking changes to the 4-dispatcher API surface.
@@ -211,10 +251,17 @@ Run this single command in your terminal. It will automatically detect your IDE
 npx -y engram-mcp-server --install
 ```
 
+**Universal mode** (~80 token single-tool schema — recommended for token-conscious setups):
+
+```bash
+npx -y engram-mcp-server --install --universal
+```
+
 **Non-interactive mode (CI/CD / Scripting):**
 
 ```bash
 npx -y engram-mcp-server install --ide vscode --yes
+npx -y engram-mcp-server install --ide vscode --universal --yes
 ```
 
 **Clean removal:**
@@ -461,6 +508,22 @@ In the extension settings → MCP Servers:
 
 </details>
 
+### Verifying Your Installation
+
+After installing, verify Engram is working by running:
+
+```bash
+npx -y engram-mcp-server --check
+```
+
+Or use the MCP Inspector for a full interactive test:
+
+```bash
+npx @modelcontextprotocol/inspector npx -y engram-mcp-server
+```
+
+In your IDE, open the AI chat and ask the agent to call `engram_session(action:"start")`. If it returns a session ID and tool catalog, Engram is running correctly.
+
 ---
 
 ## Features
@@ -601,51 +664,75 @@ Engram v1.7.0 exposes **4 dispatcher tools** (or 1 tool in `--mode=universal`).
 
 ## Using with AI Agents
 
-Add the following to your agent's system prompt or custom instructions — Cursor Rules, `.github/copilot-instructions.md`, `CLAUDE.md`, or whichever file your IDE reads. The goal is to make the agent consult Engram **before** doing work, not just after. That's where most of the token and time savings come from.
+> **Copy-paste ready.** Copy everything between the `<!-- ENGRAM_INSTRUCTIONS_START -->` and `<!-- ENGRAM_INSTRUCTIONS_END -->` markers below directly into your agent's instruction file — `CLAUDE.md`, `.github/copilot-instructions.md`, Cursor Rules, or equivalent. No reformatting needed. Works as-is.
+
+<!-- ENGRAM_INSTRUCTIONS_START -->
+
+## Engram — Persistent Memory MCP (v1.7)
+
+Engram is a persistent memory MCP server. It gives AI agents session continuity, change tracking, decision logging, and multi-agent coordination across sessions — all via a SQLite database. The API surface is **4 dispatcher tools** (or **1 tool** in universal mode) — each routed via an `action` parameter. Schema tokens: ~1,600 per call in standard mode, ~80 in universal mode.
 
-> You have access to **Engram**, a persistent memory MCP server. It stores everything learned about this project across all sessions: file notes, architectural decisions, conventions, tasks, and change history. Use it to avoid re-reading files already analysed, re-debating settled decisions, and re-discovering known context.
+Follow these rules **every session, every project**.
 
 ---
 
-### 🟢 Session Start
+### Dispatcher Tools
 
-**Always call `engram_session(action:"start")` first** — before reading any file or taking any action. Pass `focus` when you know what you're about to work on — it FTS5-ranks returned context around that topic.
+| Tool             | Responsibility                                    |
+| ---------------- | ------------------------------------------------- |
+| `engram_session` | Session lifecycle (start, end, handoffs, history) |
+| `engram_memory`  | All memory operations (34+ actions)               |
+| `engram_admin`   | Maintenance, git hooks, backup, config, stats     |
+| `engram_find`    | Tool catalog search + convention linting          |
+
+> If running in **universal mode** (`--mode=universal`), all actions route through a single `engram` tool instead. Call `engram({ action: "start" })` etc.
+
+> Use `engram_find({ query: "what I want to do" })` whenever you don't know the exact `action` name.
+
+---
+
+### 1. Session Start — Always First
+
+**Before reading any file or taking any action**, call `engram_session(action:"start")`.
 
 ```js
 engram_session({
     action: "start",
     agent_name: "claude",
     verbosity: "summary",
-    focus: "authentication refactor",
+    focus: "topic if known",
 });
 ```
 
-Act on everything it returns:
+- **Verbosity** — Use `"summary"` by default. Use `"minimal"` for count-only context. Use `"nano"` (under 100 tokens) only when context is critically constrained. **Never** use `"full"`.
+- **`focus`** — When you know what you're about to work on, pass it. Context is FTS5-ranked around that topic.
+- **`tool_catalog`** — Returned at session start. Use it to know available actions — do not call a separate tool for this.
 
-| Field                      | What to do                                                                                                                 |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `previous_session.summary` | Read immediately. Do not re-explore what is already known.                                                                 |
-| `active_decisions`         | Binding. Follow them; do not re-debate. Supersede with `engram_memory(action:"record_decision")` if they must change.      |
-| `active_conventions`       | Enforce in every file you touch this session.                                                                              |
-| `open_tasks`               | Pending work items. Ask the user which to focus on if unclear.                                                             |
-| `abandoned_work`           | Work items left open by a previous session that ended unexpectedly. Review and resume or close.                            |
-| `handoff_pending`          | A structured handoff from the previous agent. Read instructions, then call `engram_session(action:"acknowledge_handoff")`. |
-| `suggested_focus`          | Auto-derived topic hint. Pass as `focus` on the next `start` call for filtered context.                                    |
-| `triggered_events`         | Scheduled reminders or deferred work now triggered. Act on them.                                                           |
-| `agent_rules`              | Live-loaded rules from the Engram README. Treat as binding session instructions.                                           |
-| `tool_catalog`             | Full list of available `engram_memory` and `engram_admin` actions with schemas.                                            |
-| `update_available`         | Tell the user: _"Engram v{available_version} is available. Update, skip, or postpone?"_                                    |
+Act on everything returned:
 
-If `update_available` is set, respond to the user's choice:
+| Field                      | What to do                                                                                                               |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `previous_session.summary` | Read immediately. Do not re-explore what is already known.                                                               |
+| `active_decisions`         | Binding. Follow them. Supersede via `engram_memory(action:"record_decision", supersedes:<id>)` only if they must change. |
+| `active_conventions`       | Enforce in every file touched this session.                                                                              |
+| `open_tasks`               | Pending work. Ask the user which to focus on if unclear.                                                                 |
+| `abandoned_work`           | Work left open by a previous unexpected session end. Resume or close it.                                                 |
+| `handoff_pending`          | Structured handoff from previous agent. Read instructions, then call `engram_session(action:"acknowledge_handoff")`.     |
+| `suggested_focus`          | Auto-derived topic hint. Pass as `focus` on the next `start` call.                                                       |
+| `triggered_events`         | Scheduled reminders or deferred work now due. Act on them.                                                               |
+| `agent_rules`              | Live-loaded rules from the Engram README. Treat as binding session instructions.                                         |
+| `update_available`         | Inform the user: _"Engram v{version} is available — update, skip, or postpone?"_                                         |
+
+**If `update_available` is set**, respond to the user's choice:
 
 - **Update** → `npx -y engram-mcp-server install`
-- **Skip** → `engram_admin({ action: "config", op: "set", key: "auto_update_skip_version", value: "{version}" })`
-- **Postpone** → `engram_admin({ action: "config", op: "set", key: "auto_update_remind_after", value: "7d" })`
-- **Disable** → `engram_admin({ action: "config", op: "set", key: "auto_update_check", value: "false" })`
+- **Skip this version** → `engram_admin({ action: "config", op: "set", key: "auto_update_skip_version", value: "{version}" })`
+- **Postpone 7 days** → `engram_admin({ action: "config", op: "set", key: "auto_update_remind_after", value: "7d" })`
+- **Disable checks** → `engram_admin({ action: "config", op: "set", key: "auto_update_check", value: "false" })`
 
 ---
 
-### 📂 Before Reading Any File
+### 2. Before Opening Any File
 
 Always check Engram before opening a file:
 
@@ -653,18 +740,26 @@ Always check Engram before opening a file:
 engram_memory({ action: "get_file_notes", file_path: "path/to/file.ts" });
 ```
 
-- **`confidence: "high"`** → Use stored notes. Only open the file if you need to edit it.
-- **`confidence: "medium"`** → Notes exist but the file may have minor changes. Use as a guide; open if precision matters.
-- **`confidence: "stale"`** → The file has changed significantly since notes were stored. Re-read and update notes.
-- **No notes** → Read the file, then immediately call `engram_memory(action:"set_file_notes")` with `file_path`, `purpose`, `dependencies`, `dependents`, `layer`, `complexity`, `notes`. Batch multiple files with `set_file_notes_batch`.
+| `confidence` result | Action                                                                              |
+| ------------------- | ----------------------------------------------------------------------------------- |
+| `"high"`            | Use stored notes. Only open if you need to edit.                                    |
+| `"medium"`          | Notes exist but file may have minor changes. Open only if precision matters.        |
+| `"stale"`           | File has changed since notes were stored (hash mismatch). Re-read and update notes. |
+| No notes            | Read the file, then immediately call `set_file_notes`.                              |
 
-> **Rule:** Never read a file already analysed in a previous session without checking Engram first.
+After reading a file for the first time, store notes immediately:
+
+```js
+engram_memory({ action: "set_file_notes", file_path, purpose, dependencies, dependents, layer, complexity, notes, executive_summary })
+// Batch multiple files:
+engram_memory({ action: "set_file_notes_batch", files: [...] })
+```
 
 ---
 
-### 🏛️ Before Making Any Design Decision
+### 3. Before Making Design or Architecture Decisions
 
-Before choosing an implementation approach, search for an existing decision:
+Search for existing decisions before proposing anything:
 
 ```js
 engram_memory({
@@ -672,29 +767,29 @@ engram_memory({
     query: "relevant keywords",
     scope: "decisions",
 });
+// or:
+engram_memory({ action: "get_decisions" });
 ```
 
 - **Decision exists** → Follow it.
-- **Should change** → Explain why, then supersede:
-    ```js
-    engram_memory({ action: "record_decision", decision: "...", supersedes: <id> })
-    ```
-- **No decision exists** → Make the call and record it:
-    ```js
-    engram_memory({
-        action: "record_decision",
-        decision,
-        rationale,
-        affected_files,
-        tags,
-    });
-    ```
+- **Needs to change** → Explain why, then: `engram_memory({ action:"record_decision", supersedes:<id>, decision, rationale })`
+- **No decision** → Make the call and record it immediately:
+
+```js
+engram_memory({
+    action: "record_decision",
+    decision,
+    rationale,
+    affected_files,
+    tags,
+});
+```
 
 ---
 
-### ✏️ When Modifying Files
+### 4. When Modifying Files
 
-After every meaningful change, record it. Batch where possible:
+After every meaningful change, record it — batch where possible:
 
 ```js
 engram_memory({
@@ -703,7 +798,7 @@ engram_memory({
         {
             file_path,
             change_type, // created | modified | refactored | deleted | renamed | moved | config_changed
-            description, // What changed AND why — not just the action. Future sessions read this.
+            description, // What changed AND why — not just the action
             impact_scope, // local | module | cross_module | global
         },
     ],
@@ -712,7 +807,7 @@ engram_memory({
 
 ---
 
-### 🔍 When You Don't Know Something
+### 5. When You Don't Know Something
 
 Search Engram before asking the user — they may have already explained it to a previous session:
 
@@ -727,22 +822,92 @@ engram_find({ query: "what I want to do" }); // discover the right action
 
 ---
 
-### 🔴 Session End
+### 6. Mid-Session — Approaching Context Limits
 
-Before ending every session:
+Before hitting the context wall, save a checkpoint:
+
+```js
+engram_memory({ action: "checkpoint", current_understanding: "...", progress_percentage: 70, key_findings: [...], next_steps: [...], file_paths: [...] })
+// Restore later:
+engram_memory({ action: "get_checkpoint" })
+```
+
+Check for context pressure events proactively:
+
+```js
+engram_memory({ action: "check_events" }); // fires at 50% / 70% / 85% context fill
+```
+
+---
+
+### 7. Session End — Always Last
+
+Before ending any session:
 
 1. Record all file changes not yet recorded.
-2. Create tasks for anything incomplete or blocked:
-    ```js
-    engram_memory({ action: "create_task", title, description, priority });
-    ```
-3. Call `engram_session({ action: "end", summary: "..." })` with a summary that includes:
-    - Exactly what was done — file names, function names, specific changes
-    - What is pending or blocked, and why
-    - Any new patterns, gotchas, or constraints discovered
-    - Which tasks were completed or partially done
+2. Mark completed tasks: `engram_memory({ action:"update_task", task_id, status:"done" })`
+3. Create tasks for anything incomplete: `engram_memory({ action:"create_task", title, description, priority })`
+4. Record any new conventions: `engram_memory({ action:"add_convention", convention, rationale })`
+5. Call end with a precise summary:
+
+```js
+engram_session({
+    action: "end",
+    summary:
+        "Exact files/functions touched, what is pending, any blockers, new patterns discovered",
+});
+```
+
+---
+
+### Quick Reference
+
+| Situation                       | Call                                                        | Notes                                   |
+| ------------------------------- | ----------------------------------------------------------- | --------------------------------------- |
+| **Start every session**         | `engram_session(action:"start")`                            | verbosity:"summary", add focus if known |
+| Discover an action name         | `engram_find({ query:"..." })`                              | Returns action name + param schema      |
+| Before opening any file         | `engram_memory(action:"get_file_notes")`                    |                                         |
+| After first reading a file      | `engram_memory(action:"set_file_notes")`                    | Include `executive_summary`             |
+| Before a design choice          | `engram_memory(action:"search")` / `action:"get_decisions"` |                                         |
+| Record a new decision           | `engram_memory(action:"record_decision")`                   | Always include `rationale`              |
+| After editing files             | `engram_memory(action:"record_change")`                     | Batch multiple changes in one call      |
+| Save mid-session progress       | `engram_memory(action:"checkpoint")`                        | Use near context limits                 |
+| Check context pressure          | `engram_memory(action:"check_events")`                      | Fires at 50% / 70% / 85%                |
+| Create task for incomplete work | `engram_memory(action:"create_task")`                       |                                         |
+| Mark task done                  | `engram_memory(action:"update_task", status:"done")`        |                                         |
+| Record a convention             | `engram_memory(action:"add_convention")`                    |                                         |
+| Schedule deferred work          | `engram_memory(action:"schedule_event")`                    |                                         |
+| Lint code against conventions   | `engram_find(action:"lint", content:"...")`                 | Returns `violations[]`                  |
+| Backup the database             | `engram_admin(action:"backup")`                             |                                         |
+| **End every session**           | `engram_session(action:"end")`                              | Be specific: files, functions, blockers |
+
+---
+
+### 8. Sub-Agent Sessions (v1.7+)
+
+When your orchestrator spawns a sub-agent to handle a specific task, use `agent_role: "sub"` to get a lightweight, task-scoped context (~300-500 tokens) instead of the full session boilerplate:
 
-A precise summary is what allows the next session to start immediately without re-reading files or re-asking the user for context.
+```js
+engram_session({
+    action: "start",
+    agent_name: "sub-agent-auth",
+    agent_role: "sub",
+    task_id: 42, // The task ID assigned by the orchestrator
+});
+```
+
+The response includes only:
+
+- The specified task's details (title, description, priority, tags)
+- File notes for files assigned to that task
+- Decisions matching the task's tags
+- Up to 5 relevant conventions
+
+Sub-agents should still call `engram_session(action:"end")` when done and `engram_memory(action:"record_change")` for any edits made.
+
+> **Note:** Sub-agent mode is auto-activated when `agent_role: "sub"` is passed. No separate configuration needed.
+
+<!-- ENGRAM_INSTRUCTIONS_END -->
 
 ---
 
@@ -879,6 +1044,62 @@ engram_memory({
 
 ---
 
+## Troubleshooting
+
+### Windows: `'engram' is not recognized` when using `npx`
+
+If your Windows username contains special characters (tildes `~`, spaces, accented letters, etc.), `npx` may fail to resolve the binary:
+
+```
+'engram' is not recognized as an internal or external command,
+operable program or batch file.
+```
+
+**Cause:** `npx` downloads packages to a temp directory under your user profile (e.g., `C:\Users\~ RG\AppData\Local\npm-cache\_npx\...`). Special characters — especially tildes — are misinterpreted as DOS 8.3 short-path prefixes, and spaces compound the issue. The generated `.cmd` shim fails to resolve its own path.
+
+**Fix — use a global install instead of `npx`:**
+
+```bash
+npm install -g engram-mcp-server
+```
+
+Then update your MCP config to use the binary directly:
+
+```jsonc
+// .vscode/mcp.json (or equivalent for your IDE)
+{
+    "servers": {
+        "engram": {
+            "type": "stdio",
+            "command": "engram-mcp-server",
+            "args": [
+                "--mode=universal",
+                "--project-root",
+                "${workspaceFolder}",
+            ],
+        },
+    },
+}
+```
+
+**Note:** With a global install, you won't get automatic version updates. After publishing a new version, update manually:
+
+```bash
+npm install -g engram-mcp-server@latest
+```
+
+### Database locked or corrupted
+
+If you see `SQLITE_BUSY` or corruption errors:
+
+1. Stop all IDE instances using Engram
+2. Delete the project-local database: `rm -rf .engram/`
+3. Restart — Engram will re-create the database and run all migrations automatically
+
+The global database at `~/.engram/memory.db` can be reset the same way if needed.
+
+---
+
 ## Contributing
 
 We welcome contributions!

package/dist/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAK/D,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,UAAU,EAAE,mBAAmB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG/I,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,IAAI,EAAE,kBAAkB,CAAC;IACzB,GAAG,EAAE,UAAU,CAAC;IAChB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,iBAAiB,CAAC;CAC/B;AAwDD,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAiC7E;AAED,wBAAgB,KAAK,IAAI,YAAY,CAGpC;AAED,wBAAgB,QAAQ,IAAI,YAAY,CAGvC;AAED,wBAAgB,WAAW,IAAI,QAAQ,CAGtC;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAID;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAmBxD;AAkBD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAIvF;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAK5F;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAI/E;AAED,wBAAgB,WAAW,CAAC,UAAU,EAAE,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,CAAC,GAAG,IAAI,CAQvF;AAID,wBAAgB,GAAG,IAAI,MAAM,CAE5B;AAED,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,IAAI,CAGnD;AAED,wBAAgB,uBAAuB,IAAI;IACzC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;CAC1E,GAAG,IAAI,CAWP;AAED,wBAAgB,WAAW,IAAI,MAAM,CAKpC;AAED,wBAAgB,UAAU,IAAI,IAAI,CAIjC;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,SAAS,GAAG,OAAmB,EACxC,KAAK,CAAC,EAAE,MAAM,GACb,IAAI,CAcN"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAK/D,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,UAAU,EAAE,mBAAmB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG/I,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,IAAI,EAAE,kBAAkB,CAAC;IACzB,GAAG,EAAE,UAAU,CAAC;IAChB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,iBAAiB,CAAC;CAC/B;AAwDD,wBAAsB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAiC7E;AAED,wBAAgB,KAAK,IAAI,YAAY,CAGpC;AAED,wBAAgB,QAAQ,IAAI,YAAY,CAGvC;AAED,wBAAgB,WAAW,IAAI,QAAQ,CAGtC;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAID;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAwBxD;AAkBD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAIvF;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAK5F;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAI/E;AAED,wBAAgB,WAAW,CAAC,UAAU,EAAE,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,CAAC,GAAG,IAAI,CAQvF;AAID,wBAAgB,GAAG,IAAI,MAAM,CAE5B;AAED,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,IAAI,CAGnD;AAED,wBAAgB,uBAAuB,IAAI;IACzC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;CAC1E,GAAG,IAAI,CAWP;AAED,wBAAgB,WAAW,IAAI,MAAM,CAKpC;AAED,wBAAgB,UAAU,IAAI,IAAI,CAIjC;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,SAAS,GAAG,OAAmB,EACxC,KAAK,CAAC,EAAE,MAAM,GACb,IAAI,CAcN"}

package/dist/database.js

@@ -133,8 +133,16 @@ export function backupDatabase(destPath) {
     // Ensure destination directory exists
     const destDir = path.dirname(destPath);
     fs.mkdirSync(destDir, { recursive: true });
-    // Use SQLite backup API
-    db.backup(destPath);
+    // Flush WAL to the main DB file so the copy is consistent (ISS-005 fix).
+    // better-sqlite3's db.backup() is async in v9+ and statSync immediately after
+    // it would throw ENOENT before the file is written. Using WAL checkpoint +
+    // synchronous file copy guarantees the backup file is fully written before
+    // we return the path to callers.
+    try {
+        db.pragma("wal_checkpoint(FULL)");
+    }
+    catch { /* WAL may not be in use */ }
+    fs.copyFileSync(getDbPath(), destPath);
     return destPath;
 }
 // ─── Gitignore ───────────────────────────────────────────────────────

package/dist/database.js.map

@@ -1 +1 @@
-{"version":3,"file":"database.js","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -56,7 +56,7 @@ export class SafetyCheckError extends EngramError {
  */
 export class NoActiveSessionError extends EngramError {
     constructor() {
-        super("No active session. Start one with engram_start_session first.", "NO_SESSION");
+        super('No active session. Call engram_session({ action: "start" }) first.', "NO_SESSION");
         this.name = "NoActiveSessionError";
     }
 }

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,kCAAkC;AAClC,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACzB,IAAI,CAAS;IACb,OAAO,CAA2B;IAE3C,YAAY,OAAe,EAAE,OAAe,cAAc,EAAE,OAAiC;QACzF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,WAAW;IAC1C,YAAY,MAAc,EAAE,EAAmB;QAC3C,KAAK,CAAC,GAAG,MAAM,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QAClE,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAChC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,WAAW;IAC5C,YAAY,OAAe,EAAE,OAAiC;QAC1D,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAClC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,WAAW;IAC1C,YAAY,OAAe,EAAE,OAAiC;QAC1D,KAAK,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAChC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,gBAAiB,SAAQ,WAAW;IAC7C,YAAY,eAAuB;QAC/B,KAAK,CAAC,iCAAiC,eAAe,eAAe,EAAE,cAAc,EAAE,EAAE,eAAe,EAAE,CAAC,CAAC;QAC5G,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACnC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,WAAW;IACjD;QACI,KAAK,CAAC,+DAA+D,EAAE,YAAY,CAAC,CAAC;QACrF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACvC,CAAC;CACJ"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,kCAAkC;AAClC,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACzB,IAAI,CAAS;IACb,OAAO,CAA2B;IAE3C,YAAY,OAAe,EAAE,OAAe,cAAc,EAAE,OAAiC;QACzF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,WAAW;IAC1C,YAAY,MAAc,EAAE,EAAmB;QAC3C,KAAK,CAAC,GAAG,MAAM,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QAClE,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAChC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,WAAW;IAC5C,YAAY,OAAe,EAAE,OAAiC;QAC1D,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAClC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,aAAc,SAAQ,WAAW;IAC1C,YAAY,OAAe,EAAE,OAAiC;QAC1D,KAAK,CAAC,OAAO,EAAE,gBAAgB,EAAE,OAAO,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAChC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,gBAAiB,SAAQ,WAAW;IAC7C,YAAY,eAAuB;QAC/B,KAAK,CAAC,iCAAiC,eAAe,eAAe,EAAE,cAAc,EAAE,EAAE,eAAe,EAAE,CAAC,CAAC;QAC5G,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACnC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,WAAW;IACjD;QACI,KAAK,CAAC,oEAAoE,EAAE,YAAY,CAAC,CAAC;QAC1F,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACvC,CAAC;CACJ"}

package/dist/installer/config-writer.d.ts

@@ -4,8 +4,12 @@ export declare function getInstallerVersion(): string;
 /**
  * Generate the Engram server entry tailored to a specific IDE's requirements.
  * Includes _engram_version so the installer can detect upgrades and legacy installs.
+ *
+ * @param ide        IDE definition (controls type, cmd wrapper, etc.)
+ * @param universal  When true, adds --mode=universal and --project-root to args.
+ *                   Uses IDE-appropriate workspace variable when available.
  */
-export declare function makeEngramEntry(ide: IdeDefinition): Record<string, any>;
+export declare function makeEngramEntry(ide: IdeDefinition, universal?: boolean): Record<string, any>;
 /**
  * Read and parse a JSON config file. Returns null if file doesn't exist or is invalid.
  */
@@ -25,7 +29,7 @@ export type InstallResult = "added" | "upgraded" | "exists" | "legacy-upgraded";
  *   "upgraded"       — updated from an older tracked version to the current one
  *   "legacy-upgraded" — entry existed but had no _engram_version (pre-tracking era), now stamped
  */
-export declare function addToConfig(configPath: string, ide: IdeDefinition): InstallResult;
+export declare function addToConfig(configPath: string, ide: IdeDefinition, universal?: boolean): InstallResult;
 /**
  * Remove the Engram entry from a config file.
  * Returns true if the entry was found and removed, false if not present.

package/dist/installer/config-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-writer.d.ts","sourceRoot":"","sources":["../../src/installer/config-writer.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,yFAAyF;AACzF,wBAAgB,mBAAmB,IAAI,MAAM,CAQ5C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqBvE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAMrE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI,CAG3D;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,iBAAiB,CAAC;AAEhF;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,aAAa,CA2BjF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAgBhF"}
+{"version":3,"file":"config-writer.d.ts","sourceRoot":"","sources":["../../src/installer/config-writer.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,yFAAyF;AACzF,wBAAgB,mBAAmB,IAAI,MAAM,CAQ5C;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,EAAE,SAAS,UAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA8B1F;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAMrE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI,CAG3D;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,iBAAiB,CAAC;AAEhF;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,EAAE,SAAS,UAAQ,GAAG,aAAa,CA2BpG;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAgBhF"}

package/dist/installer/config-writer.js

@@ -18,24 +18,36 @@ export function getInstallerVersion() {
 /**
  * Generate the Engram server entry tailored to a specific IDE's requirements.
  * Includes _engram_version so the installer can detect upgrades and legacy installs.
+ *
+ * @param ide        IDE definition (controls type, cmd wrapper, etc.)
+ * @param universal  When true, adds --mode=universal and --project-root to args.
+ *                   Uses IDE-appropriate workspace variable when available.
  */
-export function makeEngramEntry(ide) {
+export function makeEngramEntry(ide, universal = false) {
     const entry = {};
     // Some IDEs require explicit "type": "stdio"
     if (ide.requiresType) {
         entry.type = "stdio";
     }
+    // Build args
+    const baseArgs = ["-y", "engram-mcp-server"];
+    if (universal) {
+        baseArgs.push("--mode=universal");
+    }
     // Windows cmd /c wrapper for npx (npx is a .cmd on Windows)
     if (ide.requiresCmdWrapper) {
         entry.command = "cmd";
-        entry.args = ["/c", "npx", "-y", "engram-mcp-server"];
+        entry.args = ["/c", "npx", ...baseArgs];
     }
     else {
         entry.command = "npx";
-        entry.args = ["-y", "engram-mcp-server"];
+        entry.args = [...baseArgs];
     }
     // Version stamp — used by the installer to detect upgrades and legacy installs
     entry._engram_version = getInstallerVersion();
+    if (universal) {
+        entry._engram_mode = "universal";
+    }
     return entry;
 }
 /**
@@ -66,12 +78,12 @@ export function writeJson(filePath, data) {
  *   "upgraded"       — updated from an older tracked version to the current one
  *   "legacy-upgraded" — entry existed but had no _engram_version (pre-tracking era), now stamped
  */
-export function addToConfig(configPath, ide) {
+export function addToConfig(configPath, ide, universal = false) {
     let config = readJson(configPath) || {};
     const key = ide.configKey;
     if (!config[key])
         config[key] = {};
-    const newEntry = makeEngramEntry(ide);
+    const newEntry = makeEngramEntry(ide, universal);
     const currentVersion = newEntry._engram_version;
     if (config[key].engram) {
         const existingVersion = config[key].engram._engram_version;