paif/AGENT_SCHEMA.md

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

// 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