MindGate MCP
You can use MindGate MCP as a local-first persistent memory and context gateway for AI agents.
Store architectural decisions, bugfixes, conventions, context, tags, workspaces, source agent, and superseding memory IDs.
Update memories in place, change status, deprecate decisions, or delete outdated records.
Search and recall memories using FTS5 BM25 with workspace, category, status, and global-inclusion filters.
Log cross-agent session handoffs with summaries, next steps, and active files.
Save and retrieve developer preferences or global coding rules.
Compact historical session handoffs into milestone summaries.
Generate workspace rules files such as
AGENTS.md,CLAUDE.md,.cursorrules,.windsurfrules, andMINDGATE_CONTEXT.md, with backups and overwrite protection.Export portable JSON snapshots of memories, session handoffs, and preferences.
List workspaces with memory counts and timestamps.
Get the local web dashboard URL for visual memory management, search, lifecycle management, compaction, and backups.
Benefit from runtime validation and best-effort secret redaction on write paths.
Provides a Git post-commit hook adapter that records commit messages and active files into MindGate memory for persistent project context tracking.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MindGate MCP recall our auth architecture decisions for this workspace"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🧠 MindGate MCP (v1.5.0) — بوابة العقل
Local-First Persistent Memory & Context Gateway for AI Agents (Model Context Protocol).
🇪🇬 اقرأ التوثيق باللغة العربية · 🖥️ Landing page · 📦 npm · 🎬 58-second demo
💡 Why MindGate MCP?
AI coding and workflow agents (Antigravity, Cursor, Claude Desktop, Windsurf, Cline) suffer from two critical limitations:
Cross-Session Context Amnesia: Every new chat starts from zero—forgetting architectural decisions, debugging root causes, coding conventions, and session handoffs.
Secret Leakage & Prompt-Infected Stores: Memory servers that persist raw agent output can end up storing leaked API keys and acting as a confused-deputy for poisoned instructions.
MindGate MCP addresses both in a single, zero-cloud local server:
🗄️ Blazing-Fast Local SQLite + FTS5 BM25 Search: Instant full-text retrieval of architectural decisions, bugfixes, conventions, preferences, and session handoffs.
🔍 Hybrid Semantic Search (v1.4.0): Combines BM25 keyword search with offline ONNX semantic embeddings (
all-MiniLM-L6-v2, ~23 MB, 384-dim).recall_contextautomatically uses both engines when a query is provided — no network calls, 100% local.🌐 Cross-Lingual Arabic <-> English Search (NEW in v1.5.0): Native Arabic normalization and dual-profile architecture (
defaultbundled +multilingualprofile viamindgate-mcp download-model --multilingual). Allows Arabic queries to semantically retrieve English architectural decisions with >0.72 cosine alignment on CPU.🔄 Decision Superseding & Lifecycle Tracking: Supersede obsolete architectural decisions (
supersedes) or mark them deprecated (deprecate_memory). Agents never follow stale patterns, while historical audit trails remain preserved.📦 Historical Memory Compaction: Automatically compact long chains of historical session handoffs into milestone summaries (
compact_memories) to preserve context without inflating token usage.🖥️ Built-in Local Web Dashboard: Zero-dependency HTTP UI (
mindgate-mcp uiornpm run ui) running locally onhttp://127.0.0.1:4242with Dark/Light themes, Arabic RTL & English LTR switch, live FTS5 search, workspace filtering, and visual context management.🪝 Git Post-Commit Context Adapter: Seamless commit tracking (
mindgate-mcp git-hook install) that logs commit messages and active files directly into MindGate without workflow disruption.🔄 Auto-Compiled Workspace Rules (
AGENTS.md/.cursorrules/CLAUDE.md): Compiles your stored decisions, conventions, and bugfixes into a structured rules file so any AI agent immediately inherits project context. Writes are atomic, existing files are backed up (.bak-<timestamp>), and hand-written files are never overwritten withoutforce: true.✏️ In-Place Memory Updates & Portable JSON Snapshots: Update evolving decisions in place (
update_memory) while keeping FTS5 indexes in sync, and export full JSON backups (export_memory_snapshot).🔒 Secret Redaction On Write: Well-known token patterns (OpenAI, GitHub, AWS, Slack, Google, JWT, PEM private keys) are masked with
[REDACTED:<kind>]before anything touches disk — in memories, session handoffs, and preferences. Tool responses report aredacted_secretscount. Disable withMINDGATE_REDACT_SECRETS=false(not recommended).🛡️ Node2Shell (CVE-2026-111497) Mitigations: stdio-only transport (zero HTTP attack surface), runtime version check against the patched releases (22.23.4 / 24.22.1 / 26.12.1, Bun ≥ 1.4.4), and a best-effort in-process lock of the public
node:zlibBrotli decompression API installed before any other module loads. See SECURITY.md for the honest threat model and limitations.
⚠️ MindGate does not execute shell commands, does not open network sockets, and does not attempt to detect prompt injection in arbitrary text. Memories you store are embedded verbatim into generated rules files — treat stored memories as you would any local notes file, and review generated rules before committing them.
Related MCP server: Sugar Memory
🏛️ Architecture — How MindGate Works

