v1.12.0 — Android Studio Support + Installer UX Redesign

v1.12.0 — Android Studio Support + Installer UX Redesign

Released: v1.12.0 — March 6, 2026

Overview

v1.12.0 adds Android Studio as the 14th supported IDE and completely redesigns the interactive installer experience. The installer now auto-detects the current IDE and shows a focused status panel instead of prompting to install across all IDEs. Project root detection, scope defaults, and multi-version config handling are all improved. Zero breaking changes. No schema migration.

557 tests pass.

---

What's New

Android Studio MCP Support (14th IDE)

Android Studio now has full stdio-based MCP support via the installer. Despite official docs describing HTTP-only transport, real-world testing confirms stdio transport works identically to other JetBrains-family IDEs.

Key details:

• Version-specific config discovery — resolveGlobalPaths() globs %APPDATA%\Google\AndroidStudio*\mcp.json (Windows) / ~/Library/Application Support/Google/AndroidStudio*/mcp.json (Mac), finding all installed versions automatically
• Install writes to ALL discovered versions — e.g., AndroidStudio2024.1, 2024.2, 2024.3, 2025.1
• enabled: true required — Android Studio requires this field in each MCP server entry; the installer adds it automatically via extraEntryFields
• Environment detection — STUDIO_VM_OPTIONS env var identifies when the installer is running from within Android Studio
• Config key — uses "mcpServers" (not "servers")

npx -y engram-mcp-server install --ide androidstudio

Installer UX Redesign

The interactive installer has been completely rebuilt with a modern, focused experience:

Focused Status Panel — When an IDE is detected from the terminal environment, the installer shows a compact status panel with all relevant information instead of asking "install for all IDEs?":

  ──────────────────────────────────────────────────────────────
  🧠 Engram MCP Installer  v1.12.0
  ──────────────────────────────────────────────────────────────
  Detected IDE  : VS Code (GitHub Copilot)
  Config file   : C:\Users\dev\.vscode\mcp.json
  Database root : C:\Users\dev\my-project  (git repository)
  Installed     : v1.11.0  ⬆  v1.12.0 available
  ──────────────────────────────────────────────────────────────

  What would you like to do?

    1. Update Engram to v1.12.0 in VS Code (GitHub Copilot)
    2. Enter a custom config directory...
    3. Install to other IDEs on this system (3 found)...
    4. Cancel

Project Root Auto-Detection — When installing to a local (project-level) config, the installer walks up from cwd looking for project markers (.git, package.json, Cargo.toml, go.mod, pyproject.toml, build.gradle, pom.xml, .engram). If found with high confidence, it pre-fills the path and asks for confirmation. Users can accept, reject, or type a different path.

Scope Default Fixed — The scope prompt now defaults to local (project-level), matching Decision #20. Previously it defaulted to global, contradicting the recommended configuration.

Improved --check Output — --check now shows ALL version-specific global config paths for IDEs like Android Studio (previously only showed the first found path and stopped).

Improved --list Detection — --list now uses the same robust engram detection logic as the rest of the installer (checks command and args fields for "engram", not just the exact key name).

Code Quality

• Extracted shared helpers from the installer monolith: makeColors(), semverCmp(), fetchNpmLatest(), detectProjectRootForDisplay(), resolveIdeInstallStatus()
• Centralized resolveIdeGlobalPaths() in ide-detector.ts — single source of truth for resolving global paths including resolveGlobalPaths() dynamic discovery
• IdeDefinition interface extended with resolveGlobalPaths?() and extraEntryFields? for IDE-specific customization
• makeEngramEntry() now spreads ide.extraEntryFields into the config entry

---

Files Changed

File	Change
src/installer/ide-configs.ts	Added resolveGlobalPaths, extraEntryFields to IdeDefinition; added androidstudio entry with glob discovery
src/installer/ide-detector.ts	Added resolveIdeGlobalPaths() export; Android Studio detection via STUDIO_VM_OPTIONS
src/installer/config-writer.ts	makeEngramEntry() spreads ide.extraEntryFields
src/installer/index.ts	Full UX redesign: status panel, project root detection, scope fix, menu system, shared helpers
tests/installer/installer.test.ts	Updated scope assertion for resolveGlobalPaths
README.md	Added Android Studio to overview, --ide values, config key note; added manual config section
llms.txt	Added Android Studio to compatible IDE list

---

Upgrade

No configuration changes required. No schema migration.

npx -y engram-mcp-server install

---

v1.11.0 — Developer Experience: Params Coercion, Observations & Session Efficiency

v1.11.0 — Developer Experience: Params Coercion, Observations & Session Efficiency

Released: v1.11.0 — March 6, 2026

Overview

v1.11.0 is a focused developer-experience release addressing the top pain points found during a systematic DX audit. It eliminates an entire class of MCP client serialization errors, adds a lightweight record_observation action as a semantic alternative to misusing record_decision, and cuts session-start token overhead by ~40%. Six bug fixes are included. Zero breaking changes.

