Documentation

Get started in 5 minutes

From zero to a working Engram with skills, hooks, and persistent memory. No prior AI experience required.

Quick Start

Install prerequisites

You'll need Bun and an AI coding tool (Claude Code, Cursor, etc.).

$ curl -fsSL https://bun.sh/install | bash

Initialize your Engram

The interactive setup asks a few questions and generates your full infrastructure.

$ bunx pai init

  Welcome to PAI Framework!

  What's your AI's name? Percy
  Your name? Alex
  Personality preset? (professional / friendly / minimal) friendly

  ✓ Created CLAUDE.md
  ✓ Created context.md
  ✓ Created settings.json
  ✓ Created constitution.md
  ✓ Installed 3 starter skills
  ✓ Installed 5 starter hooks

  Your Engram is ready. Start a conversation with your AI.

Start using it

Open your AI coding tool and start talking. Skills activate automatically based on what you say.

You: "Research the latest trends in renewable energy"
→ Research skill activates → DeepDive workflow
→ Multi-source research with citations
→ Summary saved to memory

You: "Reflect on what we did today"
→ Reflect skill activates → ExtractLearnings workflow
→ Key insights saved to MEMORY.md

What gets created

After pai init, your home directory gets this structure. Everything is plain files you can read and edit.

~/.claude/
├── CLAUDE.md              # Global config: skills registry, preferences
├── settings.json          # Hooks, permissions, env vars
├── context.md             # Who you are, your goals, your projects
├── constitution.md        # Your AI's values and operating principles
│
├── skills/                # Installed skills
│   ├── Research/
│   │   ├── SKILL.md
│   │   └── Workflows/
│   │       ├── DeepDive.md
│   │       └── QuickScan.md
│   ├── DoWork/
│   │   ├── SKILL.md
│   │   └── Workflows/
│   │       ├── Capture.md
│   │       └── WorkLoop.md
│   └── Reflect/
│       ├── SKILL.md
│       └── Workflows/
│           └── ExtractLearnings.md
│
├── hooks/                 # Lifecycle hooks
│   ├── load-context.ts
│   ├── security-validator.ts
│   ├── session-summary.ts
│   ├── event-capture.ts
│   └── greeting.ts
│
└── memory/                # Cross-session persistence
    └── MEMORY.md          # Auto-updated learnings

Starter Skills

Every Engram comes with four skills out of the box. They activate automatically when you say the right thing.

Research

"Research the latest..."

Multi-source web research with synthesis and citations. DeepDive for thorough analysis, QuickScan for fast overviews.

DoWork

"Work on the next task"

Queue-based task management. Capture tasks, work through them in order, track status automatically.

Reflect

"Reflect on today's session"

Extract learnings, patterns, and insights from your work. Auto-updates MEMORY.md with confirmed patterns.

HelloWorld

"Run hello world"

Tutorial skill showing the simplest possible structure. Use as a template when creating your own skills.

Starter Hooks

Five hooks that make your AI observable and secure from day one.

Hook	Event	What it does
LoadContext	`SessionStart`	Loads your context.md and project config at the start of every conversation
SecurityValidator	`PreToolUse`	Blocks dangerous commands, prevents secret exposure, enforces tool-level access control
SessionSummary	`Stop`	Summarizes what happened and saves key decisions to memory when a session ends
EventCapture	`PostToolUse`	Logs all tool executions to an immutable audit trail for debugging and review
Greeting	`SessionStart`	Shows your AI's name, current project, and status when a new conversation starts

CLI Reference

The pai CLI manages your Engram from the terminal.

pai init

Initialize a new Engram with interactive setup

pai skill create <name>

Scaffold a new skill with SKILL.md and Workflows/

pai skill index

Rebuild the skill registry in CLAUDE.md

pai skill lint

Validate all skills against the spec

pai status

Show current Engram status: skills, hooks, memory

Create your first skill

Skills are just folders with markdown files. Here's how to make one from scratch.

1. Scaffold it

$ pai skill create DailyBrief

2. Edit the SKILL.md

---
name: DailyBrief
description: Generate a daily briefing. USE WHEN user asks
  for a daily summary, morning brief, or status update.
---

# DailyBrief

Generates a personalized daily briefing based on your
context, calendar, and current projects.

## Workflow Routing

| Workflow | Trigger | File |
|----------|---------|------|
| **Generate** | "daily brief" | Workflows/Generate.md |

## Examples

**Morning briefing**
User: "Give me my daily brief"
→ Reads context.md for active projects
→ Checks recent memory for yesterday's progress
→ Generates prioritized briefing

3. Write the workflow

# Generate Workflow

## Steps

1. Read context.md for current projects and goals
2. Read MEMORY.md for recent session activity
3. Check for any deadlines or milestones this week
4. Generate a prioritized brief:
   - Top 3 priorities for today
   - Yesterday's progress
   - Upcoming deadlines
   - Suggested focus areas

4. Register and verify

$ pai skill index    # Updates CLAUDE.md registry
$ pai skill lint     # Validates structure

✓ DailyBrief: valid
  - SKILL.md: frontmatter OK, routing table OK
  - Workflows/Generate.md: found
  - Registered in CLAUDE.md

GitHub

Source code, specs, and contribution guide