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:

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:

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

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

2. Register an agent

# 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

claude-paif init my-agent --default --gravity --checkpoint

4. Daily Workflow

# 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:

[ -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.