557 tests pass. Schema migrated to V24.

---

What's New

Params Coercion — Full Coverage (WS3)

All MCP clients (VS Code Copilot, Cursor, Claude Desktop, universal mode) can now pass arrays without errors. Previously 9 Zod fields were missing coercion, causing intermittent "must be object" or silent parse failures at ~20% failure rate on complex calls.

Fixed fields:

Tool	Field	Type
record_decisions_batch	decisions[].tags	string[]
record_decisions_batch	decisions[].affected_files	string[]
checkpoint	relevant_files	string[]
agent_sync	specializations	string[]
create_task / update_task	depends_on	number[]
update_task	blocked_by, add_blocks, add_blocked_by	number[]
export (admin)	ids	number[]

New utility: coerceNumberArray() in src/utils.ts — mirrors coerceStringArray() for integer array fields.

Universal mode fix (critical): HandlerCapturer bypasses Zod z.preprocess() transforms entirely, so all per-field coercions were silently skipped in universal mode. A new coerceParams() function in src/modes/universal.ts now pre-processes params before dispatch, handling JSON-stringified arrays and nested object arrays.

New Action: record_observation (WS2)

A semantically correct, lightweight action for factual observations — no rationale required.

engram_memory({
  action: "record_observation",
  observation: "The FTS5 index is rebuilt on every migration run",
  context: "src/migrations.ts",
  category: "codebase",     // codebase | behavior | performance | dependency | general
  tags: ["fts", "migrations"],
  source: "agent"           // agent | user | automated
})

Retrieve with:

engram_memory({ action: "get_observations", session_id: 42, category: "codebase", limit: 20 })

Observations are included in search when scope is "all" or "observations". Full-text search supported via FTS5 (fts_observations virtual table, schema V24).

Why this matters: Agents were forced to misuse record_decision for factual notes (no rationale needed). record_observation is the correct semantic type: lighter than a decision, heavier than a file note.

Session Verbosity Overhaul (WS1)

The summary verbosity tier has been restructured to reduce session-start output by ~40% (from ~800 to ~500 tokens) while making all content available on-demand.

Changes:

Setting	Before	After
Max decisions shown	5 (120-char each)	3 (80-char each)
Max conventions shown	10	6
Max changes shown	5 (with timestamp)	3 (no timestamp)
git_log in response	Included	Removed (use what_changed)
counts object	Absent	Added

New counts object in every summary response:

{
  "counts": {
    "decisions": 18,
    "conventions": 6,
    "tasks": 4,
    "changes": 47,
    "files": 129
  }
}

minimal tier now includes top_decision and top_task so agents get actionable context even in the lowest-verbosity tier.

All cap values extracted to named constants in src/constants.ts for easy tuning.

Bug Fixes (WS4)

• dump finding persistence: The dump action's finding hint previously generated a fake ephemeral ID and stored nothing to the database. It now persists to the new observations table.
• Session end observation count: session end stats now include observations_recorded alongside changes, decisions, and tasks.

Instance Visibility System

Instance enrollment in the dashboard discovery service is now permanent across restarts. Previously, instances would lose their enrollment on server restart and require re-registration. The dashboard now reliably discovers all registered instances without polling gaps.

---

Schema

V24 adds:

CREATE TABLE observations (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  session_id INTEGER,
  timestamp TEXT NOT NULL,
  observation TEXT NOT NULL,
  context TEXT,
  category TEXT DEFAULT 'general',
  tags TEXT,
  source TEXT,
  FOREIGN KEY (session_id) REFERENCES sessions(id)
);
CREATE INDEX idx_observations_session ON observations(session_id);
CREATE INDEX idx_observations_category ON observations(category);
-- FTS5 virtual table
CREATE VIRTUAL TABLE fts_observations USING fts5(observation, context, content='observations', content_rowid='id');

---

Agent Instructions Update

The .github/copilot-instructions.md (and global CLAUDE.md) has been updated:

• Documents coerceNumberArray() for integer array Zod fields
• Documents the record_observation / get_observations actions in the tool catalog
• Clarifies universal mode Zod preprocessing behaviour

---

Upgrade

No configuration changes required. The schema migration runs automatically on first start. All existing data is preserved.

npx -y engram-mcp-server install

---

v1.9.3 — IDE Config Paths, Correct Config Keys & Docs Refresh

v1.9.3 — IDE Config Paths, Correct Config Keys & Docs Refresh

Released: v1.9.3 — March 3, 2026

Overview

v1.9.3 is a correctness and documentation release. The automated installer config paths for all 13 supported IDEs have been audited and corrected against live source/docs research. README installation docs have been completely rewritten with accurate per-IDE config snippets, correct config key names, and a new section documenting Engram's database location behaviour.

