# Configuring Claude Code Auto-Save Hooks for Session Persistence in MemPalace

> Configure Claude Code auto-save hooks in MemPalace to prevent session expiration and data loss. Persist your palace state to disk with simple shell scripts.

- Repository: [MemPalace/mempalace](https://github.com/MemPalace/mempalace)
- Tags: how-to-guide
- Published: 2026-06-07

---

**MemPalace prevents Claude Code's 30-day session expiration from causing data loss by executing [`mempal_save_hook.sh`](https://github.com/MemPalace/mempalace/blob/main/mempal_save_hook.sh) and [`mempal_precompact_hook.sh`](https://github.com/MemPalace/mempalace/blob/main/mempal_precompact_hook.sh) after every MCP command to persist the palace state to disk.**

Session persistence in the MemPalace memory system relies on auto-save hooks that integrate with Claude Code's MCP client. When configured correctly, these hooks ensure that every utterance and index update is preserved verbatim to disk, allowing seamless resumption of work across Claude Code sessions. The hooks reside in the repository's `hooks/` directory and communicate with the core MCP server implemented in [`mempalace/mcp_server.py`](https://github.com/MemPalace/mempalace/blob/main/mempalace/mcp_server.py).

## Why Session Persistence Requires Auto-Save Hooks

Claude Code sessions expire after 30 days of inactivity, which destroys any in-memory state held by the client. Without persistent storage, the **BM25 + vector hybrid index** and **knowledge graph** built during a MemPalace session would vanish. The auto-save hooks solve this by writing atomic checkpoints after every command and before compression operations, ensuring the `data/palace.db` (or the path defined by `MEMPALACE_DATA_DIR`) always contains the latest state.

## Understanding the Hook Architecture

The persistence layer consists of two shell scripts located in the `hooks/` directory. Claude Code's MCP client automatically detects and executes these scripts by name when they exist in the repository root.

### The Save Hook (mempal_save_hook.sh)

**[`hooks/mempal_save_hook.sh`](https://github.com/MemPalace/mempalace/blob/main/hooks/mempal_save_hook.sh)** runs immediately after every successful MCP command issued by Claude Code. It serializes the current palace state—including new chunks, embeddings, and graph mutations—to the configured data directory. According to the MemPalace source code, this hook ensures the "verbatim always" storage principle is maintained by flushing memory to disk without requiring manual intervention.

### The Pre-Compact Hook (mempal_precompact_hook.sh)

**[`hooks/mempal_precompact_hook.sh`](https://github.com/MemPalace/mempalace/blob/main/hooks/mempal_precompact_hook.sh)** executes just before the index compression step (referred to as the AAAK "pre-compact" phase). This hook forces a clean checkpoint so that the compression process, which reorganizes the AAAK dialect pointers, starts from a fully persisted state. This prevents accidental loss of recent writes during the compacting phase.

## Step-by-Step Configuration

Configuring Claude Code auto-save hooks for session persistence requires three actions:

1. **Verify the scripts exist** in your local clone of the `MemPalace/mempalace` repository.

2. **Make the hooks executable** so Claude Code can spawn them as subprocesses:

```bash
chmod +x hooks/mempal_save_hook.sh hooks/mempal_precompact_hook.sh

```

3. **Reference the repository root** in Claude Code's MCP configuration. The client searches for hook scripts relative to the workspace root, so ensure your Claude Code settings point to the directory containing the `hooks/` folder.

Once configured, the MCP server will automatically invoke these hooks. For example, after running a mining command:

```bash
mempalace mine ~/myproject

```

The [`mempal_save_hook.sh`](https://github.com/MemPalace/mempalace/blob/main/mempal_save_hook.sh) script executes automatically, writing a checkpoint to `./data/palace.db` (or your custom `MEMPALACE_DATA_DIR`).

## How the Hooks Interact with the MCP Server

The core logic resides in **[`mempalace/mcp_server.py`](https://github.com/MemPalace/mempalace/blob/main/mempalace/mcp_server.py)**, which implements the MCP protocol over STDIO JSON-RPC. When the server receives a command, it processes the request and then signals the hook subsystem. On startup, the server checks for existing checkpoints in the data directory and loads them to restore the previous session state. This architecture satisfies MemPalace's "incremental only" design principle by ensuring no data is lost between the 30-day expiration windows.

## Validating Your Configuration

To verify that your hooks are functioning correctly, examine the test suite in **[`tests/test_save_hook_verbose.py`](https://github.com/MemPalace/mempalace/blob/main/tests/test_save_hook_verbose.py)**. This file validates that the save hook correctly writes state files and that the pre-compact hook triggers before compression operations. You can run these tests to confirm your environment properly persists data:

```bash
python -m pytest tests/test_save_hook_verbose.py -v

```

Successful test execution confirms that Claude Code will retain your MemPalace sessions beyond the automatic expiration period.

## Summary

- **MemPalace** requires **[`mempal_save_hook.sh`](https://github.com/MemPalace/mempalace/blob/main/mempal_save_hook.sh)** and **[`mempal_precompact_hook.sh`](https://github.com/MemPalace/mempalace/blob/main/mempal_precompact_hook.sh)** in the `hooks/` directory to persist sessions.
- The **save hook** writes checkpoints after every MCP command, while the **pre-compact hook** ensures clean state before index compression.
- Both scripts must be **executable** and located at the repository root for Claude Code's MCP client to discover them.
- Persistent data is stored in `data/palace.db` by default, or wherever `MEMPALACE_DATA_DIR` points.
- The **[`mempalace/mcp_server.py`](https://github.com/MemPalace/mempalace/blob/main/mempalace/mcp_server.py)** implementation handles STDIO JSON-RPC and automatic checkpoint loading on startup.

## Frequently Asked Questions

### What happens if I don't configure the auto-save hooks?

Without the hooks configured, Claude Code will display a warning that "Claude Code sessions expire in 30 days without auto-save hooks wired." While the system will function temporarily, any data accumulated during the session will be lost when the 30-day expiration triggers, as the in-memory palace will not be written to disk.

### How do the hooks handle the MEMPALACE_DATA_DIR environment variable?

Both [`mempal_save_hook.sh`](https://github.com/MemPalace/mempalace/blob/main/mempal_save_hook.sh) and [`mempal_precompact_hook.sh`](https://github.com/MemPalace/mempalace/blob/main/mempal_precompact_hook.sh) respect the `MEMPALACE_DATA_DIR` environment variable. If set, they write checkpoints to that directory instead of the default `./data/` location. This allows you to store session data on separate volumes or cloud-synced directories for additional durability.

### Can I manually trigger the save hook for debugging?

Yes, you can invoke the save hook manually to force an immediate checkpoint. This is useful when debugging session persistence or when preparing for a manual compression step:

```bash
./hooks/mempal_save_hook.sh
./hooks/mempal_precompact_hook.sh
mempalace compact

```

Manual execution follows the same code path as the automatic MCP-triggered invocation.

### Where does the persistent data actually get stored?

By default, the hooks write to `data/palace.db` in the repository root. However, if the `MEMPALACE_DATA_DIR` environment variable is defined, the system uses that path instead. The checkpoint files contain the full BM25 indices, vector embeddings, and knowledge graph required to restore your MemPalace session exactly as it was before interruption.