🧠 AI-Cortex

A self-hosted, persistent long-term memory cortex for Claude, Gemini, and other LLMs. Combines the best of Notion (structured properties, databases, Kanban boards) and Obsidian (speed, privacy, local ownership, markdown, bidirectional backlinks), backed by MySQL 8.4 and local hybrid file storage.

Designed to connect natively to Claude Desktop (Claude Pro) and Gemini via the Model Context Protocol (MCP) with zero API keys.

✨ Features

• ⚡ Sub-Millisecond MySQL 8.4 Relational Engine: Pre-indexed slugs, B-Tree foreign keys with cascading updates, and FULLTEXT search index.

• 📎 Hybrid Attachment Storage: Deduplicated binary storage on disk (storage/attachments/) using SHA-256 hashes, with metadata and relations in MySQL.

• 🤖 Native MCP Server for Claude & Gemini:

  • Connects to Claude Desktop using your monthly Claude Pro subscription without paying for API tokens.

  • Connects to Gemini / Antigravity with zero setup friction.

  • In-app 1-Click Auto-Installer for claude_desktop_config.json.

• 🔗 Bidirectional Backlinks & Wikilinks:

  • Type [[ in any note to trigger instant autocompletion of existing notes.

  • "Linked Mentions" panel at the bottom of every note displaying all notes that reference it.

• 📋 Notion-Style Database Views:

  • Kanban Board: Drag or transition notes across workflow statuses.

  • Database Grid: Sortable, filterable table view with editable statuses.

  • Global Action Items: Automatically extracts and aggregates - [ ] tasks from every note into a consolidated checklist.

• 📅 Daily Journaling: Jump to or create today's daily note with one keystroke (Alt + D).

• 🎨 Adaptive Theming: 3-way Dark / Light / System ambiance (follows the OS and reacts live to changes), 15 curated accent palettes plus a custom-colour picker. Preferences persist in localStorage; the theme is applied before first paint to avoid any flash. Toggle modes with Alt + T or from Settings → Appearance.

• 📦 Obsidian Vault 1-Click Export & Import: Export all notes and attachments as a standard .zip vault, or import existing Markdown vaults.

• 🧪 Complete Test Suite: 11 automated unit and integration tests passing in ~300ms (npm test).

Related MCP server: Engram

🚀 Quick Start

1. Requirements

• Node.js v20+ (v22 recommended)

• MySQL 8.4+ (MariaDB 10.6+ also works)

2. Environment Setup

Copy .env.example to .env and configure with your MySQL or MariaDB credentials:

cp .env.example .env

PORT=3001
HOST=127.0.0.1
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=ai_cortex
DB_USER=your_db_user
DB_PASS=your_db_password

3. Run Migrations & Seed Demo Data

npm run migrate
npm run seed

4. Run Automated Tests

npm test

5. Start AI-Cortex

Development (backend + Vite dev client with hot reload):

npm run dev

Open http://127.0.0.1:5173 — the client proxies /api to the backend on port 3001.

Production (single server serving the built UI + API):

npm run build   # bundles the client into ./dist
npm start

Open http://127.0.0.1:3001. The API binds to HOST (default 127.0.0.1); set HOST / ALLOWED_HOSTS to expose it on a LAN.

🤖 Connecting Claude Desktop (Zero API Keys)

1. Open AI-Cortex in your browser.

2. Click Settings in the bottom-left sidebar, then open the AI Integrations tab.

3. Click the "1-Click Auto Install" button (or copy the pre-filled JSON snippet into your claude_desktop_config.json). A "1-Click Enable for Gemini" button does the same for .agents/mcp_config.json in this workspace.

4. Restart Claude Desktop. You will now see the memory tools (ai_cortex_search, ai_cortex_read_note, ai_cortex_create_note, ai_cortex_update_note, ai_cortex_get_backlinks, ai_cortex_list_recent, ai_cortex_list_tasks) available directly in Claude using your existing Claude Pro subscription!

⌨️ Keyboard Shortcuts