Skip to main content
Glama

🧠 MindGate MCP (v1.5.0) — بوابة العقل

npm version npm downloads License: MIT Security: Node2Shell Hardened Version: 1.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:

  1. Cross-Session Context Amnesia: Every new chat starts from zero—forgetting architectural decisions, debugging root causes, coding conventions, and session handoffs.

  2. 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_context automatically 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 (default bundled + multilingual profile via mindgate-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 ui or npm run ui) running locally on http://127.0.0.1:4242 with 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 without force: 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 a redacted_secrets count. Disable with MINDGATE_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:zlib Brotli 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

MindGate architecture — one local pipe: clients → stdio → bootstrap → validate → redact → SQLite FTS5 → compiled rules

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"| PROJ

Request lifecycle (numbered as in the diagram):

  1. Any MCP client spawns mindgate-mcp as a child process. All communication is newline-delimited JSON-RPC over stdio — no sockets, no HTTP, no telemetry.

  2. The first module evaluated is src/security/bootstrap.ts (imported before everything else): it hard-locks the public node:zlib Brotli decompression API and checks the Node/Bun version against the patched releases for CVE-2026-111497.

  3. 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.

  4. On write paths (remember / update / session handoff / preferences), secrets are redacted before anything touches disk.

  5. 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.

  6. sync_workspace_rules compiles 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 unless force: 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

remember_decision

Store a persistent memory (architecture / decision / bugfix / convention / context) with automatic secret redaction and optional supersedes parameter to invalidate previous decisions

update_memory

Update an existing memory in-place by ID with optional status (active/superseded/deprecated) while keeping FTS5 search indexes in sync

recall_context

Search memories with FTS5 BM25 ranking, workspace/category filters, and lifecycle status filter (active/superseded/deprecated/all, default: active). When no query matches, falls back to most-recent memories and flags it (search.fallback: true)

deprecate_memory

Mark an existing memory as deprecated by ID with an optional reason, excluding it from active recall without deletion

compact_memories

Compact historical session handoffs into consolidated milestone summaries to reduce token overhead while retaining full context

log_session_summary

Save a structured session handoff (summary, next steps, active files) for the next agent to resume

get_dashboard_url

Get the URL of the local MindGate Web Dashboard (http://127.0.0.1:4242)

sync_workspace_rules

Generate AGENTS.md, .cursorrules, CLAUDE.md, .windsurfrules, or MINDGATE_CONTEXT.md from stored memories. Atomic write, .bak backup, hand-written files protected unless force: true

export_memory_snapshot

Export a portable JSON backup of memories, session handoffs, and preferences

set_user_preference

Save or update a persistent developer preference (key/value)

get_user_preferences

Retrieve all saved preferences, optionally filtered by category

list_workspaces

List all workspaces with memory counts and last-updated timestamps

delete_memory

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-compiled AGENTS.md rules 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 with MINDGATE_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 .db file.

  • 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.md before 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:

  1. Close every app that uses MindGate (check the system tray too) and any VS Code windows on the repo.

  2. Get-Process node | Select-Object Id, Path — then Stop-Process -Id <ID> -Force.

  3. Rename-Item node_modules node_modules.old → npm ci → npm test. Renaming succeeds even while files are open.

  4. Delete node_modules.old afterwards.

On Windows the POSIX chmod test is skipped; everything else passes (28 pass + 1 skip).


⚙️ Environment Variables

Variable

Default

Description

MINDGATE_DB_PATH

~/.mindgate/mindgate.db

Absolute path of the SQLite database file. Parent directory is created automatically (0700).

MINDGATE_DEFAULT_WORKSPACE

global

Default workspace when a tool call omits workspace.

MINDGATE_REDACT_SECRETS

true

Set to false to disable secret redaction on write (not recommended).

MINDGATE_STRICT_NODE2SHELL

false

Set to true to refuse starting on an unpatched Node.js runtime.

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 version

Option 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-config

Configure 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 ui

Then 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 supersedes links, 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 uninstall

The 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 tools
compact_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

    A3.7/5.0

    Scored across 13 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Gives 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Provides 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Gives 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -