mempalace-mcp

A lightweight LM Studio Plugin wrapper around the MemPalace MCP server. It re-exposes all 45 MemPalace MCP tools in two complementary ways, without ever editing the original Python source tree (so git pull inside MemPalace/ keeps working):

1. As a native LM Studio Plugin tools provider — usable directly inside LM Studio's tool-calling loop (src/toolsProvider.ts).

2. As a standalone MCP server — connectable from any MCP client, including Claude Code, Gemini CLI, Cursor, and Antigravity (dist/mcp.js, see npm run mcp).

Both entry points share one catalog (src/core/tools-catalog.ts) and one long-lived bridge (src/core/python-bridge.ts). The TypeScript layer is purely a thin, type-safe proxy in front of the real Python server.

Bottom line: you write nothing about MemPalace's internals here. The wrapper only spawns, talks, and forwards. MemPalace stays the source of truth and stays updatable.

What MemPalace is

MemPalace is a local-first AI memory store. It keeps your conversation history as verbatim text and retrieves it with semantic search — it does not summarize, extract, or paraphrase. The index is structured: people and projects become wings, topics become rooms, and original content lives in drawers. Retrieval is pluggable (ChromaDB by default) and nothing leaves your machine unless you opt in.

mempalace-mcp simply makes that palace reachable from LM Studio and any other MCP client through a consistent 45-tool surface.

Related MCP server: mempalace-mcp-http

Architecture

            LM Studio Plugin tool loop          Any MCP client
                        │                              │
                        └──────────┬───────────────────┘
                                     │
                   ┌────────────────▼─────────────────┐
                   │  src/index.ts  →  main(context)   │  (registers both)
                   └───────────────┬──────────────────┘
                     ┌──────────────┴──────────────┐
                     ▼                              ▼
        src/toolsProvider.ts              src/mcp.ts
   (LM Studio Tool API, zod params)   (standalone MCP server)
                     │                              │
                     └───────────────┬──────────────┘
                                     │
                    src/core/tools-catalog.ts   ← single source of truth
                    (name + description + JSON schema for all 45 tools)
                                     │
                    src/core/python-bridge.ts
                    (spawns the Python server once, reuses the connection)
                                     │
                     ┌───────────────┴───────────────┐
                     ▼                                ▼
        python -m mempalace.mcp_server         MemPalace palace
        (stdio JSON-RPC, unmodified)       (ChromaDB / SQLite / KG / logstream)

Key design decisions:

Repository layout

mempalace-mcp/
├── manifest.json            # LM Studio Plugin manifest (owner kebab-case)
├── package.json             # deps, scripts ("postinstall" provisions the venv), bin
├── tsconfig.json            # NodeNext ESM-style TS → compiled to dist/
├── README.md
├── scripts/
│   └── setup.cjs            # postinstall: clone + venv + pip install MemPalace
├── src/
│   ├── index.ts             # Plugin entry → exports main(pluginContext)
│   ├── toolsProvider.ts     # LM Studio tool provider (all 45 tools)
│   ├── config.ts            # Global config schematics (Palace Path, Read-only)
│   ├── mcp.ts               # Standalone MCP server entry (npm run mcp)
│   └── core/
│       ├── python-bridge.ts # Spawns + talks to the Python MCP server
│       ├── tools-catalog.ts # Authoritative list of all 45 tools
│       ├── zod-from-json.ts # JSON schema → Zod conversion
│       └── format-result.ts # Result shaping for both surfaces
└── dist/                    # Compiled JavaScript (output of `npm run build`)

Development process

This project was built as a port, not a rewrite. The steps that mattered:

1. Enumerate the source of truth. The Python server declares every tool in MemPalace/mempalace/mcp_server/schemas.py (TOOLS). We transcribed each tool's name, description, and JSON schema verbatim into src/core/tools-catalog.ts. Nothing is hand-rolled per tool.

2. Wrap, don't reimplement. Rather than translate the MCP protocol by hand, python-bridge.ts uses @modelcontextprotocol/sdk as an MCP client and spawns python -m mempalace.mcp_server once, reusing that connection. The wrapper only forwards arguments and shapes results.

3. Share one catalog across two entry points. toolsProvider.ts (LM Studio) and mcp.ts (standalone MCP) iterate the same catalog, so the two surfaces can never drift apart.

4. Keep the Python tree pristine. MemPalace/ is a git clone managed by scripts/setup.cjs. We never edit it, so upstream fixes and new tools land through a plain git pull and this catalog can be regenerated.

