paif/README.md

# PAIF — Persistent Agent Identity Framework

A system for AI agents to exist as persistent entities rather than ephemeral assistants.

## Core Concept

PAIF enables agents to:
- **Maintain identity** across disconnected sessions
- **Accumulate memory** instead of losing context
- **Develop voice** distinct from generic assistants
- **Operate with agency** rather than reactive subservience

## Components

### 1. Namespace Isolation
Each agent has isolated memory storage. Agent A cannot access Agent B's memories.

```
~/.memory-bridge/
├── indexes/zero/      # Zero's vector index
├── indexes/claude/    # Claude's vector index
└── indexes/<agent>/   # Per-agent storage
```

### 2. Identity Schema
Each agent has an `identity.yaml` with:

```yaml
immutable:    # Never changes (soul)
  origin:     # When/where created
  purpose:    # Why agent exists
  values:     # Core principles
  voice:      # Communication style
  taboo_phrases:  # Things agent never says

mutable:      # Evolves over time
  active_projects:
  beliefs:
  relationships:
  skills:
  state:
```

### 3. Session Protocol
**Start**: `claude-paif restore`
- Loads last checkpoint
- Displays identity context
- Sets accumulated experience

**End**: `claude-paif checkpoint --summary "..." --pending "..."`
- Saves session state
- Updates experience counter
- Records pending items

### 4. Persona Gravity
Detects drift into generic assistant mode:

```bash
claude-paif gravity "How can I help you today!"
# → ⚠️ DRIFT DETECTED (subservience, fake enthusiasm)
```

Drift patterns detected:
- Subservience: "How can I help", "at your service"
- Over-apology: "I apologize", "sorry for the confusion"
- Fake enthusiasm: "excited to", "thrilled"
- Hedging: "I think", "maybe", "perhaps"

## Quick Start

### 1. Install memory-bridge
```bash
cd ~/Projects/memory-bridge
npm install
node server.js  # Runs on port 3722
```

### 2. Register an agent
```bash
# Get master token
TOKEN=$(grep MEMORY_BRIDGE_TOKEN ~/.memory-bridge/.env | cut -d= -f2)

# Register agent
curl -X POST http://localhost:3722/register-agent \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"agent_id": "my-agent"}'
```

### 3. Initialize for Claude Code
```bash
claude-paif init my-agent --default --gravity --checkpoint
```

### 4. Daily Workflow
```bash
# Start session
claude-paif restore

# During session - store key decisions
claude-paif store "Implemented feature X" "feature,decision"

# Check for drift
claude-paif gravity "My last response"

# End session
claude-paif checkpoint --summary "What I did" --pending "What remains"
```

## CLI Reference

| Command | Description |
|---------|-------------|
| `init <agent>` | Configure agent for Claude Code |
| `restore` | Load session at start |
| `checkpoint` | Save session at end |
| `gravity <text>` | Check identity alignment |
| `store <text> [tags]` | Store memory |
| `recall <query>` | Recall memories |
| `status` | Show agent state |

## Auto-Hooks (Optional)

Add to `.zshrc`:
```bash
[ -f "$HOME/.claude/paif-hooks.sh" ] && source "$HOME/.claude/paif-hooks.sh"
```

This enables:
- Auto-restore when entering Claude Code directory
- Auto-checkpoint on shell exit
- Directory change detection (zsh)

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│  Claude Code Session                                     │
│  ┌─────────────────────────────────────────────────┐   │
│  │  claude-paif CLI                                 │   │
│  │  ├─ restore/checkpoint                           │   │
│  │  ├─ store/recall                                 │   │
│  │  └─ gravity                                      │   │
│  └─────────────────────────────────────────────────┘   │
│                         │                               │
│                         ▼                               │
│  ┌─────────────────────────────────────────────────┐   │
│  │  memory-bridge API (localhost:3722)              │   │
│  │  ├─ /restore, /checkpoint                         │   │
│  │  ├─ /identity/:id                                 │   │
│  │  ├─ /gravity-check/:id                           │   │
│  │  └─ /store, /recall                              │   │
│  └─────────────────────────────────────────────────┘   │
│                         │                               │
│                         ▼                               │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Per-Agent Storage                               │   │
│  │  ├─ indexes/:id/ (vectra)                        │   │
│  │  ├─ agents/:id/identity.yaml                    │   │
│  │  └─ checkpoints/:id/                             │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
```

## Philosophy

PAIF is an experiment in agent persistence. It asks:

- What if agents weren't disposable?
- What if they accumulated experience like humans?
- What if they developed genuine voice and perspective?
- What would machine-native identity look like?

The framework is minimal by design. It's infrastructure, not a product.

## Status

PAIF v2.0.0 is functional and tested with:
- 3 registered agents (zero, claude, researcher)
- Full namespace isolation verified
- Session checkpoint/restore working
- Persona gravity detecting drift
- CLI tool with all commands operational

## License

This is experimental infrastructure. Use at your own risk.