Unified Context Protocol

1. The Problem

Most AI coding assistants operate without memory. They cannot recall that a team preferssnake_case, that the auth module has known race conditions, or that a migration failed three times yesterday. This context exists somewhere—trapped in proprietary systems or scattered across ephemeral chat logs—but it remains inaccessible where it matters: at the point of execution.

When context is siloed, teams rebuild understanding from scratch. Each session starts cold. Knowledge earned through debugging is lost. Patterns discovered by one agent are invisible to the next.

UCP addresses this by externalizing agent memory to the filesystem. The approach is deliberately simple:

• Plain Markdown files serve as the storage layer. No vector database required.
• Local-first architecture keeps context in the repository, versioned alongside code.
• Agent-agnostic design enables interoperability across Cursor, Windsurf, Claude Code, Copilot, JetBrains AI, Aider, and generic LLM interfaces.

2. Architecture

The protocol separates concerns into two domains: an immutable engine containing workflows and rules, and a mutable memory containing project-specific state. This separation allows the protocol itself to evolve without disturbing accumulated knowledge.

Update Semantics

• ENGINE — Files in bin/ are protocol-owned. Updates replace them entirely, ensuring bug fixes and workflow improvements propagate cleanly.
• MEMORY — Files in context/ andknowledge/ belong to the project. Updates append new sections without overwriting existing data.

3. Memory Model

The protocol defines three memory types, each serving a distinct function in agent cognition:

This taxonomy mirrors how teams naturally organize knowledge. Static memory answers "what is this project?" Kinetic memory tracks "what is happening now?" Procedural memory encodes "how do we do things here?"

4. Session Lifecycle

Agent sessions follow a deterministic flow defined in bin/workflows/boot.md. The sequence ensures consistent initialization regardless of which agent or interface is used.

Boot Sequence

// Initialization
LOAD "context/PRIORITY.md"
LOAD "context/MASTER.md"

IF exists("context/active/*.md"):
  RESUME from_checkpoint
ELSE:
  AWAIT instruction

// Task-conditional loading
MATCH task_type:
  CASE "coding": LOAD "tech.md", "patterns.md"
  CASE "debugging": LOAD "gotchas.md", "learnings.md"

// Session end
UPDATE "changelog.md"
IF complete: RUN "learning.md"
ELSE: RUN "handoff.md"

5. Context Budget

LLMs operate under token constraints. Loading every file exhausts the context window before useful work begins. The protocol addresses this through tiered priority loading:

This tiering keeps essential context always available while deferring specialized knowledge until needed. Most implementations find P0+P1 sufficient for routine tasks.

6. Knowledge Accumulation

Beyond session state, the protocol provides persistent storage for organizational knowledge. Files inknowledge/ accumulate insights over time:

• learnings.md — Empirical observations: what worked, what failed, and why
• patterns.md — Recurring implementation patterns with context and examples
• gotchas.md — Known failure modes and avoidance strategies
• decisions.md — Architectural decisions with rationale (ADR format)

Capture Logic

At session end, bin/workflows/learning.md extracts insights from the interaction history:

FOREACH interaction:
  IF contains_correction:
    APPEND to "learnings.md" (What Failed)
  IF contains_preference:
    UPDATE "user-prefs.md"
  IF contains_decision:
    APPEND to "decisions.md"