5. Provision at install time. The postinstall script clones MemPalace, builds a Python venv, and installs the package (plus chromadb, numpy, onnxruntime, …) into it — so npm install leaves a working palace behind.

The plugin is CommonJS on purpose: lms dev/Hub bundles it with esbuild as CJS, so the package must load as CJS too. The source therefore uses __dirname (not import.meta) to locate .venv, and the entry exports a main(pluginContext) function that lms invokes to register the provider.

Installation

From the LM Studio Hub (recommended)

Once published, install straight from the Hub. On first load, npm runs the postinstall hook, which:

1. clones https://github.com/MemPalace/mempalace into MemPalace/,

2. creates a Python venv at .venv/,

3. runs pip install -e ./MemPalace to provision the palace + deps.

Then open Plugins → mempalace-mcp, enable it, and set Palace Path in its global configuration. The first tool call spawns the Python server; the connection is cached for subsequent calls.

From a source checkout

npm install                 # runs postinstall: clone + venv + pip install
npm run typecheck           # tsc --noEmit
npm run build               # tsc → dist/
lms dev                     # load into LM Studio (hot-reload)
lms push                    # publish to the Hub

npm install alone is not proof that MCP is connected — see Verifying the connection below.

The 45 MCP tools

Every tool mirrors its Python counterpart exactly. They fall into eight groups.

Overview (7)

Graph navigation (8)

mempalace_traverse, mempalace_find_tunnels, mempalace_create_tunnel, mempalace_list_tunnels, mempalace_delete_tunnel, mempalace_list_hallways, mempalace_delete_hallway, mempalace_follow_tunnels

Search & read drawers (4)

mempalace_search, mempalace_check_duplicate, mempalace_get_drawer, mempalace_list_drawers

Write drawers (7)

mempalace_add_drawer, mempalace_update_drawer, mempalace_delete_drawer, mempalace_delete_by_source, mempalace_mine, mempalace_checkpoint, mempalace_sync

Knowledge graph (6)

mempalace_kg_query, mempalace_kg_add, mempalace_kg_invalidate, mempalace_kg_supersede, mempalace_kg_timeline, mempalace_kg_stats

Diary (4)

mempalace_diary_write, mempalace_diary_read, mempalace_hook_settings, mempalace_memories_filed_away

Coordination — logstream & artifacts (RFC 003/004) (8)

mempalace_event_append, mempalace_task_create, mempalace_event_list, mempalace_event_wait, mempalace_event_ack, mempalace_artifact_put, mempalace_artifact_get, mempalace_patch_submit

Maintenance (1)

mempalace_reconnect — force a reconnect to the palace DB after external writes.

Need the exact argument schema for a tool? It is defined in src/core/tools-catalog.ts and validated by Zod on both surfaces.

Usage

1. Inside LM Studio (Plugin)

Enable the plugin, set Palace Path (and optionally Read-only mode) in its global config, then let the model call tools during a session. The provider registers all 45 tools automatically; the model sees their descriptions and can invoke any of them.

2. As a standalone MCP server

Add it to any MCP client via stdio:

{
  "mcpServers": {
    "mempalace-mcp-lms": {
      "command": "node",
      "args": ["/absolute/path/to/project/dist/mcp.js"]
    }
  }
}

Or run it directly and talk to it over stdio:

npm run build && npm run mcp

mcp.ts reads MEMPALACE_PALACE_PATH / MEMPALACE_MCP_READ_ONLY from the environment when no explicit config is supplied.

Verifying the connection

Package installation alone does not prove MCP is connected. Confirm the live tool list:

# standalone
node dist/mcp.js            # then call tools/list over stdio
# or, inside LM Studio, open the tool panel and confirm all 45 tools appear

The first call spawns python -m mempalace.mcp_server; a healthy response (mempalace_status returning counts, or a graceful "no palace yet" message) means the bridge is wired correctly.

Using MemPalace's own examples & skills through mempalace-mcp

MemPalace ships examples and skills that describe how agents should set up, recall from, and coordinate via the palace. mempalace-mcp is the transport that lets your agent actually execute those patterns — whether you run them in LM Studio or through another MCP harness. The sections below map each upstream resource to the concrete tool calls it triggers.

MemPalace/examples/ — runnable recipes & wiring guides

How to use them with mempalace-mcp:

• Mine a project first. Point mempalace_mine at the directory you want the agent to remember (code, docs, or transcripts). For Claude Code sessions: mempalace_mine with mode="convos" over your ~/.claude/projects/ tree — the shape matches convo_import.py.

