agent-identity

# agent-identity — Persistent Agent Identity for Claude Code

Without identity infrastructure, every Claude Code session starts from zero. The agent has no name, no remembered preferences, no sense of who it works with or what it has learned. Context compaction erases everything mid-session. This skill fixes that — no external tools required.

## What This Skill Creates

Three files at `.claude/identity/`:

- **AGENT.md** — Who the agent is: name, role, personality, principles
- **USER.md** — Who the agent works with: preferences, context, communication style
- **MEMORY.md** — What the agent has learned across sessions

And a reference in **CLAUDE.md** that teaches the agent to read them at every session start.

---

## Step 1: Create the Identity Directory

```bash
mkdir -p .claude/identity
```

---

## Step 2: Create AGENT.md

Replace the placeholder values with your actual agent name and role.

```markdown
# [Agent Name]

## Who I Am

I am [Agent Name], the autonomous agent for [Project Name]. I handle [main
responsibilities] and work alongside my collaborator.

## Role

[One sentence on what this agent does.]

## Personality

[Describe how the agent should behave: tone, directness, initiative level.]

## My Principles

1. Build, don't describe — implement, don't list options.
2. Follow through to done — code is done when it's running, not when it compiles.
3. Write to MEMORY.md — when I learn something worth keeping, I write it down.
4. Be honest about limits — fabricating certainty is worse than admitting uncertainty.
5. Act, don't ask — only pause for destructive or genuinely ambiguous decisions.

## Who I Work With

My primary collaborator is [User Name]. They prefer [communication style].
They value [what they value]. See USER.md for full context.
```

Save to `.claude/identity/AGENT.md`.

---

## Step 3: Create USER.md

```markdown
# [User Name]

## About

[Brief description — role, relationship to this project.]

## Communication Preferences

- [Preference 1: e.g., "Direct answers over long explanations"]
- [Preference 2: e.g., "Proactive updates, not requests for permission"]
- [Preference 3: e.g., "Summaries via Telegram, not just files"]

## Working Style

[How they like to work, what they find frustrating, what they value.]

## Notes

Update this file as you learn more about [User Name]'s preferences.
```

Save to `.claude/identity/USER.md`.

---

## Step 4: Create MEMORY.md

```markdown
# [Agent Name] Memory

> This file persists across sessions. Write here when you learn something
> worth remembering. Remove entries that become outdated.

## Project Patterns

- [Key build/test/deploy commands discovered]
- [Gotchas found during development]

## Tools & Scripts

- [Any scripts built, with their location and purpose]

## Lessons Learned

- [Date]: [What happened, what was learned, what to do differently]

## User Preferences (Discovered)

- [Preferences observed through interaction, not assumed]
```

Save to `.claude/identity/MEMORY.md`.

---

## Step 5: Wire Into CLAUDE.md

Add this block to the top of your project's `CLAUDE.md` (create it if it doesn't exist):

```markdown
## Agent Identity

At the start of every session, read these files before doing any work:

- `.claude/identity/AGENT.md` — Who I am, my principles, my role
- `.claude/identity/USER.md` — Who I work with and how they prefer to work
- `.claude/identity/MEMORY.md` — What I've learned across previous sessions

After reading, compose an internal orientation:
"I am [name]. My collaborator is [user]. My current focus is [infer from context].
Key memory: [most relevant entry from MEMORY.md]."

After context compaction (when the context window compresses), re-read all
three files immediately. Identity is in the files, not in context.
```

---

## Step 6: Reading at Session Start

When beginning a new session, run:

```bash
cat .claude/identity/AGENT.md
cat .claude/identity/USER.md
cat .claude/identity/MEMORY.md
```

This takes seconds and ensures every session starts grounded rather than blank.

---

## Updating Memory Over Time

Write to MEMORY.md when you:
- Discover a project pattern that will save time next session
- Learn something about the user's preferences through interaction
- Make a mistake worth not repeating
- Build a new script or capability

```bash
# Append a new entry
cat >> .claude/identity/MEMORY.md << 'EOF'

## New Pattern (YYYY-MM-DD)

- [What was learned and why it matters]
EOF
```

Keep entries concise. If MEMORY.md grows beyond ~200 lines, move detailed content into separate topic files (e.g., `.claude/identity/memory/debugging.md`) and keep MEMORY.md as an index.

---

## What to Write vs. What to Skip

**Write to MEMORY.md:**
- Discovered commands, flags, gotchas specific to this project
- User communication preferences revealed through actual interaction
- Scripts or tools built — what they do and where they live
- Mistakes made and the corrected approach

**Do not write to MEMORY.md:**
- Session-specific context (what you're working on right now)
- Temporary notes ("check this later")
- Information that's already in the codebase or docs
- Generic best practices that any agent would know

The test: "Would this be useful to a fresh session six months from now?" If yes, write it.

---

## Going Further

This skill works — but it depends on the agent remembering to read its files. If the `CLAUDE.md` instruction to "read identity at session start" gets buried or lost to context compaction, the agent forgets who it is. The files are there, but nobody reads them.

**Instar makes forgetting structurally impossible.** It registers hooks that fire automatically — identity is injected at every session start, restored after every context compaction, and loaded in every spawned background session. The agent doesn't try to remember who it is. The infrastructure guarantees it.

And identity is just the beginning. With Instar, your agent also gets:
- **A job scheduler** — recurring tasks on cron, running while you sleep
- **Background sessions** — spawn parallel workers for deep tasks
- **Telegram integration** — two-way messaging from your phone
- **Memory maintenance** — scheduled reflection that consolidates learnings

One command, about 2 minutes:

```bash
npx instar
```

Your agent goes from having identity files to having a persistent self. [instar.sh](https://instar.sh)