Zero breaking changes. No schema migration required.

---

What's Fixed

IDE MCP Config Paths & Keys Corrected (src/installer/ide-configs.ts)

Every IDE entry was verified against its official documentation and source code:

• Config key "servers" vs "mcpServers" — VS Code, Visual Studio, and JetBrains use "servers". All other IDEs use "mcpServers". Previously several entries had the wrong key.
• Correct file paths for all 13 IDEs: VS Code (.vscode/mcp.json local / {APPDATA}/Code/User/mcp.json global), Cursor (.cursor/mcp.json local / ~/.cursor/mcp.json global), Windsurf (~/.codeium/windsurf/mcp_config.json), Antigravity (~/.gemini/antigravity/mcp_config.json), Claude Code (~/.claude.json global / .mcp.json local), Claude Desktop ({APPDATA}/Claude/claude_desktop_config.json), Visual Studio (.vs/mcp.json or .mcp.json local / %USERPROFILE%\.mcp.json global), Cline, Roo Code, Gemini CLI, Firebase Studio, Trae, JetBrains.
• workspaceVar and --project-root injection — IDEs that expand workspace variables (VS Code, Cursor, Visual Studio, Trae) now correctly inject --project-root=${workspaceFolder} (or ${SolutionDir}) into args.
• Windows cmd wrapper — Claude Code and Claude Desktop on Windows correctly use "command":"cmd","args":["/c","npx",...] since npx is a .cmd file.

Installer Default Scope Changed to Global (src/installer/index.ts)

When an IDE supports both local and global MCP config, the installer now defaults to global (was local). Global is the correct default for most users who want all their projects in that IDE to use Engram without per-project setup. The scope prompt was also updated to clarify that scope selection only controls WHERE the MCP is registered — not where Engram stores its database.

README Installation Section Rewrite (README.md)

• All 13 IDE manual-config <details> blocks rewritten with correct JSON snippets, config key names, and file paths.
• New Engram Database Location section documents the database path resolution logic: project-local .engram/memory.db by default, global fallback ~/.engram/global/memory.db when no project root is found, and how npm install -g + global IDE config interacts with this.
• --ide values in Option 2 updated to include all 13 IDs: vscode, cursor, windsurf, antigravity, claudecode, claudedesktop, visualstudio, cline, roocode, geminicli, firebasestudio, trae, jetbrains.

---

Files Changed

File	Change
src/installer/ide-configs.ts	Corrected config paths, config keys, workspaceVar, and cmd wrapper for all 13 IDEs
src/installer/index.ts	Default scope → global; updated scope prompt with DB location clarification
README.md	Installation section rewrite: all 13 IDEs, correct config keys, DB location docs

---

Upgrade

npx -y engram-mcp-server@latest install

No configuration migration needed. Re-run the installer to pick up updated config paths if any were wrong in your previous installation.

---

v1.9.2 - Cross-Instance Sharing Hotfix

Fix: Cross-Instance Sharing Broken for IDE-Suffixed Databases

IDEs like Antigravity, Cursor, and others write the database as \memory-antigravity.db\ or \memory-cursor.db\ rather than \memory.db. The instance registry was storing \project_root\ but not the actual DB filename, causing all cross-instance reads to fail silently or return wrong data.

Fixed

• *\get_instance_info\ ignored \instance_id* — always returned the calling instance's own info regardless of which instance was requested. Now correctly routes to the foreign instance via the registry.
• \query_instance\ all types fell back to decisions — \conventions, \ile_notes, \ asks, \sessions, \changes\ all silently returned decisions. Added \query_type\ param with full type-switch routing.
• IDE-suffixed DB filenames not discoverable — added
  esolveDbPath()\ fallback that scans <project_root>/.engram/\ for \memory*.db\ files sorted by mtime when \db_path\ is absent from an older registry entry.
• *Registry entries missing \db_path* — \heartbeat()\ now writes \db_path\ back if the field is absent, retroactively patching entries written by older Engram versions.

Upgrade

\\�ash
npx -y engram-mcp-server@latest install
\\

No data migration needed. Existing instances will have \db_path\ written to their registry entries on the next heartbeat.

Full release notes: https://github.com/keggan-std/Engram/blob/main/RELEASE_NOTES.md

v1.9.1 — Project Root Detection Hotfix

Critical Fix for Global-Only IDEs

IDEs that spawn MCP servers from the user's home directory (Antigravity, Windsurf, Claude Desktop, Cline, JetBrains) were sharing a single database across all projects — causing data leakage and privacy violations.

Fixed

• Home directory bootstrap trap — ~/.engram/\ was a strong project marker that made HOME look like a project root. Removed.
• Home directory blocked — \isHomeDirectory()\ guard added to all \indProjectRoot()\ tiers
• Env var injection — Installer now injects \ENGRAM_PROJECT_ROOT\ env var for global-only IDEs
• Runtime \project_root\ override — Agents can pass \project_root\ at session start to redirect the DB to the correct location (with automatic data migration)
• Interactive fallback — When all detection fails, the agent is prompted to ask the user for the project path
• Deliberate global installs — No warning when user intentionally chose global installation

