npm package: @richardhhhhhh/personas
Description: Universal AI learning system - autonomous knowledge acquisition and skill indexing
Author: richardhhhhhh
Latest version: 0.1.0

# Personas

[![CI](https://github.com/richardhhhhhh/personas/actions/workflows/ci.yml/badge.svg)](https://github.com/richardhhhhhh/personas/actions/workflows/ci.yml)
[![npm version](https://badge.fury.io/js/@richardhhhhhh%2Fpersonas.svg)](https://badge.fury.io/js/@richardhhhhhh%2Fpersonas)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Claude Code that learns and gets smarter with every interaction** 🧠

Personas transforms Claude Code into a continuously learning AI assistant. Every question you ask, every problem you solve together - Claude remembers, learns, and gets better at helping **you** specifically.

---

## 🎯 The Problem

Claude forgets everything after each conversation. You explain the same architecture patterns, face the same debugging challenges, and repeat the same context over and over.

## ✨ The Solution

**Personas makes Claude learn from your interactions**:

```
Week 1: "How do I optimize this API?"
→ Claude gives generic advice
→ Proficiency: 65%

Week 4: "How do I optimize this other API?"
→ Claude remembers what worked for YOU
→ Uses YOUR code patterns
→ Proficiency: 82% ↗️

Week 8: "API performance issue again"
→ Claude instantly recognizes the pattern
→ Suggests solutions that worked before
→ Proficiency: 91% ↗️↗️
```

**Your Claude Code gets smarter every time you use it.**

---

## ⚡ Install in 10 Seconds

```bash
curl -fsSL https://raw.githubusercontent.com/richardhhhhhh/personas/main/install.sh | bash
```

That's it! Restart Claude Code and try `/personas:dashboard`.

<details>
<summary>Or install with npm...</summary>

```bash
npm install -g @richardhhhhhh/personas
personas init
# Restart Claude Code
```
</details>

<details>
<summary>Or install from source...</summary>

```bash
git clone https://github.com/richardhhhhhh/personas.git
cd personas && npm install
npm run build
# Restart Claude Code with: claude --plugin-dir /path/to/personas
```
</details>

---

## 📊 See It Learn in Real-Time

**First time asking:**
```bash
You: "How do I fix slow database queries?"

📊 Stats:
- API N+1 Optimization: 75% proficiency
- Database Indexing: 70% proficiency
- 0 interactions with you

Claude: [gives standard optimization advice]
```

**After Claude helps you successfully:**
```bash
📊 Stats:
- API N+1 Optimization: 78% ↗️ (+3%)
- Database Indexing: 73% ↗️ (+3%)
- 1 successful interaction recorded
- Average response improved by 15%
```

**Next time you ask about database performance:**
```bash
Claude: [instantly recalls what worked for YOUR codebase]
        [suggests patterns specific to YOUR stack]
        [references YOUR previous solutions]

📊 Stats:
- API N+1 Optimization: 81% ↗️↗️
- Database Indexing: 76% ↗️↗️
- 2 successful interactions
- Getting smarter every time! 🚀
```

---

## 🎁 What You Get

### 🧠 Continuous Learning
- **Every success makes Claude smarter** - Proficiency increases automatically
- **Learns from failures too** - Adjusts to avoid what didn't work
- **Adapts to your tech stack** - Focuses on your specific tools and patterns

### ⚡ Instant Skill Retrieval
- **<50ms retrieval** - No noticeable delay
- **Automatic context injection** - Claude gets relevant skills with every prompt
- **Smart filtering** - Only retrieves skills relevant to your question

### 🎯 Role-Based Intelligence
- **Backend developer?** Focuses on APIs, databases, microservices
- **Frontend developer?** Emphasizes React, CSS, UI patterns
- **DevOps engineer?** Prioritizes K8s, Docker, CI/CD

```bash
# Create specialized roles
/personas:create backend-engineer
/personas:create frontend-dev

# Switch between them
/personas:switch backend-engineer

# Each role learns independently!
```

### 📈 Track Your Progress
```bash
/personas:stats

📊 Personas Learning Statistics

Active Role: backend-developer

Overall Progress:
- Total Skills: 47
- Total Episodes: 234
- Average Proficiency: 84.2% ↗️ (was 68.1%)
- Success Rate: 91.3%

Top Skills:
1. API N+1 Query Optimization - 94% (89 uses)
2. Redis Caching Patterns - 91% (67 uses)
3. PostgreSQL Index Tuning - 88% (54 uses)
```

---

## 💡 How It Works

**100% Automatic. Zero Configuration.**

### 1. You Ask Claude Anything
```
You: "How do I debug this slow endpoint?"
```

### 2. Personas Retrieves Relevant Skills (Behind the Scenes)
```
[Searching: database, api, performance...]
Found 3 relevant skills:
- API N+1 Optimization (proficiency: 91%)
- Database Query Analysis (proficiency: 87%)
- Caching Strategies (proficiency: 84%)
[Injecting into prompt...]
```

### 3. Claude Responds with Enhanced Knowledge
```
Claude: "Based on our previous work optimizing endpoints:
        1. Check for N+1 queries (we fixed this in user-profile API)
        2. Add database indexes (like we did for posts table)
        3. Consider Redis caching (works great for your stack)"
```

### 4. Personas Learns from the Outcome
```
✓ Solution worked!
→ API N+1 Optimization: 91% → 94% (+3%)
→ Database Query Analysis: 87% → 90% (+3%)
→ Success recorded: Episode #235
```

**Next time you ask about performance, Claude will be even better.**

---

## 🎭 Multiple Roles, Multiple Specializations

```bash
# Morning: Backend work
/personas:switch backend-engineer
# Claude focuses on: APIs, databases, microservices

# Afternoon: Frontend work
/personas:switch frontend-dev
# Claude focuses on: React, TypeScript, UI/UX

# Each role learns separately!
# backend-engineer: 234 episodes, 84% proficiency
# frontend-dev: 156 episodes, 79% proficiency
```

---

## 🔧 Commands

```bash
/personas:dashboard    # Dashboard and main menu
/personas:stats        # View learning progress
/personas:search       # Search skills database
/personas:create       # Create new role
/personas:switch       # Switch roles
/personas:list         # List all roles
/personas:export       # Backup your learning data
/personas:import       # Restore from backup
```

**CLI Commands:**
```bash
personas status                           # Show installation status
personas export                           # Export to ~/personas-backup.json
personas export ~/my-backup.json          # Export to custom location
personas import ~/personas-backup.json    # Restore from backup
```

---

## 🚀 Real Example

**Day 1:**
```
You: "How to optimize React rendering?"
Claude: [standard React optimization advice]
📊 React Performance: 65% proficiency
```

**Day 7:**
```
You: "Another component is slow"
Claude: "Remember we used React.memo for the UserList component?
        Same pattern will work here. Also, consider the useMemo
        hook like we did for the expensive calculations."
📊 React Performance: 79% proficiency ↗️
```

**Day 30:**
```
You: "Performance issue in dashboard"
Claude: "I notice your performance issues typically stem from:
        1. Large list re-renders (fixed 3 times before)
        2. Unoptimized useEffect hooks (fixed 5 times)
        Let's check both - here's what worked last time..."
📊 React Performance: 91% proficiency ↗️↗️
```

**Claude learned YOUR patterns, YOUR codebase, YOUR solutions.**

---

## 📚 Features

- ✅ **Automatic Learning** - No manual skill entry required
- ✅ **Cross-Session Memory** - Remembers across Claude Code restarts
- ✅ **Role-Based Focus** - Different skills for different roles
- ✅ **Fast Retrieval** - <50ms, no noticeable delay
- ✅ **Privacy First** - All data stored locally on your machine
- 🚧 **GitHub Integration** - Auto-learn from your repos (coming soon)
- 🚧 **Team Sharing** - Share skills with your team (coming soon)

---

## 💾 Take Your Learning With You

**Your learning is portable!** Moving to a new machine? No problem.

### Export Your Data

```bash
# Backup everything
personas export

# Creates: ~/personas-backup.json
```

### Import on New Machine

```bash
# On your new computer
npm install -g @richardhhhhhh/personas
personas init
personas import ~/personas-backup.json

# All your learning is back! ✅
```

### What Travels With You

✅ All skills and proficiency scores
✅ Complete learning history (234 episodes)
✅ Role configurations (tech stack, tools)
✅ Attention weights (what you focus on)
✅ Success rates and patterns

### Use Cases

- 🖥️ **New computer** - Take your learning with you
- 🔄 **Multiple machines** - Sync via Dropbox/Google Drive
- 👥 **Team sharing** - Share team knowledge base
- 💾 **Backup** - Don't lose months of learning

```bash
# Example: Sync across machines
# Machine A
personas export ~/Dropbox/personas.json

# Machine B
personas import ~/Dropbox/personas.json
```

**Your learning follows you everywhere.** 🚀

---

## 🔒 Privacy & Security

- **100% Local** - All data stored in `~/.personas/` on YOUR machine
- **No Telemetry** - We don't collect or send any data
- **No Cloud Sync** - Your skills stay private unless you explicitly share them
- **Open Source** - Review the code yourself
- **Portable Backups** - You control where your data goes

---

## 💬 FAQ

**Q: Does this send my data anywhere?**
A: No. Everything stays on your machine in `~/.personas/`.

**Q: Will this slow down Claude Code?**
A: No. Skill retrieval adds <50ms, barely noticeable.

**Q: Can I use this without Claude Code?**
A: Yes! Personas works as a standalone library. See [CONTRIBUTING.md](./CONTRIBUTING.md) for API docs.

**Q: What if I don't like a learned skill?**
A: Skills are just SQLite data. You can view, edit, or delete them anytime.

**Q: Can I share skills with my team?**
A: Export/import is coming in v0.5.0. For now, you can copy the `~/.personas/` folder.

---

## 🛠️ Technical Details

- **Storage**: SQLite with FTS5 full-text search
- **Performance**: <50ms retrieval, <20ms learning update
- **Architecture**: Attention mechanism prevents knowledge pollution
- **Node.js**: Requires 22.x or higher

See [CONTRIBUTING.md](./CONTRIBUTING.md) for architecture details.

---

## 🗺️ Roadmap

- **v0.1.0** (Current): Core learning engine ✅
- **v0.2.0**: GitHub connector - auto-learn from your repos
- **v0.3.0**: Vector embeddings - semantic search
- **v0.4.0**: Team sharing and knowledge export
- **v1.0.0**: Production-ready release

---

## 🤝 Contributing

Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for:
- Code style guide
- Development setup
- Architecture overview
- How to add features

---

## 📄 License

MIT License - See [LICENSE](./LICENSE) for details

---

## 🔗 Links

- **GitHub**: https://github.com/richardhhhhhh/personas
- **Issues**: https://github.com/richardhhhhhh/personas/issues
- **Discussions**: https://github.com/richardhhhhhh/personas/discussions

---

<div align="center">

### Stop Repeating Yourself. Let Claude Learn.

```bash
curl -fsSL https://raw.githubusercontent.com/richardhhhhhh/personas/main/install.sh | bash
```

**Your Claude Code gets smarter with every interaction. Start today.** 🚀

</div>