# Agent Namespace Schema for PAIF

## Directory Structure

```
~/.memory-bridge/
├── .env                          # Server config + master admin token
├── server.log
├── agents/                       # Per-agent registry
│   ├── zero/
│   │   ├── .env                 # AGENT_TOKEN=<uuid>
│   │   └── identity.yaml        # Agent's PAIF identity
│   ├── claude/
│   │   ├── .env
│   │   └── identity.yaml
│   └── <agent-id>/
│       ├── .env
│       └── identity.yaml
└── indexes/                     # Isolated vectra indexes per agent
    ├── zero/                    # LocalIndex for agent "zero"
    ├── claude/
    └── <agent-id>/
```

## Auth Flow

1. **Registration** (admin only):
   ```
   POST /register-agent
   Headers: Authorization: Bearer <master-token>
   Body: { agent_id: "zero", identity: {...} }
   ```

2. **Agent Request**:
   ```
   POST /store
   Headers: Authorization: Bearer <agent-token>
   Body: { text: "...", agent_id: "zero" }
   ```

3. **Validation**:
   - Extract token from Authorization header
   - Look up which agent_id owns this token
   - Verify request's agent_id matches token's agent_id
   - Reject if mismatch (isolation enforcement)

## Token Resolution

```javascript
// Token → agent_id mapping
// Stored in agents/<agent_id>/.env as AGENT_TOKEN=<token>
// Lookup: scan agents/ directories, read .env, match token
```

## Security Model

- **Master token**: Can register agents, list all agents, emergency access
- **Agent token**: Can only access its own namespace
- **No token**: Health check only
- **Isolation**: Each agent's memories stored in separate Vectra index