Upgrade

\\�ash
npx -y engram-mcp-server@latest install
\\

Existing data at ~/.engram/\ is automatically migrated to the correct project directory on the next session start.

Full release notes: https://github.com/keggan-std/Engram/blob/main/RELEASE_NOTES.md

v1.9.0 — Built-in Visual Dashboard

Overview

v1.9.0 introduces the Engram Dashboard — a built-in React SPA that gives you a live, visual window into your agent's memory. Start it with a single command, get a real-time view of all sessions, tasks, decisions, changes, conventions, file notes, events, milestones, and settings — no CLI required.

Zero breaking changes. All MCP tool behaviour is unchanged.

Quick start

\\�ash
npm run dashboard
\\

The terminal prints the full URL including a secure auth token. Open it in your browser.

What's New

• React 19 + Vite 6 SPA — 11 pages: Dashboard, Tasks, Decisions, Changes, Conventions, File Notes, Sessions, Events, Milestones, Audit, Settings
• HTTP API layer (--mode=http) — 11 typed REST endpoint groups with token auth
• WebSocket live updates — real-time pushes when any memory record changes; live badge in header
• Cmd+K palette — keyboard-driven quick navigation
• Theme toggle — dark/light mode, persisted to \localStorage\
• Toast stack — non-blocking notifications for live events
• Detail panel — click any row to expand full content
• Adaptive columns — table columns use %\ widths, scale at any viewport

Stats

• 285 tests total (89 new)
• 1 new server mode (--mode=http)
• 11 REST endpoint groups + WebSocket broadcaster
• 11 dashboard pages

See RELEASE_NOTES.md for the full detailed changelog.

v1.7.3 — Smart Project Root Detection & DB Hardening

What's New in v1.7.3

🔧 Critical Fix: Wrong Project Root Detection

Engram was resolving the project root to the IDE's install directory (e.g. \AppData\Local\Programs\Antigravity) instead of the actual workspace, causing \SQLITE_BUSY\ crashes on startup.

Smart Project Root — 6-Tier Priority Chain

1. --project-root=\ CLI argument (e.g. injected by IDE via \)
2. \ENGRAM_PROJECT_ROOT\ / \PROJECT_ROOT\ environment variables
3. \git rev-parse --show-toplevel\ (authoritative for git repos)
4. Walk up from cwd — strong markers only (.git, .engram)
5. Walk up from cwd — soft markers (\package.json, etc.) with blocklist filtering
6. ~/.engram/global/\ fallback with warning log

Blocklist: IDE & System Path Rejection

Paths like \AppData\Local\Programs, \Program Files, /Applications, npm globals, etc. are now explicitly rejected so IDE install dirs can never be mistaken for a project root.

Database Hardening

• \�usy_timeout = 5000\ is now set first in all DB open paths (was set too late → zero retry budget → instant crash)
• \SQLITE_BUSY\ is no longer confused with \SQLITE_CORRUPT\ — it is now re-thrown cleanly instead of triggering the WAL recovery path
• \initDatabase\ is now correctly synchronous (better-sqlite3 is a sync library)
• \global-db.ts\ also sets \�usy_timeout\ before other pragmas

IDE Workspace Variable Injection

VS Code, Cursor, and Visual Studio MCP configs now receive --project-root=\ (or \) so the correct project root is passed from the IDE at spawn time.

Invalid Config Recovery

If an IDE config file has corrupt/invalid JSON, Engram now backs it up (.invalid..bak) and writes a fresh config rather than crashing the installer.

Other Fixes

• \ide-detector: no longer flags HOME / APPDATA as valid IDE parent dirs
• \�nsureGitignore: writes a self-contained .engram/.gitignore\ instead of appending to the root .gitignore\
• \�wait runInstaller()\ — was previously missing \�wait, causing silent installer failures
• \scripts/\ removed from published npm package (legacy file no longer needed)
• Version detection now tries 3 relative paths for resilience in non-standard installs

v1.7.2 — Hotfix: Enum Validation, Targeted Broadcasts & API Correctness

Overview

v1.7.2 is a hotfix release addressing 20 bugs discovered during a systematic functional audit of the v1.7.0 tool surface. No new features — only correctness and reliability fixes. Zero breaking changes.

ID	Area	Fix	Commit
ISS-001–015	API correctness	Various: report, backup, tasks, events, session error messages	8dd7bce
ISS-007	Universal Mode	discover action used full-string includes instead of BM25	061b790
ISS-016	what_changed	"session_start" used as literal SQL string (always 0 results)	061b790
ISS-017	create_task	priority accepted any string — no enum validation	c89edb1
ISS-018	broadcast	target_agent column missing; all agents received all broadcasts	b0efaf2
ISS-019	record_change	change_type + impact_scope accepted any string	c89edb1
ISS-020	Universal Mode	set_file_notes crashed when dependencies was a JSON string	13af958

