Mempalace Explorer

MemPalace Explorer

A modern web application for visually navigating, searching, and managing MemPalace memories. Built with Vue 3, Tailwind CSS, Express, and Prisma.

Features

• Tree Navigation -- Browse your palace hierarchy (Wing > Room > Memories) with an expandable sidebar
• Semantic Search -- Full-text search powered by MemPalace embeddings, triggered via Ctrl+K / Cmd+K
• Memory Viewer -- Read, create, edit, and delete memories with full metadata display
• Knowledge Graph -- Force-directed D3.js visualization of room traversals and entity relationships
• Query Lab -- Monaco Editor with a custom DSL, autocomplete, and sortable results table
• Timeline -- Chronological view of memories with type inference (decision / insight / rule) and filters
• Favorites -- Star memories for quick access
• Dark Mode -- Default dark theme inspired by Linear and Notion

Prerequisites

| Dependency | Version | |---|---| | Node.js | >= 18 | | npm | >= 9 | | mempalace (Python) | pip install mempalace |

The mempalace CLI must be available on your PATH, or you can provide the full path to the binary in Settings.

Quick Start

Option A -- CLI (recommended)

git clone https://github.com/user/mempalace-explorer.git
cd mempalace-explorer
npm install -g .

mempalace-explorer init   # installs deps, sets up DB, builds everything
mempalace-explorer run    # http://localhost:3001

Option B -- Manual

# 1. Install dependencies (root, client, and server)
npm install

# 2. Generate Prisma client & create the SQLite database
cd server
npx prisma generate
npx prisma db push
npx prisma migrate deploy
cd ..

# 3. Start both client and server in dev mode
npm run dev

The client runs on http://localhost:5173 and the server on http://localhost:3001.

CLI Usage

After installing globally with npm install -g ., the mempalace-explorer command is available system-wide.

mempalace-explorer init

Installs all dependencies, generates the Prisma client, runs database migrations, and builds both client and server for production.

mempalace-explorer run [options]

| Flag | Description | Default | |---|---|---| | -p, --port | Server port (API + frontend) | 3001 | | --front-port | Vite dev server port (only with --dev) | 5173 | | -d, --detach | Run in background (returns terminal immediately) | false | | -D, --dev | Start in development mode with HMR | false | | -o, --open | Open browser automatically (implies --detach) | false |

Examples:

mempalace-explorer run                          # production on :3001 (foreground)
mempalace-explorer run --port 4000              # production on :4000 (foreground)
mempalace-explorer run -d                       # production, detached (background)
mempalace-explorer run -d --port 4000           # production on :4000, detached
mempalace-explorer run --open                   # detach + open browser
mempalace-explorer run --dev                    # dev mode (Vite :5173 + Express :3001)
mempalace-explorer run --dev --port 3000 --front-port 8080  # custom dev ports
mempalace-explorer run -d --dev                 # dev mode, detached

In production mode, a single Express server serves both the API (/api/*) and the Vue SPA as static files. In dev mode, Vite runs separately with HMR.

The server runs persistently in the background until explicitly stopped -- closing the browser does not stop the server. This is by design for spaced-out queries.

mempalace-explorer stop

Stops a running instance that was started with --detach (-d) or --open. Kills the entire process tree and cleans up the PID file. If no instance is running, it reports that cleanly.

Duplicate-run protection: attempting to run -d while an instance is already running will fail with a message to stop first.

First-Run Setup

On first launch the app redirects to the Settings page where you:

1. Choose a provider: MCP Client (recommended, persistent connection) or CLI Subprocess (one process per request).
2. Set the path to mempalace (e.g. mempalace if on PATH, or a full path like /home/user/.local/bin/mempalace).
3. Click Test Connection to verify.
4. Click Save -- the app loads your palace taxonomy and redirects to the Explorer.

Configuration is persisted in a local SQLite database at server/prisma/dev.db.

Project Structure

mempalace-explorer/
├── cli/                        # CLI tool (commander.js)
│   ├── index.ts                #   Entry point + command registration
│   ├── commands/               #   init, run, stop commands
│   └── utils.ts                #   Helpers (PID management, spawn, logger)
├── client/                     # Vue 3 + Vite frontend
│   └── src/
│       ├── assets/styles/      # Tailwind + custom theme
│       ├── components/         # Reusable UI components
│       │   ├── graph/          #   D3 force-directed graph
│       │   ├── layout/         #   AppLayout, Topbar, Sidebar, StatusBar, Breadcrumb
│       │   ├── memory/         #   MemoryCard, MemoryDetail, MemoryEditor
│       │   ├── query/          #   Monaco QueryEditor, QueryResults table
│       │   ├── search/         #   SearchBar modal, SearchResults list
│       │   ├── settings/       #   ProviderSelector, ConnectionTester
│       │   ├── timeline/       #   TimelineItem
│       │   └── tree/           #   TreeView, TreeNode (recursive)
│       ├── composables/        # useKeyboard (global shortcuts)
│       ├── router/             # Vue Router (lazy-loaded routes)
│       ├── services/           # HTTP client (fetch wrapper)
│       ├── stores/             # Pinia stores (settings, palace, memory, search, ui)
│       ├── types/              # Shared TypeScript interfaces
│       └── views/              # Page-level components
├── server/                     # Express + Prisma backend
│   ├── prisma/                 # Schema & SQLite DB
│   └── src/
│       ├── providers/          # MCP Client & CLI provider implementations
│       ├── routes/             # REST API routes
│       └── types/              # Server-side TypeScript interfaces
└── package.json                # Workspace root (npm workspaces + CLI bin)

Scripts

| Script | Description | |---|---| | npm run dev | Start client + server concurrently | | npm run build | Build client and server for production | | npm run build:cli | Build the CLI tool | | npm run build:all | Build client, server, and CLI | | npm run dev:client | Start only the Vite dev server | | npm run dev:server | Start only the Express dev server |

Keyboard Shortcuts

| Key | Action | |---|---| | Ctrl+K / Cmd+K | Open semantic search | | Escape | Close search / editor / detail panel | | ↑ / k | Navigate tree up | | ↓ / j | Navigate tree down | | → / l | Expand into wing (select first room) | | ← / h | Collapse back to wing | | Ctrl+B / Cmd+B | Toggle sidebar | | Ctrl+Enter | Run query (in Query Lab) |

Tech Stack

Frontend: Vue 3 (Composition API + TypeScript), Pinia, Vue Router, Tailwind CSS v4, D3.js, Monaco Editor

Backend: Express, Prisma (SQLite), JSON-RPC 2.0 over stdio to mempalace mcp

License

MIT.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pauloteixeira
• Source: pauloteixeira/mempalace-explorer
• License: MIT

Install and usage instructions live in the source repository linked above.