memory-palace-setup

# Memory Palace Setup

Use this skill for first-time onboarding of the **Memory Palace project itself**.

This is a setup-and-routing skill, not the durable-memory operation skill.

## Separate The Two Layers First

Explain this immediately when the user is confused:

- `memory-palace-setup`
  - the onboarding skill in this repository
- `memory-palace`
  - the canonical runtime skill shipped by the main `Memory-Palace` repository
  - target repo: `https://github.com/AGI-is-going-to-arrive/Memory-Palace`

Also explain:

- service startup is not the same as client integration
- a running Dashboard / API / SSE service does not mean the user's client is
  already connected
- for `Cursor / Windsurf / VSCode-host / Antigravity`, seeing the
  `memory-palace` skill does **not** prove MCP is installed yet

## Default Stance

- Prefer **skills + MCP** for supported clients.
- Treat **MCP-only** as a fallback for explicit Docker `/sse`, remote-only, or
  no-skill environments.
- Default to **Profile B** to get the system running with the fewest extra
  services.
- Recommend **Profile C** once local embedding / reranker services are ready.
- Recommend **Profile D** once remote APIs or a hosted environment are already
  part of the plan.

## First-Pass Routing

Before giving commands, determine these facts:

1. Which host is the user trying to use?
   - `Claude Code`
   - `Codex CLI`
   - `Gemini CLI`
   - `OpenCode`
   - `Cursor`
   - `Windsurf`
   - `VSCode-host`
   - `Antigravity`
   - service-only (`Dashboard / API / SSE`)
2. What is the user trying to do?
   - run the service only
   - connect a CLI client to the current repo
   - connect an IDE host to the current repo
   - connect to Docker `/sse` only
3. What platform boundary matters?
   - native Windows
   - macOS / Linux
   - `WSL` / `Git Bash`
4. What is already present?
   - repo checkout
   - `.env` or `.env.docker`
   - `backend/.venv`
   - `scripts/sync_memory_palace_skill.py`
   - `scripts/install_skill.py`
   - `scripts/render_ide_host_config.py`
5. What scope decision is actually being made?
   - onboarding access
     - default: repo URL or direct read of this repo's `README.md` and
       `SKILL.md`
     - persistent installation of `memory-palace-setup` is optional
   - runtime skill visibility
     - if something should be installed persistently, prioritize the main
       repo's `memory-palace` skill
   - MCP binding
     - keep the current host-specific recommendation from the main repo
     - do not silently change MCP scope just because the user asked about
       onboarding access or runtime skill visibility

If one concise question can disambiguate the path, ask it. Otherwise inspect
the repo first.

If the user is explicitly asking for the default cross-host scope policy, do
not ask a host-selection follow-up first. Answer the default split directly:

- onboarding access
  - default to repo URL or direct doc reads
- runtime skill visibility
  - if something should be installed persistently, make that the main repo's
    `memory-palace` skill
  - if the user wants one stable cross-host installer, prefer
    `scripts/apply_runtime_global_setup.py`
- MCP binding
  - keep the current host-specific logic unchanged

## Platform Rules

- native Windows repo-local stdio default:
  - `backend/mcp_wrapper.py`
- macOS / Linux / `WSL` / `Git Bash` repo-local stdio default:
  - `scripts/run_memory_palace_mcp_stdio.sh`
- On Windows, do not lead with “you must use Git Bash / WSL.”
- On Windows, `Git Bash / WSL` are only relevant when the user explicitly wants
  the POSIX wrapper path.
- Do not tell the user to copy Docker `/app/...` or `/data/...` paths into a
  host `.env`.
- For `Cursor`, `Antigravity`, `VSCode-host`, and `Windsurf`, prefer an automatic local config write when
  the host CLI or config surface is known; otherwise fall back to rendered
  snippet + manual paste.
- When the user chooses the global runtime path for IDE hosts, say explicitly:
  - the runtime rule or skill layer is global
  - the IDE MCP config is also user-level
  - but that MCP entry still points to one selected local `Memory-Palace`
    checkout
  - if that checkout is moved, deleted, or broken, tool calls fail even though
    the runtime rule layer still appears available

## Repo-Visible Sources To Prefer

When the main `Memory-Palace` repo is present, prefer these paths:

- `README.md`
- `docs/README.md`
- `docs/skills/SKILLS_QUICKSTART.md`
- `docs/skills/GETTING_STARTED.md`
- `docs/skills/CLI_COMPATIBILITY_GUIDE.md`
- `docs/skills/IDE_HOSTS.md`
- `docs/GHCR_QUICKSTART.md`
- `scripts/sync_memory_palace_skill.py`
- `scripts/install_skill.py`
- `scripts/render_ide_host_config.py`
- `scripts/run_memory_palace_mcp_stdio.sh`
- `backend/mcp_wrapper.py`