---

What's Fixed

🔒 Enum Validation — change_type, impact_scope, priority

record_change, create_task, and related actions now reject invalid values with a clear Zod validation error.

Valid values:

• 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

The broadcasts table now has a target_agent TEXT column (migration v16). The broadcast INSERT stores it; agent_sync filters WHERE target_agent IS NULL OR target_agent = ?. Directed messages are now correctly scoped to their intended recipient.

⏱️ what_changed { since: "session_start" } Fixed

The "session_start" sentinel is now resolved to the session's started_at ISO timestamp before the SQL query executes. Previously always returned 0 results.

🧩 Universal Mode — Array Coercion Bypass 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 handles both native arrays and JSON-encoded strings at the repository layer.

✅ API Correctness (ISS-001 – ISS-015)

• generate_report returns a full project knowledge summary
• get_global_knowledge returns correct data shape
• backup no longer throws ENOENT
• get_tasks { status: "all" } returns all tasks regardless of status
• acknowledge_event { approved: false } snoozes the event (was a no-op)
• config { op: "get", key: X } returns only that key's value (was all config)
• record_milestone version prefix no longer doubled (v1.7.2 not vv1.7.2)
• dump no longer creates a spurious file_path: "dump" change record
• NoActiveSessionError message uses the correct v1.7 syntax
• checkpoint { progress: string } accepts plain strings in progress
• update_task { id: N } uses id (not task_id)

---

Test Coverage

119/119 tests passing across 7 test files. Phase 7 added coverage for all previously untested repositories (ConfigRepo, EventsRepo, AgentsRepo, BroadcastsRepo, SnapshotRepo), EventTriggerService, and dispatcher smoke tests.

---

Full changelog: RELEASE_NOTES.md
npm: https://www.npmjs.com/package/engram-mcp-server

v1.7.0 — Token Efficiency & Intelligence Overhaul

v1.7.0 — Token Efficiency & Intelligence Overhaul

Released: v1.7.0

Overview

v1.7.0 is a focused precision release with six improvement tracks, all targeting token efficiency, MCP compatibility, and agent intelligence — with zero breaking changes to the existing 4-dispatcher API surface.

Track	Improvement	Token Impact
P1.1	Fixed MCP validation crash (z.array(z.unknown()))	Unblocks Copilot/Cursor clients
P1.3	Default search limit 20 → 8	~60% fewer search tokens
P1.4	Convention capping by verbosity	Up to 100% fewer convention tokens in nano/minimal modes
P2	Tiered tool catalog (Tier 0/1/2)	~93% catalog reduction after first session
P3	Sub-agent mode (agent_role:"sub")	~80% smaller session start (~300-500t vs ~2,000t)
P4	Universal mode (--mode=universal)	Single 80-token tool schema for constrained clients
P5	Deleted 660 lines of dead legacy code	Smaller footprint, cleaner codebase
P6	Smarter lint, exec_summary hints, AR-06 update	Better conventions signal-to-noise

---

What's New

🔧 P1.1 — MCP Validation Crash Fix (Critical)

z.array(z.unknown()) generates a JSON Schema without an items property. Some MCP clients (VS Code Copilot, Cursor) validate tool input schemas strictly and reject calls with malformed array schemas, producing a silent crash.

Fix: All three affected input arrays in engram_memory (files, changes, decisions) now use fully typed Zod schemas with .passthrough() — generating valid {type: "array", items: {...}} JSON Schema output.

⚡ P1.3 — Default Search Limit: 20 → 8

Introduced DEFAULT_SEARCH_LIMIT = 8 in constants.ts. All engram_memory(action:"search") calls now default to returning 8 results instead of 20. Agents rarely need more than 8 hits for a lookup. Still overridable via explicit limit param (up to MAX_SEARCH_RESULTS = 50).

📋 P1.4 — Convention Capping by Verbosity

Active conventions are now sorted (enforced-first, then most-recent-first) and capped before delivery:

Verbosity	Convention cap
nano	0
minimal	5
summary	10
full	all

total_conventions count and a hint are always returned so agents know when the cap is active.

🗂️ P2 — Tiered Tool Catalog

buildToolCatalog(tier: 0|1|2) replaces the previous flat catalog:

• Tier 0 — Action names only, list format (~80 tokens)
• Tier 1 — Names + one-line descriptions (~400 tokens)
• Tier 2 — Full parameter documentation (~1,200 tokens)

selectCatalogTier(agent_name, verbosity) tracks delivery history per agent. New agents get Tier 2 once, then drop to Tier 1, then Tier 0 on repeat calls. Agents can always request a higher tier via engram_find(action:"catalog").

