Claude Copilot Architecture
Five-pillar framework: persistent memory, expert agents, on-demand skills, ephemeral task storage, battle-tested workflows.
System Overview
| Layer |
Pillar |
Component |
Purpose |
| Persistence |
1 |
Memory Copilot |
Cross-session context, decisions, lessons |
| Expertise |
2 |
14 Lean Agents |
Minimal agents (under 120 lines) with on-demand skills |
| Knowledge |
3 |
Skills Copilot |
Auto-detected skill loading via skill_evaluate |
| Tasks |
4 |
Task Copilot |
Ephemeral PRD, task, work product storage |
| Workflow |
5 |
Protocol |
/protocol and /continue commands |
Data Flow
User Request → Protocol → Lean Agent → skill_evaluate() → Load Skills → Execute → Store Work Product → Memory Update
Lean Agent Pattern:
- Agent files are under 120 lines (workflow, routing, core behaviors)
- Shared boilerplate extracted to "Agent Shared Behaviors" in CLAUDE.md
- Domain expertise lives in skill files (200-500 lines each)
skill_evaluate() matches skills based on file patterns and keywords- Skills loaded on-demand via
@include directive
- ~70% token reduction vs. monolithic agents
Core Workflows
| Command |
Flow |
Result |
/protocol |
Classify request → Route to agent → Understand → Present findings → Get approval → Execute → Save to memory |
Fresh work with agent-first approach |
/continue |
Load initiative → Present context → Resume work |
Continue with full history |
Agent Routing
Understanding Phase
| Request Type |
First Agent |
Routes To |
Finally |
| Bug/Defect |
qa |
me (fix) |
qa (verify) |
| Experience |
sd + uxd |
uids |
uid |
| Technical |
ta |
sec (if security) |
me |
| Architecture |
ta |
sec + do |
me |
Cross-Cutting Concerns
| Concern |
Routes To |
| Security implications |
sec |
| Documentation needed |
doc |
| Testing required |
qa |
| Deployment concerns |
do |
Storage
Memory Copilot (SQLite per project)
| Table |
Key Fields |
| initiatives |
title, status, completed[], inProgress[], decisions[], lessons[], keyFiles[], resumeInstructions |
| memories |
type, content, tags[], embedding (semantic search) |
| sessions |
initiative_id, started_at, summary |
Location: ~/.claude/memory/{workspace-id}/memory.db
Skills Copilot (Priority Order)
| Source |
Location |
Purpose |
| Local |
./.claude/skills/ |
Project-specific |
| Cache |
SQLite (7-day TTL) |
Fast repeat access |
| Private DB |
PostgreSQL |
Organization skills |
| SkillsMP |
API |
25,000+ public skills |
Extension System
| Behavior |
Effect |
override |
Replaces base agent |
extension |
Adds to base agent |
skills |
Injects additional skills |
Detected via knowledge-manifest.json in project or docs/shared/.
Performance
| Component |
Strategy |
Token Savings |
| Memory |
Semantic search, relevant context only |
~80% |
| Skills |
Auto-detected on-demand loading |
~95% |
| Lean Agents |
Minimal definitions + shared behaviors + external skills |
~70% |
| Protocol |
Two simple commands |
~90% |
| Task Copilot |
Work products stored externally |
~96% |
Security
| Concern |
Approach |
| Data isolation |
Per-project SQLite databases |
| Secrets |
Never stored in memory/skills |
| Trust levels |
Local > Private DB > Cache > API |
| Enforcement |
sec agent reviews security concerns |
Failure Modes
| Component Fails |
Behavior |
Impact |
| Memory Copilot |
New initiative, no history |
Loss of context |
| Skills (all sources) |
Agents work without skills |
Less optimal |
| Skills (one source) |
Falls back to next priority |
Transparent |
| Specific Agent |
Routes to alternative |
Less specialized |
System Boundaries
| Included |
External |
| Memory persistence |
Claude Code CLI |
| 14 lean agents with skill_evaluate |
MCP SDK |
| Skills loading (auto-detection) |
Git, project files |
| Task storage |
SkillsMP API, PostgreSQL |
| Protocol commands |
|
1---2name: claude-copilot-architecture3description: Five-pillar framework: persistent memory, expert agents, on-demand skills, ephemeral task storage, battle-tested workflows.4---5# Claude Copilot Architecture67Five-pillar framework: persistent memory, expert agents, on-demand skills, ephemeral task storage, battle-tested workflows.89---1011## System Overview1213| Layer | Pillar | Component | Purpose |14|-------|--------|-----------|---------|15| Persistence | 1 | Memory Copilot | Cross-session context, decisions, lessons |16| Expertise | 2 | 14 Lean Agents | Minimal agents (under 120 lines) with on-demand skills |17| Knowledge | 3 | Skills Copilot | Auto-detected skill loading via skill_evaluate |18| Tasks | 4 | Task Copilot | Ephemeral PRD, task, work product storage |19| Workflow | 5 | Protocol | /protocol and /continue commands |2021### Data Flow2223```24User Request → Protocol → Lean Agent → skill_evaluate() → Load Skills → Execute → Store Work Product → Memory Update25```2627**Lean Agent Pattern:**28- Agent files are under 120 lines (workflow, routing, core behaviors)29- Shared boilerplate extracted to "Agent Shared Behaviors" in CLAUDE.md30- Domain expertise lives in skill files (200-500 lines each)31- `skill_evaluate()` matches skills based on file patterns and keywords32- Skills loaded on-demand via `@include` directive33- ~70% token reduction vs. monolithic agents3435---3637## Core Workflows3839| Command | Flow | Result |40|---------|------|--------|41| `/protocol` | Classify request → Route to agent → Understand → Present findings → Get approval → Execute → Save to memory | Fresh work with agent-first approach |42| `/continue` | Load initiative → Present context → Resume work | Continue with full history |4344---4546## Agent Routing4748### Understanding Phase4950| Request Type | First Agent | Routes To | Finally |51|--------------|-------------|-----------|---------|52| Bug/Defect | qa | me (fix) | qa (verify) |53| Experience | sd + uxd | uids | uid |54| Technical | ta | sec (if security) | me |55| Architecture | ta | sec + do | me |5657### Cross-Cutting Concerns5859| Concern | Routes To |60|---------|-----------|61| Security implications | sec |62| Documentation needed | doc |63| Testing required | qa |64| Deployment concerns | do |6566---6768## Storage6970### Memory Copilot (SQLite per project)7172| Table | Key Fields |73|-------|------------|74| initiatives | title, status, completed[], inProgress[], decisions[], lessons[], keyFiles[], resumeInstructions |75| memories | type, content, tags[], embedding (semantic search) |76| sessions | initiative_id, started_at, summary |7778Location: `~/.claude/memory/{workspace-id}/memory.db`7980### Skills Copilot (Priority Order)8182| Source | Location | Purpose |83|--------|----------|---------|84| Local | `./.claude/skills/` | Project-specific |85| Cache | SQLite (7-day TTL) | Fast repeat access |86| Private DB | PostgreSQL | Organization skills |87| SkillsMP | API | 25,000+ public skills |8889---9091## Extension System9293| Behavior | Effect |94|----------|--------|95| `override` | Replaces base agent |96| `extension` | Adds to base agent |97| `skills` | Injects additional skills |9899Detected via `knowledge-manifest.json` in project or `docs/shared/`.100101---102103## Performance104105| Component | Strategy | Token Savings |106|-----------|----------|---------------|107| Memory | Semantic search, relevant context only | ~80% |108| Skills | Auto-detected on-demand loading | ~95% |109| Lean Agents | Minimal definitions + shared behaviors + external skills | ~70% |110| Protocol | Two simple commands | ~90% |111| Task Copilot | Work products stored externally | ~96% |112113---114115## Security116117| Concern | Approach |118|---------|----------|119| Data isolation | Per-project SQLite databases |120| Secrets | Never stored in memory/skills |121| Trust levels | Local > Private DB > Cache > API |122| Enforcement | sec agent reviews security concerns |123124---125126## Failure Modes127128| Component Fails | Behavior | Impact |129|-----------------|----------|--------|130| Memory Copilot | New initiative, no history | Loss of context |131| Skills (all sources) | Agents work without skills | Less optimal |132| Skills (one source) | Falls back to next priority | Transparent |133| Specific Agent | Routes to alternative | Less specialized |134135---136137## System Boundaries138139| Included | External |140|----------|----------|141| Memory persistence | Claude Code CLI |142| 14 lean agents with skill_evaluate | MCP SDK |143| Skills loading (auto-detection) | Git, project files |144| Task storage | SkillsMP API, PostgreSQL |145| Protocol commands | |
tools-only