msd-core/docs/how-to/enable-cross-session-memory-with-mempalace.md

How to enable cross-session memory with MemPalace

Give GSD durable memory across sessions and projects. When MemPalace is connected, GSD recalls prior decisions and patterns before you plan, and captures phase artifacts verbatim at each phase boundary.

What you need: MemPalace installed locally. GSD never installs MemPalace for you — pip install mempalace is your action. A working MemPalace install is not required to complete GSD work; the capability is onError: skip at every hook, so an absent or unreachable MemPalace leaves the loop unchanged.

---

Step 1 — Install MemPalace

Follow the MemPalace installation guide. The quick path:

pip install mempalace
mempalace init          # creates the local palace (ChromaDB + SQLite)
mempalace status        # verify the server is reachable

For interactive use (Claude Code), MemPalace's MCP server must be running so mempalace_* tool calls resolve. For headless or cron runs, the CLI path (mempalace wake-up, mempalace search, etc.) is used automatically — no MCP server needed.

---

Step 2 — Enable the capability

Inside your GSD project:

gsd-tools query config-set mempalace.enabled true

That is the only required step — mempalace.enabled is the master switch that gates all loop hooks. All other mempalace.* keys are optional refinements of the enabled behavior; they are honored at runtime by the skills, curator, and fragments.

---

Step 3 — Choose a memory mode

The mempalace.memory_mode key controls how tightly MemPalace couples to GSD's native memory. Only augment is implemented today. The other modes are declared for future use — selecting them today has no additional effect beyond augment.

Mode	What it does	When to use it	Status
augment (default)	MemPalace is an additional recall layer alongside .planning/graphs/ and learnings. Lowest coupling — palace is write-mostly and never required.	Most users. Safe to enable immediately.	Implemented
kg_backend	Intended to route knowledge-graph queries through MemPalace's temporal graph instead of .planning/graphs/.	Future use — not yet functional today.	Declared; routing seam not yet implemented
replace	Intended to make the palace the durable store; GSD memory reads would resolve through it.	Future use — not yet functional today.	Declared; not yet functional

Until kg_backend and replace are implemented, changing memory_mode away from augment has no effect. Use the default and revisit when these modes ship.

# memory_mode defaults to augment (the only functional mode today)
# no change needed for most users

---

Step 4 — Run a phase and observe recall and capture

With mempalace.enabled: true, here is what you will see at each loop point:

Discuss phase (/gsd-discuss-phase):

1. At discuss:pre — MemPalace recall fires: prior decisions, patterns, and surprises are surfaced as context before the discussion begins.
2. At discuss:post — CONTEXT.md is filed into the decisions room in MemPalace.

Plan phase (/gsd-plan-phase): 3. At plan:pre — a MEMORY-RECALL.md file appears in the phase directory containing prior decisions, patterns, and surprises retrieved from the palace. 4. At plan:post — PLAN.md is filed into the planning room.

Verify phase (/gsd-verify-work): 5. At verify:post — SUMMARY.md is filed into milestones in MemPalace.

Ship phase (/gsd-ship): 6. At ship:post — the gsd-mempalace-curator agent writes a diary entry and (if enabled) proposes cross-project tunnels.

Execute phase (/gsd-execute-phase, each wave): 7. At execute:wave:post — confirmed problem→fix pairs are captured into the problems room via the capture-problems fragment.

If MemPalace is unreachable at any step, a skip-notice is written and the loop continues normally.

---

Optional configuration

Turn off recall or capture independently

# Disable recall injection at discuss:pre (keeps capture)
gsd-tools query config-set mempalace.recall_on_discuss false

# Disable the MEMORY-RECALL.md step at plan:pre
gsd-tools query config-set mempalace.recall_on_plan false

# Disable artifact capture at phase boundaries
gsd-tools query config-set mempalace.capture_artifacts false

Cross-project tunnels

Enable tunnel proposals at ship:post to connect related rooms across projects:

gsd-tools query config-set mempalace.cross_project_tunnels true

The curator agent will call mempalace_find_tunnels and propose connections to the wings it finds semantically related to this project's wing.

Passive mid-session capture (reserved — not yet implemented)

mempalace.auto_capture_hooks is a forward-declared key reserved for a future "Connected Capability" phase. Setting it to true currently has no effect — no native Claude Code hooks (stop, precompact, session-start) are installed by this key yet. The capability's hooks array is empty; the deliberate loop hooks are the only active integration today.

# Not yet functional — reserved for a future release
# gsd-tools query config-set mempalace.auto_capture_hooks true

Override the wing name

By default, the wing name derives from project_code or the project directory. Override it:

gsd-tools query config-set mempalace.wing my-project-name

---

What to expect when MemPalace is absent

If MemPalace is not installed, not running, or unreachable:

• Every hook logs a skip notice and continues.
• MEMORY-RECALL.md is written with an "unavailable" stub (the planner can still proceed without it).
• No phase step fails or blocks.
• Loop behaviour is identical to having mempalace.enabled: false.

You can safely leave mempalace.enabled: true in a config that will be used on machines without MemPalace — it is safe to do so.

---

Full configuration reference

See MemPalace Settings in the Configuration Reference for the complete key list with types and defaults.