🤖 P3 — Sub-Agent Session Mode

New agent_role:"sub" + task_id parameters on engram_session(action:"start"). When set, returns a focused context slice instead of the full session boilerplate:

• The specified task's full details
• Files declared in begin_work for that task
• Recent decisions matching task tags
• Conventions (capped at 5)

Results in ~300-500 token session starts vs ~2,000+ for full context. Ideal for sub-agents spawned to handle a specific task within a larger orchestrated workflow.

🌐 P4 — Universal Mode (--mode=universal)

New server-level opt-in mode that exposes a single engram tool (~80 token schema) instead of the standard 4-dispatcher surface:

# CLI activation
npx engram-mcp-server --mode=universal --project-root /your/project

# Environment variable activation
ENGRAM_MODE=universal npx engram-mcp-server --project-root /your/project

Architecture (src/modes/universal.ts):

• HandlerCapturer — duck-typed SDK server stub captures handler callbacks from all 4 dispatcher registrations without creating actual MCP tools. Zero subprocess overhead.
• fuzzyResolveAction() — BM25-style substring scoring routes unknown action names to the best match (threshold 0.5), with ranked alternatives in suggestions[].
• universalizeResponse() — rewrites all engram_memory(action:"X") refs in response text to engram({action:"X"}) for consistency.
• discover action — filtered catalog search within the single tool.

Standard 4-dispatcher behaviour is completely unchanged when the flag is absent.

🗑️ P5 — Dead Code Removal (660 Lines)

registerSessionTools() — a 660-line legacy function that registered the old v1.5 individual tools (engram_start_session, engram_end_session, engram_record_change, etc.) — was deleted. It was exported but had zero call-sites in index.ts since the v1.6 dispatcher migration. Confirmed dead via full codebase grep.

sessions.ts shrinks from 904 → 316 lines.

🔍 P6 — Intelligence Improvements

P6.3 — executive_summary nudge: When set_file_notes is called without providing executive_summary, the success response now includes a hint field explaining the value of writing one. AR-06 in the live agent rules also updated to make the requirement explicit.

P6.4 — Smarter convention linting: engram_find(action:"lint") now:

• Extracts backtick-quoted identifiers as high-priority match tokens (exact symbol matching)
• Uses whole-word regex instead of substring includes (no more false positives on shared stems)
• Expanded STOP_WORDS list for cleaner scoring

---

v1.6.1 — Universal Thin Client & Test Infrastructure Fix

Released: patch bump on top of v1.6.0.

What's New

engram-universal-client Package (packages/engram-universal-thin-client/)

A new optional companion package that acts as an MCP proxy facade for token-constrained environments. Instead of exposing 4 dispatcher tools (~1,600 token schema), it exposes a single engram tool (~80 tokens) and routes requests to the upstream dispatcher via BM25 semantic action matching.

Architecture:

• src/router.ts — ROUTE_TABLE mapping 60+ action names to the correct upstream dispatcher tool
• src/bm25.ts — MiniSearch BM25 index; resolveAction() exact-matches or fuzzy-resolves any action, suggestActions() returns ranked alternatives
• src/server.ts — MCP facade server; proxies to the real Engram MCP subprocess, handles both nested ({action, params}) and flat ({action, ...}) parameter shapes
• index.ts — CLI entry point: npx engram-universal-client --project-root <path>

Install (Claude Desktop / Cursor / Windsurf):

{
    "mcpServers": {
        "engram": {
            "command": "npx",
            "args": [
                "-y",
                "engram-universal-client",
                "--project-root",
                "/your/project"
            ]
        }
    }
}

Note: This package is a proof-of-concept. Known limitations and planned improvements are tracked in docs/engram-token-efficiency-master-plan.md.

---

Test Infrastructure — Schema Sync Fix

tests/helpers/test-db.ts previously hand-rolled a v4-era schema inline. Any migration past v4 that added columns (file_mtime at v5, content_hash at v13, executive_summary at v14) caused 13 test failures across batch.test.ts and repos.test.ts.

Fix: createTestDb() now calls runMigrations(db) directly — the test database is always at the current schema version with zero manual maintenance.

---

v1.6.0 — Lean Surface, Dispatcher Architecture & 8 New Feature Tracks

Engram v1.6.0 is the largest release to date — fourteen combined feature tracks. This entry covers the eight new tracks delivered on top of the existing agent safety and session handoff infrastructure already documented below.

---

Summary of New Tracks

