--- title: MemPalace (cross-session memory for your sessions) --- # MemPalace — persistent cross-session memory ## What it is ### What it is MemPalace is a cross-session memory system that gives every Claude Code session a set of MCP tools for remembering things you've done before. Your session transcripts are mined in the background and organized hierarchically into **wings** (broad areas like a project or topic), **rooms** (categories like prompts, responses, outcomes), and **drawers** (individual facts or snippets). Agents can search and add drawers via MCP tools, and you can browse/edit the same content yourself in the **MemPalace** page. Search is hybrid: semantic (via local 384-dim embeddings) _plus_ full-text — neither needs a network call. Ships as an experimental feature; off by default. ## Where to find it **Settings → Features → Enable Memory Palace** turns it on. There is no panel of its own — it works by giving your sessions tools, so you see it in what an agent can recall rather than on a screen. ## How it behaves ### How to use it 1. **Turn it on.** Open Settings → **Features** → flip on **Enable Memory Palace**. The default is off. When you enable it, Omniscio writes a small curated `.mcp.json` to a private per-session path (under Omniscio's data dir, never your project folder) and hands it to each new session's Claude CLI via `--mcp-config`, so the session can see the MemPalace MCP tools. 2. **Let sessions run normally.** While sessions work, agents can call `mempalace_search`, `mempalace_add_drawer`, `mempalace_list_wings`, `mempalace_list_rooms`, `mempalace_wake_up` (returns an identity + essential-story preface), and `mempalace_status` (diagnostics). No action from you is required — the agent decides when to recall or store. 3. **Browse what's been remembered.** Once enabled, a **Memory Palace** entry (brain icon) appears in the top toolbar's **"⋯" (more) menu**, under *Notes & capture* — click it (or pin it to the toolbar) to open the three-pane UI: wings on the left, rooms in the middle-left, drawers in the middle-right. Arrow keys navigate, clicking a drawer reveals the content on the right. (It is NOT a left-sidebar hub. Agents and scripts can also open it over the CLI control server with `POST /ui/open` and body `{"target":"mempalace"}`.) 4. **Search directly.** The search bar at the top of the MemPalace page supports **hybrid**, **semantic-only**, or **lexical-only** modes. Use hybrid for best recall; semantic-only if you want concept matches; lexical-only if you need an exact phrase. 5. **Mining runs after sessions end.** You don't trigger it manually. The scheduler debounces per-session mining so a session that just stopped will be extracted into drawers shortly after, not during active work. 6. **Turning it off.** Flip the **Enable Memory Palace** toggle back off. New sessions will no longer load the MemPalace tools. Any session that was _already_ launched (with its `.mcp.json` already on disk) is also covered: the MemPalace MCP server itself re-checks Omniscio's saved toggle every time it boots and exits cleanly when the feature is off, so a stale curated `.mcp.json` cannot resurrect the feature against your wish. As a tidy-up, the next spawn rewrites (or removes) that private per-session file. ## For agents ### How it works The toggle `mempalaceEnabled` lives in [/src/shared/types.ts](/src/shared/types.ts) and is wired through Settings → Advanced → Features at [/src/renderer/src/features/settings/sections/features/feature-rows.tsx](/src/renderer/src/features/settings/sections/features/feature-rows.tsx). When enabled, [/src/main/services/mcp/mcp-entry.ts](/src/main/services/mcp/mcp-entry.ts) holds the shared bundled-local-MCP entry scaffold (it lived under `mempalace/` as `mcp-config-writer.ts` until F145 moved it; MemPalace's own entry builder was retired with the rest of that set when MemPalace left composition on 2026-09-19) and still shapes any local entry the shared orchestrator writes into a session's curated `.mcp.json` — written to a private per-session path under Omniscio's data dir, never the workDir (see [backend-spawn-contract.md](/.claude/memory/contracts/backend-spawn-contract.md) §12) — pointing at the compiled server at `out/mcp/mempalace-server.js`. That server spawns via `ELECTRON_RUN_AS_NODE=1` + `process.execPath` (Electron as pure Node) — which means any module it pulls in must defer top-level `electron` imports (e.g. [/src/main/services/embedding-model.ts](/src/main/services/embedding-model.ts)) or the subprocess crashes with `Named export 'app' not found`. The six MCP tools live in [/src/main/services/mempalace-mcp-server/](/src/main/services/mempalace-mcp-server/); storage and mining live in [/src/main/services/mempalace/storage.ts](/src/main/services/mempalace/storage.ts), [/src/main/services/mempalace/mining.ts](/src/main/services/mempalace/mining.ts), and [/src/main/services/mempalace/mining-scheduler.ts](/src/main/services/mempalace/mining-scheduler.ts). Drawers persist in SQLite (schema v87) across three tables: `memory_drawers` (content), `drawer_embeddings` (384-dim Float32 vectors from HuggingFace Xenova/all-MiniLM-L6-v2), and `memory_drawers_fts` (FTS5 with trigger-based sync). The UI is [/src/renderer/src/features/mempalace/MemPalacePage.tsx](/src/renderer/src/features/mempalace/MemPalacePage.tsx) backed by [/src/renderer/src/stores/mempalace-store.ts](/src/renderer/src/stores/mempalace-store.ts). Full schema + tool signatures: [MemPalace memory notes](/.claude/memory/mempalace.md); full incident history: [MemPalace memory-system postmortem](/.claude/memory/postmortems/archived/mempalace-memory-system-postmortem.md). ## Related ### Related - [use-skills.md](use-skills.md) — Skills are a different way to teach agents: prompt-level recipes, not memory - [session-stuck-in-needs-you.md](session-stuck-in-needs-you.md)