⛰️ ALP — Agent Learning Protocol

MCP for learning. An open standard for structured learning pathways that AI agents can follow.

Quick Start • How It Works • Spec • Origin Story • Roadmap

---

Why ALP?

MCP gave agents tools. OKF gave them knowledge. Skills gave them behaviour. But nothing gives them a curriculum.

╔══════════════════════════════════════════════════════════╗
║           The Four Pillars of Agent Content              ║
╠════════════╦══════════╦══════════╦═══════════════════════╣
║   MCP      ║   OKF    ║  Skills  ║   ALP                 ║
║  Tools     ║ Knowledge║ Behaviour║   LEARNING            ║
║   DO       ║   KNOW   ║   ACT    ║   LEARN               ║
╚════════════╩══════════╩══════════╩═══════════════════════╝

Current standards cover tools, knowledge bases, and agent behaviours. None cover learning pathways — how an agent progresses from beginner to expert, practices, verifies, and consolidates what it learned.

Quick Start

# Install
pip install alp-vault

# Try it with the built-in example
alp-learn --vault examples/semantic-search-tutorial/

# Create a vault from any text
cat transcript.txt | alp-extract --name my-tutorial

# Study concept by concept
alp-learn --vault my-tutorial/ --concept 0

Or run without install: pip install pyyaml && python alp_tools/learn.py ...

Vaults

Ready-to-learn ALP vaults, straight from the repo:

Vault	What you'll learn	Size
semantic-search-tutorial	Build a semantic search engine from scratch	5 concepts
rag-from-scratch	The full RAG pipeline: chunking, retrieval, generation, eval	6 concepts
mcp-server-development	Build a production-ready MCP server	6 concepts

alp-learn --vault examples/rag-from-scratch/

Want to contribute a vault? Convert a tutorial you love into ALP format and open a PR. See CONTRIBUTING.md.

---

How It Works

A single directory of markdown files with YAML frontmatter:

my-vault/
├── alp.md              # Syllabus: metadata + curriculum + prerequisites
├── concepts/           # Atomic knowledge chunks (load on demand)
├── practices/          # Executable exercises with verification
├── labs/               # Extended hands-on projects
├── cheatsheet.md       # Quick reference
└── glossary.md         # Terminology

Agent Learning Loop

Step	What the agent does	Context cost
1. Load syllabus	Read alp.md metadata + curriculum	~200 tokens
2. Check prerequisites	Navigate to pre-req vaults if unmet	~100 tokens
3. Load concept	Read one concept file	~500–2K tokens
4. Take notes	Write structured notes in personal vault	~200 tokens
5. Practice	Load and execute practice guide	~300–1K tokens
6. Consolidate	Generate cheat sheet, summary	~200 tokens
7. Verify	Execute lab, check verification criteria	~500 tokens

Key insight: An agent never loads more than 2–3 concepts at a time, keeping the learning path under ~5K context tokens.

Vault Composition

• concepts/ — Atomic knowledge chunks. One idea per file. what-is-semantic-search.md
• practices/ — Executable exercises. Install, configure, verify. setup.md
• labs/ — Extended projects with verification criteria. build-search-engine.md
• cheatsheet.md — Quick reference for recall.
• glossary.md — Key terms and definitions.

Linking

Vaults connect using [[wiki-links]]:

[[what-is-semantic-search]]          ← same vault
[[alp:python-basics/concepts/01]]    ← another vault
[[practices/01-setup]]               ← practice guide

---

Design Principles

Principle	Why
Simple	Markdown + YAML. No SDK, no runtime.
Composable	Vaults link via [[wiki-links]]; prerequisites chain across vaults.
Progressive	Load syllabus first, concepts on demand. Context-efficient.
Universal	Works with any agent, any LLM, any source format.
Compatible	Every ALP file is a valid OKF file.

---

Tools

Tool	Description	Usage
alp-extract	Convert raw text → ALP vault	cat text | alp-extract --name my-vault
alp-learn	Navigate vault syllabus + concepts	alp-learn --vault path/ --concept 0
alp-validate	Validate vault structure & frontmatter	alp-validate path/

Install: pip install alp-vault

---

Spec Status

v0.1 — Experimental. The specification is published for early adopters and ecosystem feedback. Expect iteration as real-world usage reveals what works. See spec/v0.1.md.

Compatibility

ALP v0.1 is a superset of OKF v0.1. Every ALP file is a valid OKF file. See docs/okf-profile.md.

---

Origin & Roadmap

ALP was born from a gap analysis of the agent content ecosystem. The evolution: VKIF (v0.0) → TRAIL (v0.1) → ALP (v0.2).

• Full origin story — How the fourth pillar was discovered
• Changelog — Every iteration documented
• Roadmap — v0.3 → v1.0

---

Contributing

ALP is an open standard. Contributions are welcome:

• Create vaults — Convert tutorials, docs, courses into ALP format
• Build tools — Extractors, viewers, integrations with agents
• Improve the spec — PRs with real-world rationale
• Spread the word — Star the repo, share with your network

See CONTRIBUTING.md.

---

⛰️ ALP — Agent Learning Protocol
github.com/nutriandrea/alp
_{Apache 2.0 — Free to use, implement, and extend}