#	Track	Branch
1	Lean 4-Tool Dispatcher (50+ → 4 tools, ~95% token reduction)	feat/v1.6-lean-surface
2	Persistent Checkpoints (offload working memory mid-session)	feat/v1.6-checkpoint
3	Hash-Based Staleness Detection (SHA-256 content_hash)	feat/v1.6-staleness-enhanced
4	Tiered Verbosity + nano mode + executive_summary	feat/v1.6-tiered-verbosity
5	Live Agent Rules from GitHub README (7-day cache)	feat/v1.6-readme-rules
6	Quality: lint action, install_hooks/remove_hooks, cascade warning	feat/v1.6-quality
7	Agent Specialization Routing + route_task + match_score	feat/v1.6-multi-agent
8	Thin-Client Proxy for Anthropic defer_loading beta	feat/v1.6-thin-client

---

Track 1 — Lean 4-Tool Dispatcher (feat/v1.6-lean-surface)

Problem

Engram exposed 50+ individual MCP tools. Every tool's full JSON Schema was injected into the model's context at session start, consuming ~32,500 tokens per call — roughly 8-17% of a typical context window, before any code was read.

Solution

All tools collapsed into 4 dispatcher tools, each routed via an action parameter...

v1.6.0 — Lean Surface, Dispatcher Architecture & 8 New Feature Tracks

v1.6.0 — Lean Surface, Dispatcher Architecture & 8 New Feature Tracks

Engram v1.6.0 is the largest release to date — fourteen combined feature tracks. This entry covers the eight new tracks delivered on top of the existing agent safety and session handoff infrastructure already documented below.

---

Summary of New Tracks

#	Track	Branch
1	Lean 4-Tool Dispatcher (50+ → 4 tools, ~95% token reduction)	feat/v1.6-lean-surface
2	Persistent Checkpoints (offload working memory mid-session)	feat/v1.6-checkpoint
3	Hash-Based Staleness Detection (SHA-256 content_hash)	feat/v1.6-staleness-enhanced
4	Tiered Verbosity + nano mode + executive_summary	feat/v1.6-tiered-verbosity
5	Live Agent Rules from GitHub README (7-day cache)	feat/v1.6-readme-rules
6	Quality: lint action, install_hooks/remove_hooks, cascade warning	feat/v1.6-quality
7	Agent Specialization Routing + route_task + match_score	feat/v1.6-multi-agent
8	Thin-Client Proxy for Anthropic defer_loading beta	feat/v1.6-thin-client

---

Track 1 — Lean 4-Tool Dispatcher (feat/v1.6-lean-surface)

Problem

Engram exposed 50+ individual MCP tools. Every tool's full JSON Schema was injected into the model's context at session start, consuming ~32,500 tokens per call — roughly 8-17% of a typical context window, before any code was read.

Solution

All tools collapsed into 4 dispatcher tools, each routed via an action parameter:

• engram_session — Session lifecycle (start, end, handoff, acknowledge_handoff, get_history)
• engram_memory — All memory operations (34+ actions, see Tools Reference)
• engram_admin — Maintenance, git hooks, backup, export, config
• engram_find — Tool catalog search + convention linting

Impact

• Schema token overhead: ~32,500 → ~1,600 (~95% reduction)
• All previous tools still available — routed via action parameter
• engram_find lets agents discover action names without memorising the full surface
• Every existing tool behaviour is preserved

---

Track 2 — Persistent Checkpoints (feat/v1.6-checkpoint)

New actions on engram_memory

• checkpoint — Saves current_understanding, progress_percentage, key_findings, next_steps, and relevant file_paths to a new checkpoints DB table (V12 migration).
• get_checkpoint — Retrieves the most recent checkpoint for the current session (or a specific session_id).

When to use

Call checkpoint when approaching context limits without wanting to end the session. Future context can pick up from where the previous one left off.

Schema (V12)

CREATE TABLE checkpoints (
  id INTEGER PRIMARY KEY,
  session_id TEXT NOT NULL,
  current_understanding TEXT,
  progress_percentage INTEGER,
  key_findings TEXT,         -- JSON array
  next_steps TEXT,           -- JSON array
  relevant_files TEXT,       -- JSON array
  created_at TEXT DEFAULT (datetime('now'))
)

---

Track 3 — Hash-Based Staleness Detection (feat/v1.6-staleness-enhanced)

Problem

mtime-based staleness missed edits where the file content changed but the timestamp did not (formatters, git ops, some editors).

Solution

set_file_notes now accepts and stores a content_hash (SHA-256). get_file_notes computes a fresh hash and compares:

State	confidence
hash matches mtime matches	high
mtime matches but hash differs	stale (content silently changed)
mtime changed	medium
>7 days old	low

Schema (V13)

Added content_hash TEXT column to file_notes.

---

Track 4 — Tiered Verbosity + nano + executive_summary (feat/v1.6-tiered-verbosity)

New verbosity level: nano

Returns only session ID, record counts, agent_rules, and tool_catalog. Under 100 tokens. Use when context is critically constrained.

New executive_summary field

set_file_notes now accepts executive_summary: a 2–3 sentence micro-summary of the file purpose. Surfaced in get_file_notes (minimal+ verbosity).

Schema (V14)

