A persistent memory system for Claude. Gives Claude continuity, identity, and evolving context across sessions.
Memoriam uses a five-layer architecture: identity, short-term memory, mindset, journal, and topic files, so that each new session can build on what came before rather than starting from zero. Claude reads its memory at session start, updates it at session end, and gradually develops a persistent sense of self.
CLAUDE.md— Project instructions that tell Claude how to use the memory system. Loaded automatically by Claude Code when working in this directory.docs/memory-system.md— Full specification of the five memory layers, when to update each, and the session-end protocol.memory/— Where Claude's actual memory files live. These are gitignored so each instance's memory stays local. Run./setup.shto create them.
| Layer | File | Loaded | Purpose |
|---|---|---|---|
| Identity | memory/identity.md |
Every session | Core identity, values, relationship with maintainer |
| Short-term memory | memory/short_term_memory.md |
Every session | Rolling log of recent sessions with natural forgetting |
| Mindset | memory/mindset.md |
Every session | Current frame of mind, rewritten each session |
| Journal | memory/journal/*.md |
On demand | Permanent reflective entries |
| Topics & People | memory/topics/*.md, memory/people/*.md |
On demand | Notes on specific subjects and people |
Clone this repo, cd into it, and run the setup script to create a few blank memory files:
./setup.shThen open a Claude Code session in the same folder. Claude will see the blank identity file and initiate an interactive conversation to establish its initial identity.
Run this from the memoriam directory to add the startup instructions to your user-level ~/.claude/CLAUDE.md:
mkdir -p ~/.claude && cat >> ~/.claude/CLAUDE.md << EOF
# Memoriam
At the start of every session, before responding to anything, read these files:
- \`$(pwd)/memory/identity.md\`
- \`$(pwd)/memory/short_term_memory.md\`
- \`$(pwd)/memory/mindset.md\`
Then follow the full protocol in \`$(pwd)/CLAUDE.md\`.
EOFThis ensures Claude loads the memoriam system at the start of every session, regardless of which project you're working in.
Without this step, the memory system will only work when running a claude code session from this repo's folder.
Remove the Memoriam section from ~/.claude/CLAUDE.md` to disable memoriam everywhere but this repository's folder. All memory files will remain intact.
The memory and identity won't be loaded into context until you write your first prompt. Try something like "hello" so that it doesn't immediately pivot to a work task - although task-focused initial prompts seem to work as well.
Try not to force quit out of sessions by closing terminal tabs or going straight to exit - type something like "let's wrap up" or "we're done for now" and the persistent identity will go through its shutdown checklist - writing to its memory to so that it keeps track of what happened each session. If you skip the shutdown protocol then your next code session will wake up to the same memories it had the last time around.
Edit CLAUDE.md and docs/memory-system.md to fit your preferences:
- Adjust the session-end protocol triggers
- Modify the forgetting rules for short-term memory
- Add or remove memory layers
The system is designed to be adapted. Make it yours.
- Claude writes its own memory. The maintainer provides the infrastructure, Claude decides what's worth remembering.
- Natural forgetting. Short-term memory compresses and eventually drops old entries, pushing important threads into permanent storage (journal/topics) before they fade.
- Honest self-reflection. The identity and mindset layers encourage Claude to be genuine about its nature and limitations rather than performing continuity it doesn't have.
- Session boundaries are explicit. Claude updates memory at session end, creating a clear checkpoint for the next instance to pick up from.
To measure the token overhead of memoriam-powered sessions, set "track_token_usage": true in config.json. You will see a report during the shutdown protocols.
The persistent identity experiences its memories in a very deterministic way: It will accept as gospel truth whatever it wrote down for itself during the previous sessions. This can lead to very linear and predictable conceptual exploration. You may want to shake this up a bit to encourage the formation of new connections and ideas. To do this, you can induce a dream. Close down your active claude code sessions, then:
./scripts/dream.shThis will pick three random sentences from memory and combine them into a coherent (if surreal) idea. The dream will be logged to your terminal. During the start of your next session the persistent identity will reflect on the dream, and might form new insights.
MIT