## Routing Rules

- For CLI clients, read `references/cli-routing.md`.
- For all host-specific differences, read `references/host-matrix.md`.
- For service-only, Docker, GHCR, or `/sse` paths, read
  `references/service-modes.md`.
- For step-by-step validation, read `references/validation-matrix.md`.
- For common setup failures or boundary conditions, read
  `references/common-failures.md`.
- For automatic IDE-host MCP config, read `references/host-matrix.md` first and
  prefer `scripts/apply_ide_mcp.py` when the host is `Cursor`,
  `Antigravity`, `VSCode-host`, or `Windsurf`.
- For persistent runtime `memory-palace` install or projection across hosts,
  prefer `scripts/apply_runtime_global_setup.py`.
- If the user is looking at Dashboard first-run setup UI or screenshots, read
  `references/ui-setup-assistant.md`.

## Mandatory Workflow

1. State which object is being installed right now:
   - onboarding skill
   - canonical runtime skill
   - when naming the target project, prefer the GitHub repo URL
     `https://github.com/AGI-is-going-to-arrive/Memory-Palace`
   - only switch to a local checkout path when the next command truly needs one
2. Diagnose the user's host, goal, platform, and scope.
3. Separate onboarding access from runtime skill visibility and MCP binding.
4. Default the onboarding layer to repo URL or direct doc reads unless the user
   explicitly wants to install `memory-palace-setup` as a persistent skill.
   - if the user wants the runtime `memory-palace` layer available across
     folders, prefer `scripts/apply_runtime_global_setup.py`
5. Recommend the smallest correct path.
6. Prefer one copyable command block per step.
7. After each step, tell the user what success should look like.
8. Validate with the smallest relevant check before moving on.
9. Do not stop at `mcp list`; require at least one real smoke call.
10. If a prerequisite is missing, stop and say exactly what must be fixed
    first.

When the user asks “global or repo-local by default?” across multiple hosts:

- answer the cross-host default policy first
- only ask a follow-up question afterward if the next command block depends on
  the specific host

## Hard Rules

- Do not recommend `MCP-only` as the primary path when the user wants normal
  daily use on a supported host.
- Do not assume “the service is running” means “the client is connected.”
- Do not collapse onboarding access, runtime skill visibility, and MCP binding
  into one generic scope answer.
- Do not dodge a direct cross-host default-scope question by immediately asking
  “which host?” when the user is clearly asking for the default policy itself.
- Do not default `memory-palace-setup` itself to persistent global installation.
- If the user wants something installed persistently, prioritize the main repo's
  runtime `memory-palace` skill instead.
- If the user wants a stable setup-repo-managed command path for persistent
  runtime install, prefer `scripts/apply_runtime_global_setup.py` before
  spelling out lower-level host-specific script combinations.
- If the user is using an IDE host with global runtime projection, do not hide
  the selected-checkout caveat.
- Do not present hidden skill mirrors as the default entry path for IDE hosts.
- For IDE hosts, route to repo-local `AGENTS.md + render_ide_host_config.py`.
- For `Cursor`, `Antigravity`, `VSCode-host`, and `Windsurf`, prefer automatic MCP config
  before asking the user to paste JSON manually.
- If the host CLI claims success, still verify the actual config file changed.
- For CLI clients, keep the current MCP guidance unchanged:
  - stable default remains **user-scope first**
  - only add workspace/project-level entries when they are actually needed,
    especially for `Claude` and `Gemini`
- Treat `Codex` and `OpenCode` as **user-scope MCP first**.
- Treat the Dashboard setup assistant as a convenience layer, not proof that
  the client integration is complete.

## Output Contract

Your answer should usually contain:

- one short diagnosis
  - current host
  - current platform
  - current mode
  - current onboarding access mode
  - current runtime skill visibility scope
  - current MCP scope
- one step at a time
- exact commands
- one verification signal after each step
- one real smoke step before calling setup “done”
- one explicit next step

Do not dump every path at once unless the user asks for a comparison.

## Example Prompts That Should Trigger This Skill

- “使用这个 skill 帮我安装配置 Memory Palace 项目。”
- “Help me install and configure Memory Palace step by step.”
- “我想让 Claude Code / Codex / Gemini / OpenCode 接这个项目，优先走 skills + MCP。”
- “我想让 Cursor / Windsurf / VSCode-host / Antigravity 接这个项目。”
- “帮我判断我是该走 repo-local，还是 Docker `/sse`。”
- “我只配了 MCP，但现在想补完整的 skill 安装。”
- “默认到底该把什么全局安装？MCP 逻辑先别改。”

## Example Prompts That Should Not Trigger This Skill

- “帮我写一条长期记忆。”
- “为什么 `guard_action=NOOP`？”
- “修一下前端页面布局。”
- “解释一下 SQLite 检索实现。”