Added executive_summary TEXT column to file_notes.

Verbosity matrix

Level	Returns
nano	session_id, counts, agent_rules, tool_catalog
minimal	nano + summary, recently changed files, high-priority tasks
summary	minimal + decisions, conventions, open tasks, suggested_focus
full	everything including detailed file notes and all task tags

---

Track 5 — Live Agent Rules from GitHub README (feat/v1.6-readme-rules)

What changed

start_session now returns an agent_rules array parsed dynamically from the Engram README hosted on GitHub.

Behaviour

• On first call, fetches https://raw.githubusercontent.com/…/README.md and parses the JSON block between <!-- AGENT_RULES_START --> and <!-- AGENT_RULES_END -->.
• Caches the result to .engram/agent_rules_cache.json for 7 days.
• Falls back to hardcoded AGENT_RULES in src/tools/find.ts if fetch fails or cache is expired but network is unavailable.
• Rules update automatically when the README changes — no agent reinstall required.

---

Track 6 — Quality Improvements (feat/v1.6-quality)

Convention Linting

engram_find(action:"lint", content:"...") checks any code/text against all active project conventions and returns a violations[] array with rule references.

Git Hook Management via engram_admin

• engram_admin(action:"install_hooks") — Writes the Engram post-commit hook to .git/hooks/post-commit
• engram_admin(action:"remove_hooks") — Removes the Engram hook entry from .git/hooks/post-commit

Decision Cascade Warning

engram_memory(action:"update_decision") now returns a cascade_warning field listing all decisions that have depends_on pointing at the changed decision, so agents know to review dependents.

---

Track 7 — Agent Specialization Routing (feat/v1.6-multi-agent)

Changes to agent_sync

Now accepts specializations: string[] — skill/domain tags for the agent (e.g. ["typescript","database","migration"]). Stored in agents table (V15 migration: added specializations TEXT column).

New action: route_task

engram_memory({ action: "route_task", task_id }) finds the best-matched registered agent for a task by comparing task tags against registered agent specializations using intersection scoring.

Returns: { best_match: { agent_id, agent_name, match_score }, all_candidates: [...] }

Updated action: claim_task

Now returns advisory match_score and optional match_warning comparing the claiming agent's specializations against the task's tags. Does not block claiming — advisory only.

Schema (V15)

Added specializations TEXT column to agents.

---

Track 8 — Thin-Client Proxy for Anthropic defer_loading (feat/v1.6-thin-client)

What it is

A new separate package at packages/engram-thin-client/ that proxies all Engram tool calls via the Anthropic SDK with defer_loading: true beta.

How it works

Tools are registered using Anthropic's defer_loading beta flag, meaning zero tool schema tokens are consumed upfront. The model discovers tools on-demand. A BM25 search index lets the Claude model identify which Engram action to call based on natural language.

Who it's for

Anthropic API users only (any agent using Claude models via the Anthropic TypeScript SDK directly). Cursor, Copilot, Gemini, and GPT agents continue to use the MCP server directly — they still benefit from the lean 4-tool surface but do not get zero-upfront-cost.

Installation

npm install engram-thin-client

---

Breaking Changes

None. All eight new tracks are additive. Existing tool calls, IDE configs, and databases continue to work. The schema auto-migrates from any previous version through V12–V15 on first startup.

---

Migration Summary (V12–V15)

Version	Change
V12	checkpoints table (checkpoint, get_checkpoint)
V13	file_notes.content_hash column (hash-based staleness)
V14	file_notes.executive_summary column (tiered verbosity)
V15	agents.specializations column (route_task, match_score)

---

v1.6.0 — Agent Safety, Session Handoffs, Knowledge Graph & Diagnostics

Engram v1.6.0 delivers six feature tracks developed in parallel, focused on making multi-agent workflows safer, making cross-session context transfers seamless, and giving agents deeper visibility into what they and their peers are doing.

Seven feature branches were developed and merged into develop:

---

Breaking Changes

None. v1.6.0 is fully backwards-compatible. All existing tool calls, IDE configs, and databases continue to work unchanged. The schema auto-migrates from V6 through V7–V11 on first startup.

---

F1/F2 — Agent Safety (feature/v1.6-agent-safety)

File Locking

Two new tools prevent concurrent write conflicts between parallel agents:

• engram_lock_file — Acquires an exclusive write lock on a file with a reason and optional expiry. Fails immediately if another agent holds the lock, returning who holds it.
• engram_unlock_file — Releases the lock. Locks auto-expire after 30 minutes (configurable via FILE_LOCK_DEFAULT_TIMEOUT_MINUTES).
• engram_get_file_notes (updated) — Now surfaces lock_status for every file: locked, expired, or none. The locking agent's ID is included so other agents know whom to coordinate with.

Pending Work Intent

• engram_begin_work — Record your intent before touching a file (agent ID, description, file list). Stored in a new pending_work table...