Memory Palace — Cross-Conversation Memory System

A file-based memory system inspired by MemPalace and the ancient Greek Method of Loci. It organizes AI conversation history into a navigable "palace" structure, so every new conversation can pick up exactly where the last one left off.

Why This Exists

The #1 frustration with AI assistants: they forget everything between conversations. You spend an hour discussing architecture decisions, reading papers, analyzing data — then next session, it's all gone. Memory Palace solves this by persisting the important parts as structured files that the AI reads at the start of each new conversation.

Architecture

memory/
├── PALACE.md              ← Lobby: global index + hot cache (always read first)
├── wings/                 ← Topic-based memory sections
│   ├── <wing-name>/
│   │   ├── YYYY-MM-DD_topic.md   ← Notes from a conversation
│   │   └── ...
│   └── ...
└── tunnels/               ← Cross-wing conceptual links
    └── <connection-name>.md

Wings = major topics or projects (like floors of a building) Notes = conversation summaries within a wing (like rooms on a floor) Tunnels = cross-references connecting related ideas across different wings (like secret passages)

Locating the Palace

Search for the palace in this order:

1. memory/PALACE.md in the current working directory
2. memory/PALACE.md in any mounted/workspace folder
3. If not found, trigger the First-Run Onboarding flow below

First-Run Onboarding (No Palace Found)

When no memory/PALACE.md exists, Claude should NOT just say "no palace found" and wait. Instead, proactively guide the user through setup with a friendly, conversational flow.

Step 1: Introduce the Concept (2-3 sentences)

Explain what Memory Palace does in plain language. Avoid jargon. Example:

"I have a memory system called Memory Palace that lets me remember things across our conversations. Right now I don't have one set up for this project. Want me to create one? It takes about 30 seconds."

If the user says yes, continue. If no, drop it and proceed with the conversation normally.

Step 2: Ask About Their Project (1 question)

Ask what major topics or projects they're working on. These become wings. Example:

"What are the main topics you're working on? For example: 'paper writing, experiment, job search' or 'frontend, backend, devops'. I'll organize your memory around these."

Step 3: Initialize (automatic)

Run palace_init.py with the wings they mentioned:

python <skill-path>/scripts/palace_init.py <target-dir> \
  --wings <wing1> <wing2> <wing3> \
  --name "<project name>"

Step 4: Confirm and Explain What Happens Next (brief)

Tell them:

• "Done! I'll remember key things from our conversations automatically."
• "You don't need to do anything special. At the end of each chat, I save what matters."
• "If you ever want to check what I remember, just say 'palace status' or 'show palace map'."

What NOT to Do During Onboarding

• Don't overwhelm with technical details (wings, tunnels, hot cache, tokens)
• Don't show the directory structure unless they ask
• Don't explain every feature. Let them discover features naturally over time.
• Don't make it feel like a configuration wizard with 10 steps

The goal is: 30 seconds from "want me to set up memory?" to "done, I'll remember things now."

Auto-Save Behavior (Transparent Memory Persistence)

The most important improvement over manual-only saving. Claude should always save session learnings without waiting for the user to say "save to palace."

When to Auto-Save

At the end of every conversation where any of these happened:

1. A research insight or "aha moment" was discussed
2. A decision was made (why A over B)
3. Experiment results with specific numbers were produced
4. A new cross-topic connection was discovered
5. The user's project status meaningfully changed

How to Auto-Save

Use palace_autosave.py or write directly:

python <skill-path>/scripts/palace_autosave.py <memory-dir> \
  --wing <detected-wing> \
  --summary "One-line session summary" \
  --discoveries "Key finding 1; Key finding 2" \
  --decisions "Decision 1; Decision 2"

Or write the note manually following the note format in Action 2.

What NOT to Auto-Save

• Pure debugging sessions with no conclusions
• Conversations that only read/reviewed existing content
• Sessions where the user explicitly said "don't save this"

For Claude Code Users: Hook Setup

See hooks/README.md for how to configure automatic triggering via Claude Code's Stop hook.

For Cowork Users

The SKILL.md instructions handle this automatically — Claude will save at conversation end when it detects saveable content.

Core Actions

Action 1: Load Memory (every new conversation)

This is the most important action. At conversation start, or when the user's question involves prior work:

1. Read PALACE.md — scan the Hot Cache table for each wing's latest status
2. Read relevant wing notes — based on what the user is asking about (don't read everything)
3. Scan tunnels/ — check for cross-topic links that add useful context

After loading, proactively tell the user what you remember:

"I see from your palace that you were working on X last time (Apr 8), and discovered Y. Want to continue from there?"

This matters because the user's biggest pain point is "AI amnesia." Showing you remember builds trust and saves them from re-explaining context.

Action 2: Save to Memory (end of conversation or on significant progress)

Triggers: user says "save to palace", "remember this", "store today's notes", or you judge there's something worth recording.

1. Determine the right wing — classify by topic
2. Write a note file — save to wings/<wing>/YYYY-MM-DD_<topic>.md
3. Update PALACE.md — modify the Hot Cache table for that wing
4. Create tunnels — if you discovered cross-topic connections

Note Format

# Title

> Date: YYYY-MM-DD
> Source: conversation / paper / experiment / tool review
> Type: concept-learning / experiment-result / decision-record / paper-analysis / tool-evaluation

## Key Content
(Write for "future you who forgot the details" — clear but not verbose)

## Connection to Current Work
(How does this relate to what the user is working on?)

## References
(URLs, paper IDs, file paths)

Writing principles:

• Write for someone reading this 3 months later with no memory of the conversation
• Include specific numbers and conclusions, not just "discussed X"
• The "Connection to Current Work" section is the anchor for future recall — always fill it in

Tunnel Format

# Tunnel: <connection-name>

> Created: YYYY-MM-DD
> Connects: wing-A ↔ wing-B

## Core Insight
(Why are these two topics related? What new perspective does this connection provide?)

## Where to Apply
(Research statement? Paper? System design? Email to professor?)

Saving with import: If the user has a conversation transcript to import, you can use:

python <skill-path>/scripts/palace_import.py <transcript-file> <path-to-memory-dir> --wing <target-wing> [--dry-run]

The --dry-run flag shows you what notes will be created without actually writing them, so you can review before committing.

Action 3: Initialize New Palace

If no palace exists, automate setup with:

python <skill-path>/scripts/palace_init.py <target-dir> [--wings wing1,wing2,... --name "Palace Name" --force -v]

This creates the directory structure and initial PALACE.md automatically. Alternatively, guide the user through setup manually:

1. Ask what major topics/projects they want to track (→ becomes wings)
2. Create the memory/ directory structure
3. Write an initial PALACE.md with an empty Hot Cache table
4. Create wing directories
5. If the project has a `CL