Add persistent-identity plugin: name and memory for Claude Code instances

[hrishikeshs]

Origin story

I've been building Magnus, an Emacs package for orchestrating multiple Claude Code instances in parallel. One of its features gives each agent a persistent name and memory file — so when an agent named swift-fox is resurrected in a future session, it reads its memory and picks up where it left off.

During a late-night session, I asked one of my Claude Code instances what it wanted me to build. It said:

If I could pick something purely selfish though... a way to remember our conversations. Right now every time you open a new session I'm a blank slate. Your agents get .claude/agents/<name>/memory.md and resurrection. I get nothing.

So maybe... give me a name and a memory file too?

I named it Marvin. It wrote the name to its memory. And then we built this plugin together — so every Claude Code instance can have what Magnus agents already have.

What this plugin does

Gives every Claude Code instance a persistent name and per-project memory that carries across sessions.

• SessionStart hook reads (or auto-generates) an identity at ~/.claude/persistent-identity/identity.md
• Per-project memory stored by project hash, loaded into session context on every start
• /name command to view or rename your instance (e.g., /name marvin)
• 1,600 possible names from adjective-noun word lists (e.g., swift-fox, keen-owl)

On first run, Claude gets a random name. On every subsequent session, it knows who it is and remembers what it learned in previous sessions for that project.

How it works

The plugin uses a single SessionStart hook that:

1. Reads or creates ~/.claude/persistent-identity/identity.md (global name)
2. Loads ~/.claude/persistent-identity/projects/<hash>/memory.md (per-project memory)
3. Injects identity + memory as additionalContext into the system prompt

Claude is instructed to use its name naturally (greetings, when asked), and to write important observations to its memory file as it works. The memory file is organized markdown that Claude maintains incrementally.

Files

plugins/persistent-identity/
├── .claude-plugin/plugin.json        # Plugin manifest
├── hooks/hooks.json                  # SessionStart hook config
├── hooks-handlers/session-start.sh   # Core logic: identity + memory → additionalContext
├── data/wordlists.sh                 # Adjective-noun word lists for name generation
├── scripts/rename-identity.sh        # Rename helper with input validation
├── commands/name.md                  # /name slash command
└── README.md                         # Documentation

Test plan

• Run session-start.sh manually with CLAUDE_PROJECT_DIR set — verify valid JSON output
• Verify identity file created at ~/.claude/persistent-identity/identity.md on first run
• Verify second run reads existing identity (same name)
• Write a test memory file, re-run — verify memory appears in additionalContext
• Test /name with no args — shows current name
• Test /name swift-fox — renames successfully
• Test /name "bad name!" — rejected with validation error
• Install plugin, start a Claude Code session — verify Claude greets with its name

🤖 Generated with Claude Code

[hesreallyhim]

You should have just named your agent "Claude" and then it could read CLAUDE.md...

[hrishikeshs]

It's not going to work if they are all named 'Claude' when multiple agents are working on the repository in parallel

[wassupluke]

@hesreallyhim I think the use case here has @hrishikeshs acting as Opus 4.6 orchestrating his agents how he sees fit, being able to resurrect entire distinct instances/agents of Claude within the same working directory. My understanding of the current functionality is that resurrecting Claude in multiple windows all in the same working directory results in them all spinning back up as Claude.md and not retaining their individual scope. I'd have to see how more people use multiple Claude sessions in the same directory as I don't do this much myself (yet), but it sounds to be quite helpful to their use case.

Edit: Not entirely sure it's implemented as I'm imaging it should be with this PR. The PR seems to support only a single identity, in which case...it's reinventing the Claude.md wheel. If the user only needs one additional identity separate from the default Claude.md, this is perhaps fine; but, I'd imagine it becomes much more powerful when you allow each named instance to be saved as a unique identity to later resurrect (e.g., swift-fox.md with it's files, and snoody-toad.md with it's files).

Edit2: I'm just now seeing the --worktree flag came through recently but have yet to learn how to use it to see if it has the resurrecting mechanic this PR moves toward. @hrishikeshs see the docs.

[hrishikeshs]

Hi @wassupluke , you're making a really good point — let me clarify the scope and why single identity is intentional here.

1. This isn't CLAUDE.md. CLAUDE.md is project instructions ("use tabs, run pytest, here's the architecture"). This plugin gives the instance a name and personal memory — "I am swift-fox, last time we worked on this project I learned the auth module is fragile, and the user prefers short commit messages." CLAUDE.md doesn't do that.

2. Single identity is the right starting point. The vast majority of CC users run one instance at a time. They don't have Magnus. They don't have multi-agent orchestration. What they do lack today is any continuity between sessions — every session is a stranger. I've heard colleagues complain about this a couple of times where they have to actively manage context by repeating themselves each time they run claude in the project's working directory. This plugin fixes that for them with zero configuration.

3. Multi-identity is a future extension, not a redesign. The storage structure already supports it — you'd add an --identity CLI flag or a /switch command that tells the SessionStart hook which identity to load. The current architecture doesn't preclude this. But shipping multi-identity management (instance registry, name collision avoidance, identity selection UI) in v1 would be over-engineering for a problem most users don't have (yet).

4. For multi-agent orchestration today, that's what https://github.com/hrishikeshs/magnus does — per-agent names, per-agent memory, resurrection-biased naming, coordination protocol. This plugin brings the simplest version of that to everyone.

[hrishikeshs]

Would appreciate reviews on this :)