flowchart TB
subgraph Clients["MCP Clients (any of them)"]
A1["Antigravity"]
A2["Cursor"]
A3["Claude Desktop"]
A4["OpenCode / Codex / Windsurf"]
end
subgraph Server["MindGate MCP Server — 100% local"]
direction TB
BOOT["1 · security/bootstrap.ts — first import<br/>locks the node:zlib Brotli API<br/>+ runtime version check (CVE-2026-111497)"]
TOOLS["2 · index.ts — MCP handlers<br/>10 tools · 2 resources · 1 prompt<br/>stdio JSON-RPC only"]
VALID["3 · validation.ts<br/>type + range + size limits<br/>invalid input → isError: true"]
REDACT["4 · security/secretRedactor.ts<br/>sk-…, AKIA…, JWT, PEM → [REDACTED:kind]"]
STORE["5 · db/memoryStore.ts<br/>SQLite (WAL) + FTS5 BM25<br/>triggers keep the index in sync"]
RULES["6 · rulesSync.ts<br/>atomic write + .bak backup<br/>hand-written files protected (sentinel)"]
BOOT --> TOOLS
TOOLS --> VALID
VALID --> REDACT
REDACT --> STORE
VALID --> RULES
STORE --> RULES
end
DB[("Local filesystem<br/>~/.mindgate/mindgate.db<br/>file chmod 600 · dir chmod 700")]
PROJ["Project workspace<br/>AGENTS.md · CLAUDE.md · .cursorrules"]
Clients <-->|"stdio JSON-RPC only<br/>no network · no HTTP"| BOOT
STORE <--> DB
RULES -->|"write / backup"| PROJRequest lifecycle (numbered as in the diagram):
Any MCP client spawns
mindgate-mcpas a child process. All communication is newline-delimited JSON-RPC over stdio — no sockets, no HTTP, no telemetry.The first module evaluated is
src/security/bootstrap.ts(imported before everything else): it hard-locks the publicnode:zlibBrotli decompression API and checks the Node/Bun version against the patched releases for CVE-2026-111497.Every tool call is validated at runtime — types, ranges, size limits, positive IDs. Invalid input returns an MCP tool error (
isError: true) with a descriptive message, never a crash.On write paths (remember / update / session handoff / preferences), secrets are redacted before anything touches disk.
Storage is embedded SQLite + FTS5 (
better-sqlite3) at~/.mindgate/mindgate.db— WAL mode, owner-only permissions. Insert/update/delete triggers keep the FTS index in sync automatically.sync_workspace_rulescompiles memories → Markdown and writes it atomically (temp file + rename) with a timestamped.bak-<timestamp>backup; files without the<!-- mindgate:auto-generated -->marker are never overwritten unlessforce: true.
Trust boundaries: memories are data, not instructions; secret redaction is best-effort pattern matching; the Brotli lock is defense-in-depth. See SECURITY.md for the full threat model.
🛠️ MCP Tools Included (13 Tools)
Tool Name | Description |
| Store a persistent memory (architecture / decision / bugfix / convention / context) with automatic secret redaction and optional |
| Update an existing memory in-place by ID with optional |
| Search memories with FTS5 BM25 ranking, workspace/category filters, and lifecycle |
| Mark an existing memory as deprecated by ID with an optional reason, excluding it from active recall without deletion |
| Compact historical session handoffs into consolidated milestone summaries to reduce token overhead while retaining full context |
| Save a structured session handoff (summary, next steps, active files) for the next agent to resume |
| Get the URL of the local MindGate Web Dashboard ( |
| Generate |
| Export a portable JSON backup of memories, session handoffs, and preferences |
| Save or update a persistent developer preference ( |
| Retrieve all saved preferences, optionally filtered by |
| List all workspaces with memory counts and last-updated timestamps |
| Delete an outdated or superseded memory by its ID |
All tool arguments are validated at runtime; invalid input returns an MCP tool error (isError: true) with a descriptive message instead of a protocol error.
📦 MCP Resources & Prompts
Resources
mindgate://context/latest— Snapshot of recent memories, latest cross-agent session handoff, and developer preferences (JSON).mindgate://rules/agents-md— Live auto-compiledAGENTS.mdrules preview (Markdown).
Prompts
mindgate-bootstrap— Loads persistent project memory, preferences, and the latest session handoff at session start. Argument:workspace(optional).
❓ FAQ
Where does my memory live?
~/.mindgate/mindgate.db(override withMINDGATE_DB_PATH). Plaintext by design — treat it like any local credential store. Delete the file to wipe everything.Does it work offline? Yes — after install, nothing ever leaves your machine. No network, no telemetry, no accounts.
Can I move memory between machines? Yes:
export_memory_snapshot→ copy the JSON, or simply copy the.dbfile.Do all secrets get redacted? No — well-known patterns only (best-effort). Never store raw secrets in memories.
Can agents be prompt-injected via memories? Memories are data, not instructions, and they are embedded verbatim into generated rules files — review generated
AGENTS.mdbefore committing it.Which Node do I need?
^22.23.4 || ^24.22.1 || >=26.12.1— see SECURITY.md (CVE-2026-111497).
🪟 Windows Troubleshooting
npm ci fails with EPERM ... better-sqlite3\prebuilds\win32-x64.node? A running agent/editor is holding the native file:
Close every app that uses MindGate (check the system tray too) and any VS Code windows on the repo.
Get-Process node | Select-Object Id, Path— thenStop-Process -Id <ID> -Force.Rename-Item node_modules node_modules.old→npm ci→npm test. Renaming succeeds even while files are open.Delete
node_modules.oldafterwards.
On Windows the POSIX chmod test is skipped; everything else passes (28 pass + 1 skip).
⚙️ Environment Variables
Variable | Default | Description |
|
| Absolute path of the SQLite database file. Parent directory is created automatically ( |
|
| Default workspace when a tool call omits |
|
| Set to |
|
| Set to |
Database files are created with owner-only permissions (0600 file, 0700 directory). Contents are plaintext by design — treat the database like any local credential store.
🚀 Quick Start
Option 1: Zero-Install via npx (published on npm)
npx -y mindgate-mcp init
# verify: npm view mindgate-mcp versionOption 2: Build from Source (Windows / macOS / Linux)
git clone https://github.com/aaserag1/mindgate-mcp.git
cd mindgate-mcp
npm install
npm run build
# Print ready-to-paste MCP client configuration
npm run init-configConfigure in Antigravity / Cursor / Claude Desktop (Windows Example)
{
"mcpServers": {
"mindgate": {
"command": "node",
"args": ["C:\\path\\to\\mindgate-mcp\\dist\\index.js"],
"env": {
"MINDGATE_DB_PATH": "C:\\Users\\YOUR_USER\\.mindgate\\mindgate.db"
}
}
}
}Configure via npx (Cross-Platform 1-Liner)
{
"mcpServers": {
"mindgate": {
"command": "npx",
"args": ["-y", "mindgate-mcp"]
}
}
}Install via Smithery
To install MindGate for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install mindgate-mcp --client claude🖥️ Local Web Dashboard
MindGate includes a zero-dependency, local-only web dashboard. It binds strictly to 127.0.0.1 so it is never exposed to external networks.
# Launch dashboard from CLI (defaults to port 4242)
mindgate-mcp ui
# Or specify a custom port
mindgate-mcp ui --port 5050
# When running from cloned source
npm run uiThen open http://127.0.0.1:4242 in your browser:
Visual Memory Manager: Search via FTS5 BM25 in real time, view status badges (
active,superseded,deprecated), filter by workspace and category.Bi-Directional Language Support: One-click toggle between English (LTR) and Arabic (RTL).
Dark & Light Modes: Smooth, accessible palette matching modern developer tools.
Lifecycle Management: Add new memories with
supersedeslinks, mark decisions deprecated, or delete memories.One-Click Compaction: Compact historical sessions into milestone summaries.
Export & Backup: Download a full JSON snapshot directly from the UI.
To start the dashboard and open it in your default browser when an MCP client starts MindGate, append --open-dashboard to that client's MindGate command arguments. For a local build, use args = ["D:/mindgate-mcp/dist/index.js", "--open-dashboard"] in Codex TOML or "args": ["D:/mindgate-mcp/dist/index.js", "--open-dashboard"] in Antigravity JSON. Use the path from your existing configuration and restart the client after saving.
The dashboard runs in a separate process on loopback. MCP continues to use stdio. Enabled clients using the same port share one dashboard address, and a remaining client can take over when the first exits. An occupied port never triggers a browser launch. Append --port 5050 as two arguments to use a different port.
🪝 Git Post-Commit Hook Adapter
Automatically capture commit messages and touched files into your workspace memory without breaking your flow:
# Install hook into current Git repository
mindgate-mcp git-hook install
# Specify custom workspace name
mindgate-mcp git-hook install --workspace my-project
# Uninstall hook cleanly
mindgate-mcp git-hook uninstallThe hook appends a non-blocking background task to .git/hooks/post-commit cleanly bounded by # --- mindgate:post-commit --- sentinels, preserving any existing Git hooks you have.
🧪 Testing & Verification
npm run typecheck # TypeScript --noEmit
npm test # 29 tests (real SQLite + FTS5)
npm run build # emit dist/All 29 tests pass on Linux; on Windows 28 pass + 1 skipped (POSIX chmod is unsupported). GitHub Actions is currently unavailable on this account, so no green-CI badge is claimed — tests are run locally before every release. Minimum runtimes: ^22.23.4 || ^24.22.1 || >=26.12.1.
📄 License
Released under the MIT License.
Available Tools
13 toolscompact_memoriesB
Compact and consolidate historical cross-agent sessions in a workspace into a dense milestone record, preventing context window bloat in long-running projects.
Inputs: workspace, max_sessions_to_keep.
delete_memoryB
Delete an outdated or superseded memory record by its ID.
Inputs: id (required).
deprecate_memoryA
Mark an architectural decision or convention as deprecated so AI agents know not to follow it anymore, while preserving it for historical auditing.
Inputs: id (required), reason.
export_memory_snapshotB
Export a portable JSON backup snapshot of MindGate memories, session handoffs, and developer preferences.
Inputs: workspace.
get_dashboard_urlA
Get the local URL and launch instructions for the MindGate visual web dashboard (localhost:4242).
Inputs: port.
get_user_preferencesB
Retrieve all saved global developer preferences and coding rules.
Inputs: category.
list_workspacesB
List all project workspaces stored in MindGate along with memory counts.
Inputs: no named parameters.
log_session_summaryA
Log a session handoff summary when finishing work in one AI agent (e.g. Antigravity) so the next agent (e.g. OpenCode or Codex) can continue seamlessly.
Inputs: summary (required), workspace, next_steps, active_files, +1 more.
recall_contextB
Search MindGate (بوابة العقل) using FTS5 BM25 full-text ranking for relevant project decisions, latest cross-agent session handoff, and developer preferences.
Inputs: limit, query, status, category, +2 more.
remember_decisionA
Save an architectural decision, coding convention, bug root-cause, or important context into MindGate (بوابة العقل) so all AI tools remember it.
Inputs: title (required), content (required), tags, category, +3 more.
set_user_preferenceB
Save a persistent developer preference or global coding rule (e.g., preferred test runner, naming conventions, forbidden packages).
Inputs: key (required), value (required), category.
sync_workspace_rulesA
Generate a structured Markdown rules file (AGENTS.md, .cursorrules, or CLAUDE.md) from stored MindGate memories, conventions, preferences, and latest session handoff. Writes are atomic; existing files are backed up to .bak- and hand-written files are never overwritten unless force=true.
Inputs: force, workspace, project_dir, target_file, +1 more.
update_memoryB
Update an existing memory or architectural decision in-place by its ID without losing its record ID or creation timestamp.
Inputs: id (required), tags, title, status, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools have clearly distinct purposes: creating, updating, deleting, deprecating, recalling, compacting, exporting, and syncing memories are separable. There is minor potential overlap between remember_decision and set_user_preference because both can store conventions/rules, but the descriptions distinguish project decisions from developer preferences.
All 13 tool names consistently use snake_case with a verb_noun pattern. Differences like singular/plural nouns (memory vs memories) are natural and do not break predictability.
The server has 13 tools, which is well within the typical 3-15 range for a focused memory/context server. Each tool appears to earn its place by covering a distinct operation in the memory lifecycle.
The surface covers core memory CRUD/lifecycle operations, preferences, session handoffs, compaction, export, and rules synchronization. Minor gaps exist, such as no direct get_memory_by_id or import/restore counterpart for export_memory_snapshot, but agents can work around these with recall_context and existing update/delete tools.
Maintenance
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Shared, scoped, reviewable team memory for AI coding agents.
Memory for AI agent teams across tools, sessions, repositories, and teammates.
Persistent engineering memory designed to follow developers across coding agents.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceGives AI coding agents persistent, local-first memory so they can store, semantically search, and recall decisions, preferences, error patterns, and cross-project guidelines directly during a session. It also optionally queues tasks for autonomous execution against that same memory.-
- FlicenseNot gradedqualityAmaintenanceProvides AI coding agents with a local-first persistent memory layer they can read and write during sessions, storing decisions, preferences, error patterns, and research per project or globally. Enables semantic and keyword search, formatted context recall, and cross-project guideline surfacing without API keys or cloud storage.-
- FlicenseNot gradedqualityAmaintenanceGives AI coding agents a local-first persistent memory they can read and write directly during sessions, storing decisions, preferences, error patterns, and guidelines in per-project and global SQLite stores. Enables semantic and keyword retrieval of relevant context across sessions so agents start work already knowing a codebase's conventions and history.-
- FlicenseNot gradedqualityAmaintenanceEnables AI coding agents to store and retrieve persistent project and cross-project memories via semantic search, so decisions, preferences, error patterns, and guidelines survive across sessions. Optionally supports autonomous task execution built on the same local-first knowledge store.-