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

MemPalace prevents Claude Code's 30-day session expiration from causing data loss by executing mempal_save_hook.sh and 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.

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 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 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:

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:

mempalace mine ~/myproject

The 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, 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. 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:

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 and 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 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 and 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:

./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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}