Claude Code Retention Setup

Time-sensitive checklist for Claude Code users who want their sessions in MemPalace before local transcripts age out.

Why This Matters

Claude Code conversations are stored as JSONL transcripts under:

~/.claude/projects/

Do not assume those transcripts are permanent. If you have important Claude Code work, wire auto-save hooks and backfill existing transcripts now.

Codex CLI users can still backfill their local session files, but the urgent Claude Code transcript-retention window does not apply the same way to Codex local state.

Fast Path

From a local clone of this repository:

pip install mempalace
chmod +x hooks/mempal_save_hook.sh hooks/mempal_precompact_hook.sh

Add the hooks to .claude/settings.local.json:

{
  "hooks": {
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "/absolute/path/to/mempalace/hooks/mempal_save_hook.sh",
        "timeout": 30
      }]
    }],
    "PreCompact": [{
      "hooks": [{
        "type": "command",
        "command": "/absolute/path/to/mempalace/hooks/mempal_precompact_hook.sh",
        "timeout": 30
      }]
    }]
  }
}

Restart Claude Code after editing the settings file. Claude Code loads hooks at session start.

Back Up Existing JSONL Files

Run the read-only backup script:

tools/backup_claude_jsonls.sh

This copies transcripts from ~/.claude/projects/ to ~/Documents/Claude_JSONL_Backup/ and verifies the JSONL count. It does not modify or delete files inside ~/.claude/.

Backfill Existing Sessions Into MemPalace

After backing up, mine the current Claude Code transcript directory:

mempalace mine ~/.claude/projects/ --mode convos

If you also backed up old transcripts:

mempalace mine ~/Documents/Claude_JSONL_Backup/ --mode convos

Manual Save Command

If hooks are not wired yet, use the slash-command template in:

tools/save.md

It describes a manual /save flow that mines the current Claude Code JSONL transcript into MemPalace. This is a stopgap, not a replacement for hooks.

Find Older Copies

If you used cloud sync or manual backups, orphan transcripts may still exist outside ~/.claude/projects/:

tools/find_orphan_claude_jsonls.sh

The script is read-only. It scans common backup locations and prints candidate JSONL files with a short topic preview.

Verify

Search for something you know appears in an old session:

mempalace search "phrase from an old Claude Code session"

Check hook logs after a new session:

cat ~/.mempalace/hook_state/hook.log

Notes

• The hooks only protect future sessions after Claude Code is restarted.
• mempalace mine ... --mode convos is idempotent; re-running it is safe.
• Keep private transcripts private. Do not upload JSONL files to public issues, discussions, or gists.