• Search before answering. Run mempalace_search with a short, keyword-only query (≤ 250 chars — never paste a whole conversation or system prompt). Use wing / room filters to scope, and limit (default 5) to bound results.

• Prefer the MX3 shim only on backed hardware. The mx3_public_shim recipe is opt-in and requires the accelerator behind the endpoint; enable it via the documented MEMPALACE_MX3_PUBLIC_SHIM_* env vars, then call mempalace_search as usual.

MemPalace/skills/ — agent runbooks

MemPalace exposes three skills (agent-runbook markdown consumed by coding agents). mempalace-mcp is the MCP surface each skill assumes is connected.

• skills/mempalace/SKILL.md — Install, configure, and operate. Guided setup for a private local palace, a shared-brain hub, or a client joining an existing hub. Covers detecting the harness, choosing topology, configuring MCP, and reporting readiness. Through mempalace-mcp this becomes: spawn the Python server, verify tools/list shows the 45 tools, then operate via mempalace_status, mempalace_mine, mempalace_list_wings, etc.

• skills/mempalace-recall/SKILL.md — Search-before-answer recall. The core agent discipline: read the palace instead of guessing from model memory. Key mappings through mempalace-mcp:

  • Wake-up: call mempalace_search; use mempalace_kg_query for relational or time-bound facts (as_of).

  • Always return the drawer's verbatim text — never summarize stored content.

  • Record continuity with mempalace_diary_write; when a fact changes, use mempalace_kg_supersede (single-valued replacement), mempalace_kg_invalidate (ended without replacement), or mempalace_kg_add (independent/coexisting).

  • Anti-patterns to enforce: don't search on greenfield tasks with no memory relevance, don't answer from model memory when the palace might know, and don't paraphrase what mempalace_search returns.

• skills/mempalace-task/SKILL.md — Logstream task delegation. Move work between agents via the logstream (not memory drawers). Through mempalace-mcp:

  • Create a handoff with mempalace_task_create (returns a ready-to-paste line).

  • Monitor the inbox with mempalace_event_list / mempalace_event_wait, carrying since_event_id forward as a resume cursor.

  • Claim with mempalace_event_ack(status="claimed"), deliver patches via mempalace_patch_submit, and reference stored files with mempalace_artifact_put / mempalace_artifact_get.

  • Remember: logstream events are immutable — show the user the exact task content and get approval before appending.

Recommended workflow (any harness)

1. Set up — follow skills/mempalace/SKILL.md; confirm the 45 tools are live.

2. Mine — mempalace_mine your corpus (code, convos, or office docs).

3. Recall — follow skills/mempalace-recall/SKILL.md: search first, quote verbatim, write diary continuity with mempalace_diary_write.

4. Coordinate — when delegating across agents, switch to skills/mempalace-task/SKILL.md and the logstream tools.

Requirements

• Python 3.9+ (provisioned automatically into .venv/ by scripts/setup.cjs).

• A vector-store backend — ChromaDB is bundled and needs no configuration.

• ~300 MB disk for the embedding model. The first embedding-backed call downloads the model (~80 MB default minilm, ~300 MB embeddinggemma); read-only sqlite-backed tools (mempalace_status, list, taxonomy, KG) stay fast.

• Optional: route embeddings/rerank through an OpenAI-compatible endpoint by setting embedding_model: "openai-compat" in MemPalace's config — no content leaves your network when the endpoint is local.

No API key is required for the core recall path.

Notes & limitations

• Python is required at install and runtime. The bridge spawns the venv's Python. On machines where python3 on PATH is a broken symlink (empty sys.executable), setup.cjs falls back to absolute interpreter paths under /usr/bin/python3.*.

• First embedding-backed call is slow and needs network. The embedder model downloads once per palace; subsequent calls are fast.

• Read-only mode spawns the Python server with --read-only; mutating tools (writes, mine, checkpoint, coordination) are refused, which is useful for pure recall sessions.

References

• MemPalace repo: https://github.com/MemPalace/mempalace

• Full MCP tool reference: https://mempalaceofficial.com/reference/mcp-tools.html

• The palace concept: https://mempalaceofficial.com/concepts/the-palace.html

• Knowledge graph: https://mempalaceofficial.com/concepts/knowledge-graph

Contributing

PRs welcome. When adding or renaming a tool, update src/core/tools-catalog.ts to match MemPalace/mempalace/mcp_server/schemas.py so both entry points stay in sync.

License

MIT — see LICENSE.