engram-mcp-server 1.7.3 → 1.9.1

package/README.md

@@ -18,6 +18,10 @@
 
 ---
 
+> ⭐ **If Engram saves you tokens and context, give it a star — it helps other developers find it.**
+
+---
+
 ## 📋 Table of Contents
 
 - [Overview](#overview)
@@ -25,12 +29,14 @@
 - [How Engram Works?](#how-engram-works)
 - [Installation](#installation)
 - [Features](#features)
+- [Dashboard](#dashboard)
 - [Architecture](#architecture)
 - [Tools Reference](#tools-reference)
-- [Using with AI Agents](#using-with-ai-agents)
+- [AI Agent Instructions](#ai-agent-instructions)
 - [Multi-Agent Workflows](#multi-agent-workflows)
 - [Contributing](#contributing)
 - [Security](#security)
+- [Author](#author)
 - [License](#license)
 
 ---
@@ -39,7 +45,7 @@
 
 **Engram** is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that gives AI coding agents persistent memory across sessions. Instead of re-reading files, re-discovering architecture, and re-learning conventions every time a session starts, the agent calls `engram_session(action:"start")` and instantly receives everything it needs.
 
-It operates seamlessly as a background brain for popular AI tools like **Claude Code**, **Claude Desktop**, **Cursor**, **Windsurf**, **Cline**, **Trae IDE**, and **GitHub Copilot** (VS Code & Visual Studio).
+It operates seamlessly as a background brain for popular AI tools like **Claude Code**, **Claude Desktop**, **Cursor**, **Windsurf**, **Cline**, **Trae IDE**, **Antigravity IDE**, and **GitHub Copilot** (VS Code & Visual Studio).
 
 ---
 
@@ -55,6 +61,17 @@ Every AI coding agent is **stateless by default**. Each new session starts from
 
 Engram solves this by providing a **persistent brain** using a native SQLite (WAL mode) database. An AI agent should only need to deeply review a file once. When you ask it to change something, it should already know where to go.
 
+### How Engram Compares
+
+| Tool | Approach | Local / No cloud | MCP native | Multi-agent | Works today |
+|------|----------|:---:|:---:|:---:|:---:|
+| **Engram** | Structured SQLite memory | ✅ | ✅ | ✅ | ✅ |
+| mem0 | Cloud vector DB | ❌ | ⚠️ wrapper | ⚠️ | ✅ |
+| MemGPT / Letta | In-context manipulation | ✅ | ❌ | ❌ | ✅ |
+| Plain `CLAUDE.md` | Static text file | ✅ | ✅ | ❌ | ✅ |
+
+Engram is the only solution that is **local-first, MCP-native, multi-agent-ready, and structured** (queryable, rankable, exportable) — not just a text file appended to every prompt.
+
 ---
 
 ## How Engram Works?
@@ -177,6 +194,8 @@ npm install -g engram-mcp-server
 engram install --ide <your-ide>
 ```
 
+Available `--ide` values: `claudecode`, `claudedesktop`, `vscode`, `cursor`, `windsurf`, `antigravity`, `visualstudio`, `cline`, `trae`, `jetbrains`
+
 > **Note:** During install you may see `npm warn deprecated prebuild-install@7.1.3`. This is a cosmetic warning from a transitive dependency used to download SQLite prebuilt binaries. It does not affect functionality and is safe to ignore.
 
 ### Option 3: Universal Mode — Built-In Single-Tool Mode (v1.7+)
@@ -510,6 +529,60 @@ No cloud. No telemetry. No authentication surface. Memory lives in a local SQLit
 
 ---
 
+## Dashboard
+
+Engram ships with a built-in **visual dashboard** — a React SPA that gives you a live window into your agent's memory without touching the CLI.
+
+### Starting the Dashboard
+
+```bash
+npm run dashboard
+```
+
+This builds the server, installs dashboard dependencies, and starts both the API and the Vite dev server concurrently. The terminal prints the full URL including the auth token:
+
+```
+[api]  Engram HTTP server running on port 7432
+[ui]   VITE ready in 320ms
+
+  ➜  Local:   http://localhost:5173?token=<token>
+```
+
+Open the printed URL directly — the token is embedded in the link and required for access.
+
+> **Security note:** The dashboard is intended for local development. The token prevents other local processes from reading your memory data. Do not expose ports `5173` or `7432` to a network.
+
+### Pages
+
+| Page | Description |
+|------|-------------|
+| **Dashboard** | Overview — session count, task totals, decisions, and change volume at a glance. Clickable stat cards navigate to the relevant page. Instance cards show per-database stats with expand/collapse. Activity chart displays recent change volume. |
+| **Tasks** | All persistent work items with status, priority, and tags. |
+| **Decisions** | Architectural decisions with rationale, affected files, and dependency chains. |
+| **Changes** | Full change history — every file edit recorded by agents and git hooks. |
+| **Conventions** | Project standards enforced every session. |
+| **File Notes** | Agent-generated file intelligence — purpose, layer, complexity, and executive summary. |
+| **Sessions** | Past session summaries with agent names and timestamps. |
+| **Events** | Scheduled and triggered events, including context-pressure warnings. |
+| **Milestones** | Named project milestones. |
+| **Audit** | Raw event log for debugging and auditing. |
+| **Settings** | Runtime config management — view and update config keys live. |
+
+### Dashboard Features
+
+- **Live updates** — WebSocket connection delivers real-time pushes when any memory record changes. A live badge in the header shows connection status.
+- **Cmd+K palette** — keyboard-driven quick navigation to any page.
+- **Theme toggle** — dark/light mode, persisted to `localStorage`.
+- **Toast notifications** — non-blocking feedback for actions and live events.
+- **Detail panel** — click any table row to expand full content in a side panel.
+- **Token auth** — every HTTP request and WebSocket connection is validated against the `?token=<value>` query parameter.
+
+### Requirements
+
+The dashboard is included in the package but its frontend dependencies are installed on first run. Node.js v18+ and an internet connection for the initial `npm install` are required. Subsequent runs use the cached install.
+
+---
+
 ## Architecture
 
 ```mermaid
@@ -625,111 +698,56 @@ Engram v1.7.0 exposes **4 dispatcher tools** (or 1 tool in `--mode=universal`).
 
 ---
 
-## Using with AI Agents
-
-> **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 — Session Rules
-
-**4 dispatcher tools:** `engram_session` · `engram_memory` · `engram_admin` · `engram_find`  
-Unknown action? → `engram_find({ query: "what I want to do" })`  
-Universal mode? All actions route through a single `engram` tool — call `engram({ action: "start" })` etc.
-
-Follow these rules **every session, every project**.
-
-> ⚠️ **MANDATORY: Call this at the start of EVERY new chat — no exceptions.**  
-> Without it, the agent is stateless. All prior context (decisions, file notes, tasks, conventions) will be invisible.
-
----
-
-### Session Start — ALWAYS FIRST, BEFORE any action
+## AI Agent Instructions
 
-```js
-engram_session({
-    action: "start",
-    agent_name: "claude",
-    verbosity: "summary",
-    focus: "topic if known",
-});
-```
-
-- **Every new chat. Every time. No skipping.** Even for "quick" questions — context is loaded in <1 second.
-- Use `verbosity: "summary"` always. Never `"full"`.
-- Act on everything returned: `previous_session`, `active_decisions` (binding), `active_conventions` (enforce), `open_tasks`, `abandoned_work`, `agent_rules` (binding), `triggered_events`.
-- If `update_available`: ask user → update (`npx -y engram-mcp-server install`), skip, postpone 7d, or disable.
+> **Important:** AI agents have a strong tendency to skip Engram tool calls — particularly `engram_session(action:"start")` at the beginning of a chat and `engram_memory(action:"get_file_notes")` before opening files — and proceed directly to reading and reviewing. This defeats the purpose of the memory system entirely. **For any session that involves file exploration or codebase work, explicitly instruct the agent in your prompt to use Engram before acting.** A simple addition like *"Before doing anything, start an Engram session. Before opening any file, check its Engram notes first."* is sufficient to enforce compliance.
 
----
+> **Copy-paste ready.** The block below can be dropped directly into `CLAUDE.md`, `.github/copilot-instructions.md`, Cursor Rules, or any equivalent agent instruction file — no reformatting needed.
 
-### Before Opening a File
+<!-- ENGRAM_INSTRUCTIONS_START -->
 
+### Session Start — ALWAYS FIRST
 ```js
-engram_memory({ action: "get_file_notes", file_path: "..." });
+engram_session({ action: "start", agent_name: "claude", verbosity: "summary", focus: "topic if known", project_root: "/absolute/path/to/project" })
 ```
+- `project_root` (optional): Pass the absolute path to the workspace when the IDE may not set cwd to the project directory (e.g. Antigravity, Windsurf, Claude Desktop). Engram will re-initialize its database at the correct location. Omit if the IDE already provides `${workspaceFolder}` (VS Code, Cursor).
 
-- `high` → use notes, skip opening. `medium` → open only if precision matters. `stale` / no notes → read file, then immediately call `set_file_notes` with `executive_summary`.
-
----
-
-### Before Design/Architecture Decisions
+Act on everything returned: `active_decisions` (binding), `active_conventions` (enforce), `open_tasks`, `agent_rules`, `triggered_events`.  
+Unknown action? → `engram_find({ query: "what I want to do" })`
 
+### Before Opening Any File
 ```js
-engram_memory({ action: "search", query: "...", scope: "decisions" });
-// or: engram_memory({ action: "get_decisions" })
+engram_memory({ action: "get_file_notes", file_path: "..." })
 ```
+`high` confidence → use notes, skip opening. `stale`/absent → read file, then immediately call `set_file_notes` with `executive_summary`.
 
-Follow existing decisions. To change one, call `record_decision` with `supersedes: <id>`. Always record new decisions with `rationale`.
-
----
-
-### After Editing Files
-
+### Before Architecture/Design Decisions
 ```js
-engram_memory({
-    action: "record_change",
-    changes: [{ file_path, change_type, description, impact_scope }],
-});
+engram_memory({ action: "search", query: "...", scope: "decisions" })
 ```
+Follow existing decisions. Supersede with `record_decision({ ..., supersedes: <id> })`. Always include `rationale`.
 
-`change_type`: created | modified | refactored | deleted | renamed | moved | config_changed  
-`impact_scope`: local | module | cross_module | global. Batch all changes in one call.
-
----
-
-### Mid-Session (context pressure)
-
+### After Every File Edit
 ```js
-engram_memory({ action: "checkpoint", current_understanding: "...", progress: "...", relevant_files: [...] })
-engram_memory({ action: "check_events" }) // fires at 50/70/85% context fill
+engram_memory({ action: "record_change", changes: [{ file_path, change_type, description, impact_scope }] })
 ```
+`change_type`: `created|modified|refactored|deleted|renamed|moved|config_changed`  
+`impact_scope`: `local|module|cross_module|global` — batch all edits in one call.
 
----
+### Documentation Rule
+Multi-step plans, analyses, proposals → write to `docs/<name>.md`. Chat gets summary only.
 
 ### Session End — ALWAYS LAST
-
-1. Record any unrecorded changes.
-2. Mark done tasks: `engram_memory({ action: "update_task", id: <n>, status: "done" })`
-3. Create tasks for incomplete work.
-4. Record new conventions.
-5. `engram_session({ action: "end", summary: "files/functions touched, pending work, blockers" })`
-
----
+1. Record unrecorded changes
+2. Mark done tasks: `engram_memory({ action: "update_task", id: N, status: "done" })`
+3. Create tasks for incomplete work
+4. `engram_session({ action: "end", summary: "files touched, pending work, blockers" })`
 
 ### Sub-Agent Sessions (v1.7+)
-
-Use `agent_role: "sub"` for lightweight task-scoped context (~300–500 tokens):
-
 ```js
-engram_session({
-    action: "start",
-    agent_name: "sub-agent-auth",
-    agent_role: "sub",
-    task_id: 42,
-});
+engram_session({ action: "start", agent_name: "sub-agent-X", agent_role: "sub", task_id: 42 })
 ```
-
-Returns only: the assigned task, its file notes, matching decisions, and up to 5 relevant conventions. Sub-agents still call `record_change` and `session end` as normal.
+Returns only the assigned task, its file notes, matching decisions, and up to 5 conventions (~300–500 tokens). Sub-agents still call `record_change` and `session end` as normal.
 
 <!-- ENGRAM_INSTRUCTIONS_END -->
 
@@ -946,15 +964,21 @@ The short version: Engram has no network-facing server, no authentication surfac
 
 ---
 
+## Author
+
+Built by **Renald Shao** (aka **Keggan Student**) — [GitHub](https://github.com/keggan-std) · [Behance](https://www.behance.net/renaldshao)
+
+---
+
 ## License
 
 This project is licensed under the [MIT License](LICENSE).
 
-Copyright &copy; 2026 Keggan Student, Tanzania.
+Copyright &copy; 2026 Renald Shao (aka Keggan Student), Tanzania.
 
 ---
 
 <div align="center">
   <em>Because your AI agent shouldn't have amnesia.</em><br/>
-  <strong>Copyright &copy; 2026 Keggan Student — Tanzania</strong>
+  <strong>Copyright &copy; 2026 Renald Shao (aka Keggan Student) — Tanzania</strong>
 </div>

package/dist/constants.d.ts

@@ -3,7 +3,7 @@ export declare const SERVER_VERSION: string;
 export declare const TOOL_PREFIX = "engram";
 export declare const DB_DIR_NAME = ".engram";
 export declare const DB_FILE_NAME = "memory.db";
-export declare const DB_VERSION = 15;
+export declare const DB_VERSION = 22;
 export declare const MAX_FILE_TREE_DEPTH = 5;
 export declare const MAX_FILE_TREE_ENTRIES = 500;
 export declare const MAX_SEARCH_RESULTS = 50;
@@ -24,7 +24,7 @@ export declare const EXCLUDED_DIRS: Set<string>;
  * STRONG markers: unambiguous project boundaries. Found → return immediately.
  * These never appear in IDE install directories or npm global dirs.
  */
-export declare const STRONG_PROJECT_MARKERS: readonly [".git", ".engram"];
+export declare const STRONG_PROJECT_MARKERS: readonly [".git"];
 /**
  * SOFT markers: typically present in real projects but also in Electron/Node
  * app install dirs. Only used after strong markers are exhausted, AND only if
@@ -42,6 +42,12 @@ export declare const PROJECT_MARKERS: string[];
  * is rejected so we don't mistake an IDE's own install dir for a project root.
  */
 export declare const BLOCKED_PATH_PATTERNS: RegExp[];
+/**
+ * Returns true if the given directory is the user's home directory.
+ * The home dir is never a valid project root — no one's "project" is ~/.
+ * This prevents the bootstrap trap where ~/.engram/ makes HOME look like a project.
+ */
+export declare function isHomeDirectory(dirPath: string): boolean;
 export declare const NPM_REGISTRY_URL = "https://registry.npmjs.org/engram-mcp-server/latest";
 export declare const GITHUB_REPO = "keggan-std/Engram";
 export declare const GITHUB_RELEASES_URL = "https://github.com/keggan-std/Engram/releases";
@@ -53,5 +59,20 @@ export declare const CFG_AUTO_UPDATE_CHANGELOG = "auto_update_changelog";
 export declare const CFG_AUTO_UPDATE_SKIP_VERSION = "auto_update_skip_version";
 export declare const CFG_AUTO_UPDATE_REMIND_AFTER = "auto_update_remind_after";
 export declare const CFG_AUTO_UPDATE_NOTIFY_LEVEL = "auto_update_notify_level";
+export declare const CFG_INSTANCE_ID = "instance_id";
+export declare const CFG_INSTANCE_LABEL = "instance_label";
+export declare const CFG_INSTANCE_CREATED_AT = "instance_created_at";
+export declare const CFG_MACHINE_ID = "machine_id";
+export declare const CFG_SHARING_MODE = "sharing_mode";
+export declare const CFG_SHARING_TYPES = "sharing_types";
+export declare const CFG_SENSITIVE_KEYS = "sensitive_keys";
+export declare const CFG_HTTP_TOKEN = "http_token";
+export declare const INSTANCE_REGISTRY_DIR = ".engram";
+export declare const INSTANCE_REGISTRY_FILE = "instances.json";
+export declare const HEARTBEAT_INTERVAL_MS = 60000;
+export declare const STALE_THRESHOLD_MS: number;
+export declare const PRUNE_THRESHOLD_MS: number;
+export declare const DEFAULT_SHARING_MODE = "none";
+export declare const DEFAULT_SHARING_TYPES: string[];
 export declare const LAYER_PATTERNS: Record<string, RegExp[]>;
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,WAAW,sBAAsB,CAAC;AAC/C,eAAO,MAAM,cAAc,EAAE,MAAqB,CAAC;AACnD,eAAO,MAAM,WAAW,WAAW,CAAC;AAGpC,eAAO,MAAM,WAAW,YAAY,CAAC;AACrC,eAAO,MAAM,YAAY,cAAc,CAAC;AACxC,eAAO,MAAM,UAAU,KAAK,CAAC;AAI7B,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AACzC,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAChD,eAAO,MAAM,eAAe,YAAY,CAAC;AACzC,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAC/C,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,eAAO,MAAM,iCAAiC,KAAK,CAAC;AACpD,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAGnC,eAAO,MAAM,aAAa,aAqBxB,CAAC;AAKH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,8BAGzB,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,UAkBhC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,UAG3B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,EAmBzC,CAAC;AAGF,eAAO,MAAM,gBAAgB,wDAAwD,CAAC;AACtF,eAAO,MAAM,WAAW,sBAAsB,CAAC;AAC/C,eAAO,MAAM,mBAAmB,kDAAkD,CAAC;AACnF,eAAO,MAAM,uBAAuB,mEAAmE,CAAC;AAGxG,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AACzD,eAAO,MAAM,0BAA0B,2BAA2B,CAAC;AACnE,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AACjE,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AACjE,eAAO,MAAM,4BAA4B,6BAA6B,CAAC;AACvE,eAAO,MAAM,4BAA4B,6BAA6B,CAAC;AACvE,eAAO,MAAM,4BAA4B,6BAA6B,CAAC;AAGvE,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAYnD,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,WAAW,sBAAsB,CAAC;AAC/C,eAAO,MAAM,cAAc,EAAE,MAAqB,CAAC;AACnD,eAAO,MAAM,WAAW,WAAW,CAAC;AAGpC,eAAO,MAAM,WAAW,YAAY,CAAC;AACrC,eAAO,MAAM,YAAY,cAAc,CAAC;AACxC,eAAO,MAAM,UAAU,KAAK,CAAC;AAG7B,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AACzC,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAChD,eAAO,MAAM,eAAe,YAAY,CAAC;AACzC,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAC/C,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,eAAO,MAAM,iCAAiC,KAAK,CAAC;AACpD,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAGnC,eAAO,MAAM,aAAa,aAqBxB,CAAC;AAKH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,mBAQzB,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,UAkBhC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,UAG3B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,EAmBzC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGxD;AAGD,eAAO,MAAM,gBAAgB,wDAAwD,CAAC;AACtF,eAAO,MAAM,WAAW,sBAAsB,CAAC;AAC/C,eAAO,MAAM,mBAAmB,kDAAkD,CAAC;AACnF,eAAO,MAAM,uBAAuB,mEAAmE,CAAC;AAGxG,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AACzD,eAAO,MAAM,0BAA0B,2BAA2B,CAAC;AACnE,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AACjE,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AACjE,eAAO,MAAM,4BAA4B,6BAA6B,CAAC;AACvE,eAAO,MAAM,4BAA4B,6BAA6B,CAAC;AACvE,eAAO,MAAM,4BAA4B,6BAA6B,CAAC;AAGvE,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAC7C,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AACnD,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAC7D,eAAO,MAAM,cAAc,eAAe,CAAC;AAC3C,eAAO,MAAM,gBAAgB,iBAAiB,CAAC;AAC/C,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AACjD,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AACnD,eAAO,MAAM,cAAc,eAAe,CAAC;AAG3C,eAAO,MAAM,qBAAqB,YAAY,CAAC;AAC/C,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AACvD,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAC5C,eAAO,MAAM,kBAAkB,QAAa,CAAC;AAC7C,eAAO,MAAM,kBAAkB,QAAuB,CAAC;AAGvD,eAAO,MAAM,oBAAoB,SAAS,CAAC;AAC3C,eAAO,MAAM,qBAAqB,UAA+B,CAAC;AAGlE,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAYnD,CAAC"}

package/dist/constants.js

@@ -2,6 +2,7 @@
 // Engram MCP Server — Constants
 // ============================================================================
 import { readFileSync } from "fs";
+import os from "os";
 import { fileURLToPath } from "url";
 import path from "path";
 const _pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
@@ -12,8 +13,7 @@ export const TOOL_PREFIX = "engram";
 // Database
 export const DB_DIR_NAME = ".engram";
 export const DB_FILE_NAME = "memory.db";
-export const DB_VERSION = 15; // V7 agent-safety, V8 ctx-pressure, V9 knowledge-graph, V10 handoffs, V11 tool_call_log
-// V12 checkpoints, V13 content_hash, V14 executive_summary, V15 agent specializations
+export const DB_VERSION = 22; // V18 http-token, V19 soft-delete, V20 audit-log, V21 import-jobs, V22 annotations
 // Limits
 export const MAX_FILE_TREE_DEPTH = 5;
 export const MAX_FILE_TREE_ENTRIES = 500;
@@ -61,7 +61,12 @@ export const EXCLUDED_DIRS = new Set([
  */
 export const STRONG_PROJECT_MARKERS = [
     ".git",
-    ".engram", // already-initialised Engram project
+    // NOTE: .engram was removed from STRONG markers in v1.9.1 hotfix.
+    // It is self-referential — Engram creates .engram/, so its presence
+    // cannot prove a *project* boundary.  When cwd = HOME, any stale
+    // ~/.engram/ made the home directory look like a project root,
+    // causing all global-only IDEs to share one database.  Real projects
+    // always have .git or a soft marker (package.json, etc.).
 ];
 /**
  * SOFT markers: typically present in real projects but also in Electron/Node
@@ -120,6 +125,15 @@ export const BLOCKED_PATH_PATTERNS = [
     /[/\\]lib[/\\]node_modules[/\\]/i,
     /[/\\]node_modules\.bin[/\\]/i,
 ];
+/**
+ * Returns true if the given directory is the user's home directory.
+ * The home dir is never a valid project root — no one's "project" is ~/.
+ * This prevents the bootstrap trap where ~/.engram/ makes HOME look like a project.
+ */
+export function isHomeDirectory(dirPath) {
+    const norm = (p) => p.replace(/\\/g, "/").replace(/\/$/, "").toLowerCase();
+    return norm(dirPath) === norm(os.homedir());
+}
 // Update check
 export const NPM_REGISTRY_URL = "https://registry.npmjs.org/engram-mcp-server/latest";
 export const GITHUB_REPO = "keggan-std/Engram";
@@ -133,6 +147,24 @@ export const CFG_AUTO_UPDATE_CHANGELOG = "auto_update_changelog";
 export const CFG_AUTO_UPDATE_SKIP_VERSION = "auto_update_skip_version";
 export const CFG_AUTO_UPDATE_REMIND_AFTER = "auto_update_remind_after";
 export const CFG_AUTO_UPDATE_NOTIFY_LEVEL = "auto_update_notify_level"; // "major" | "minor" | "patch"
+// Config keys — instance identity & cross-instance
+export const CFG_INSTANCE_ID = "instance_id";
+export const CFG_INSTANCE_LABEL = "instance_label";
+export const CFG_INSTANCE_CREATED_AT = "instance_created_at";
+export const CFG_MACHINE_ID = "machine_id";
+export const CFG_SHARING_MODE = "sharing_mode"; // "none" | "read" | "full"
+export const CFG_SHARING_TYPES = "sharing_types"; // JSON array of table names
+export const CFG_SENSITIVE_KEYS = "sensitive_keys"; // JSON array of decision/convention IDs marked sensitive
+export const CFG_HTTP_TOKEN = "http_token"; // Bearer token for dashboard API (file fallback: .engram/token)
+// Instance registry
+export const INSTANCE_REGISTRY_DIR = ".engram";
+export const INSTANCE_REGISTRY_FILE = "instances.json";
+export const HEARTBEAT_INTERVAL_MS = 60_000; // 60 seconds
+export const STALE_THRESHOLD_MS = 5 * 60_000; // 5 minutes
+export const PRUNE_THRESHOLD_MS = 7 * 24 * 60 * 60_000; // 7 days
+// Sharing defaults
+export const DEFAULT_SHARING_MODE = "none";
+export const DEFAULT_SHARING_TYPES = ["decisions", "conventions"];
 // Architecture layer detection patterns
 export const LAYER_PATTERNS = {
     ui: [/\/(ui|views?|screens?|pages?|components?|widgets?)\//i, /\.(jsx|tsx|vue|svelte)$/],

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,gCAAgC;AAChC,+EAA+E;AAE/E,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC;AAC/F,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;AAEzD,MAAM,CAAC,MAAM,WAAW,GAAG,mBAAmB,CAAC;AAC/C,MAAM,CAAC,MAAM,cAAc,GAAW,IAAI,CAAC,OAAO,CAAC;AACnD,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC;AAEpC,WAAW;AACX,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC;AACrC,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AACxC,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,CAAC,CAAC,wFAAwF;AACxF,sFAAsF;AAEpH,SAAS;AACT,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AACrC,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AACzC,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AACrC,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,CAAC,6EAA6E;AACpH,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AACtC,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AACzC,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAC3C,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AACvC,MAAM,CAAC,MAAM,6BAA6B,GAAG,EAAE,CAAC;AAChD,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC;AACzC,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,CAAC;AAC/C,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC,CAAC,uDAAuD;AACjG,MAAM,CAAC,MAAM,iCAAiC,GAAG,EAAE,CAAC,CAAC,iDAAiD;AACtG,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AACzC,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAEnC,yCAAyC;AACzC,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC;IACnC,MAAM;IACN,SAAS;IACT,OAAO;IACP,KAAK;IACL,SAAS;IACT,SAAS;IACT,eAAe;IACf,cAAc;IACd,OAAO;IACP,MAAM;IACN,KAAK;IACL,KAAK;IACL,KAAK;IACL,aAAa;IACb,OAAO;IACP,OAAO;IACP,QAAQ;IACR,MAAM;IACN,YAAY;IACZ,YAAY;CACb,CAAC,CAAC;AAEH,gEAAgE;AAChE,uEAAuE;AAEvE;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,MAAM;IACN,SAAS,EAAI,qCAAqC;CAC1C,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,cAAc;IACd,cAAc;IACd,kBAAkB;IAClB,iBAAiB;IACjB,qBAAqB;IACrB,YAAY;IACZ,QAAQ;IACR,SAAS;IACT,gBAAgB;IAChB,UAAU;IACV,gBAAgB;IAChB,UAAU;IACV,MAAM;IACN,SAAS;IACT,cAAc;IACd,SAAS;IACT,eAAe;CAChB,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,GAAG,sBAAsB;IACzB,GAAG,oBAAoB;CACxB,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAa;IAC7C,6CAA6C;IAC7C,2CAA2C;IAC3C,wCAAwC;IACxC,sCAAsC;IACtC,sBAAsB;IACtB,+CAA+C;IAC/C,8BAA8B;IAC9B,yCAAyC;IACzC,2BAA2B;IAC3B,kCAAkC;IAClC,2BAA2B;IAC3B,oBAAoB;IACpB,iCAAiC;IACjC,UAAU;IACV,wCAAwC;IACxC,+CAA+C;IAC/C,iCAAiC;IACjC,8BAA8B;CAC/B,CAAC;AAEF,eAAe;AACf,MAAM,CAAC,MAAM,gBAAgB,GAAG,qDAAqD,CAAC;AACtF,MAAM,CAAC,MAAM,WAAW,GAAG,mBAAmB,CAAC;AAC/C,MAAM,CAAC,MAAM,mBAAmB,GAAG,+CAA+C,CAAC;AACnF,MAAM,CAAC,MAAM,uBAAuB,GAAG,gEAAgE,CAAC;AAExG,kCAAkC;AAClC,MAAM,CAAC,MAAM,qBAAqB,GAAG,mBAAmB,CAAC;AACzD,MAAM,CAAC,MAAM,0BAA0B,GAAG,wBAAwB,CAAC;AACnE,MAAM,CAAC,MAAM,yBAAyB,GAAG,uBAAuB,CAAC;AACjE,MAAM,CAAC,MAAM,yBAAyB,GAAG,uBAAuB,CAAC;AACjE,MAAM,CAAC,MAAM,4BAA4B,GAAG,0BAA0B,CAAC;AACvE,MAAM,CAAC,MAAM,4BAA4B,GAAG,0BAA0B,CAAC;AACvE,MAAM,CAAC,MAAM,4BAA4B,GAAG,0BAA0B,CAAC,CAAC,8BAA8B;AAEtG,wCAAwC;AACxC,MAAM,CAAC,MAAM,cAAc,GAA6B;IACtD,EAAE,EAAE,CAAC,uDAAuD,EAAE,yBAAyB,CAAC;IACxF,SAAS,EAAE,CAAC,oDAAoD,CAAC;IACjE,MAAM,EAAE,CAAC,uDAAuD,CAAC;IACjE,IAAI,EAAE,CAAC,yDAAyD,CAAC;IACjE,OAAO,EAAE,CAAC,4CAA4C,CAAC;IACvD,QAAQ,EAAE,CAAC,6CAA6C,CAAC;IACzD,EAAE,EAAE,CAAC,0CAA0C,CAAC;IAChD,IAAI,EAAE,CAAC,2CAA2C,CAAC;IACnD,IAAI,EAAE,CAAC,wCAAwC,EAAE,kBAAkB,CAAC;IACpE,MAAM,EAAE,CAAC,sCAAsC,CAAC;IAChD,KAAK,EAAE,CAAC,oCAAoC,EAAE,oBAAoB,CAAC;CACpE,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}

package/dist/database.d.ts

@@ -1,6 +1,6 @@
 import type { Database as DatabaseType } from "better-sqlite3";
 import { type Repositories } from "./repositories/index.js";
-import { CompactionService, ProjectScanService, GitService, EventTriggerService, UpdateService, AgentRulesService } from "./services/index.js";
+import { CompactionService, ProjectScanService, GitService, EventTriggerService, UpdateService, AgentRulesService, InstanceRegistryService, CrossInstanceService, SensitiveDataService } from "./services/index.js";
 export interface Services {
     compaction: CompactionService;
     scan: ProjectScanService;
@@ -8,13 +8,34 @@ export interface Services {
     events: EventTriggerService;
     update: UpdateService;
     agentRules: AgentRulesService;
+    registry: InstanceRegistryService;
+    crossInstance: CrossInstanceService;
+    sensitiveData: SensitiveDataService;
 }
-export declare function initDatabase(projectRoot: string): DatabaseType;
+export declare function initDatabase(projectRoot: string, ideKey?: string): DatabaseType;
 export declare function getDb(): DatabaseType;
 export declare function getRepos(): Repositories;
 export declare function getServices(): Services;
 export declare function getProjectRoot(): string;
 export declare function getDbPath(): string;
+/**
+ * Re-initialize the database at a new project root.
+ *
+ * Used when the agent provides the correct project_root at session start
+ * and the server originally resolved to the wrong location (e.g. the
+ * global fallback because the IDE spawned from $HOME).
+ *
+ * If the old DB at the incorrect location contains data, this function
+ * copies it to the new location so previous sessions/decisions/etc. survive.
+ *
+ * @returns {{ migrated: boolean; oldPath: string; newPath: string; message: string }}
+ */
+export declare function reinitDatabase(newProjectRoot: string, ideKey?: string): {
+    migrated: boolean;
+    oldPath: string;
+    newPath: string;
+    message: string;
+};
 /**
  * Create a backup copy of the database file.
  * Uses SQLite's backup API for a safe, consistent copy.

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;AA0ED,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,CAiC9D;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;AAmCD,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,uBAAuB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAKpN,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;IAC9B,QAAQ,EAAE,uBAAuB,CAAC;IAClC,aAAa,EAAE,oBAAoB,CAAC;IACpC,aAAa,EAAE,oBAAoB,CAAC;CACrC;AA4ED,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CA6D/E;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;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG;IACvE,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,CA4DA;AAID;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAwBxD;AAmCD,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"}