How to give Claude Code persistent project memory

Flow

❯_

Do this with Claude CodeCopy a prompt that links the cckit docs so Claude learns the CLI, then follows these steps.

Copy as Markdown

Before you start

Install cckitQuickstart: your first lifecycle

This tutorial

Intermediate6 min readNeedscckit installed & initializedpipx or uv

What you’ll set up: coding agents are stateless — every session starts from zero, so you keep re-explaining the same architecture and re-deriving decisions you already made. cckit’s optional memory layer (powered by the open-source MemPalace) wires four hooks so each session wakes up already knowing your project and files its work back on its own. The wake-up costs ~600–900 tokens, leaving 95%+ of the window for real work.

Steps

1. Enable memory when you initialize. Say yes to memory at cckit init, or pass it explicitly:

   cckit init --profile software --memory on

2. Let doctor install the engine. cckit doctor sees memory is on and installs the MemPalace CLI into an isolated environment, then points you at the MCP wiring:

   cckit doctor     # installs mempalace + seeds this project's wake-up header
   mempalace mcp    # print the MCP-server setup line for Claude Code

   Prefer to do it by hand? pipx install mempalace.

3. That’s it. Every session now loads a wing-scoped wake-up header plus your project’s recent decisions. The full recall/record protocol lives in the scaffolded .claude/rules/mempalace.md — you never have to say “remember this”.

How it works

Memory is first-class in the lifecycle, not a bolt-on. Four hooks wire it into every session: SessionStart loads a wing-scoped wake-up, Stop files the finished session, PreCompact sweeps to memory before the window compresses, and SessionEnd catches unsynced work if a session ends abruptly. Each project gets one wing, so memories never bleed across repos, and cckit doctor keeps the layer healthy as the kit evolves.

Built on MemPalace — credit where it's due

The memory engine, palace format, and MCP server are the work of the open-source MemPalace project. cckit only scaffolds the hooks and the per-wing header — MemPalace does the remembering. cckit is not affiliated with the project; direct MemPalace bugs to its own issue tracker.

Troubleshooting

doctor didn’t install MemPalace. It only installs it when memory is on. Re-run cckit init with --memory on (or answer yes), then cckit doctor.

Claude isn’t recalling anything. Confirm the MCP server line from mempalace mcp is wired into Claude Code, and that .claude/rules/mempalace.md exists — it’s what teaches Claude to recall before answering.

Memories from another repo showed up. They shouldn’t — memory is scoped per wing (one per project). Check you’re in the right repo and that its wing name in the config is unique.

Related tutorials

Run checks automatically with cckit hooks The hook system memory plugs into.

Set up cckit in a repo Initialize the repo where you turn memory on.

Drive Claude Code headless in CI Keep hand-offs token-lean, memory included.