Protext: Dynamic Context Management

Protext provides a three-layer context hierarchy for token-efficient AI agent orientation.

Core Concept

PROTEXT.md (Layer 0)  →  .protext/index.yaml (Layer 1)  →  Deep Context (Layer 2)
     ~500 tokens              Signposts only                 Full docs/memory
     Always loaded            On-demand hints                Explicit extraction

Separation of Concerns:

• Behavior file = Agent behavior (how to act) — stable, rarely changes

  • CLAUDE.md

    (Claude Code) ·

    GEMINI.md

    (Gemini CLI) ·

    AGENTS.md

    (Codex/OpenCode)

• PROTEXT.md

  = Project state (what's happening) — dynamic, session-aware

File Structure

project-root/
├── PROTEXT.md                  # Layer 0: Orientation (~500 tokens)
├── CLAUDE.md / GEMINI.md / AGENTS.md   # Existing: Behavior instructions (platform-specific)
└── .protext/
    ├── index.yaml              # Layer 1: Extraction signposts
    ├── handoff.md              # Session continuity
    ├── scopes/
    │   ├── ops.md              # Operations context
    │   ├── dev.md              # Development context
    │   └── security.md         # Security context
    └── config.yaml             # Protext settings

PROTEXT.md Format

# Protext: [Project Name]
> Generated: YYYY-MM-DD | Scope: [active-scope] | Tokens: ~XXX

## Identity
[1-2 sentences: What is this project/system?]

## Current State
Active: [current work] | Blocked: [blockers] | Recent: [last completed]

## Hot Context
- [Critical point 1]
- [Critical point 2]
- [Critical point 3]

## Scope Signals
- `@ops` → .protext/scopes/ops.md
- `@security` → .protext/scopes/security.md
- `@deep:[name]` → Extract from index

## Links
- `[path]` → [rel-type] | [note]

## Handoff
Last: [summary] | Next: [suggested] | Caution: [warnings]

Commands

/protext

(Primary - Session Start)

Load project orientation. This is the main entry point - invoke at session start.

/protext              # Load PROTEXT.md + active scope + handoff status
/protext @security    # Load with security scope
/protext --full       # Include available extractions list

What it does:

1. Reads and displays PROTEXT.md (orientation layer)
2. Shows handoff status (FRESH/AGING/STALE)
3. Loads active scope context
4. Lists available deep extractions (with

   --full

   )

Cross-platform: Works as slash command on Claude Code, or natural language on other platforms:

• "Load protext"
• "Show me the project context"
• "What's the current state?"

If no PROTEXT.md exists: Inform the user and offer to run

protext init

to bootstrap one. Do not fail silently.

---

protext init

Initialize protext in a project. Reads existing CLAUDE.md to bootstrap.

# Standard mode
"Initialize protext for this project"
"Set up protext here"

# Parent mode (aggregates children)
"protext init --parent"

Creates: PROTEXT.md, .protext/ directory with full structure.

Parent mode: Scans for child

.protext/

directories, aggregates their status into

## Child Projects

section. One-level hierarchy only.

protext status

Display current protext state.

"Show protext status"
"What's the current context state?"

Shows: Tier, active scope, handoff age, token budget, available extractions.

protext scope [name]

Switch active scope context.

"Switch to ops scope"
"Focus on security context"
"@security"  # Shorthand

protext handoff

Capture or display session handoff. User-initiated only — no auto-capture, no TTL enforcement.

"Capture handoff: stopped mid-refactor, next step is testing"
"What was the last handoff?"

Handoff is an optional scratchpad. Only created when user explicitly captures.

protext extract [name]

Pull deep context from index.

"Extract network context"
"@deep:services"  # Shorthand

Agent receives extraction suggestion; confirm to load.

protext link [path]

Add a cross-project link. Guided flow — agent asks for relationship type and note.

"Link this project to ../skills-validator"
"protext link ../homelab"
"What projects are linked?"

Relationship types with spatial validation:

• child

  — Subdirectory (./name) — aggregates status

• parent

  — Ancestor (../) — no aggregation

• sibling

  — Adjacent (../name) — no aggregation

• peer

  — Any path (relative preferred) — no aggregation

Path preference: Use relative paths (

../sibling

,

./child

) wherever possible — they are portable across nodes and OS mount points. Absolute paths may break on machines with different prefixes (e.g.,

/mnt/ops

on Linux vs

/Volumes/ops

on macOS).

Validates path patterns with regex enforcement (ERROR if spatial rules violated). Max 5 lateral links. See Spatial Validation Rules in

references/commands.md

for pattern specs, validation flow, and edge cases.

protext refresh --children

Re-aggregate child status in parent protext. User-initiated only — no auto-refresh.

"protext refresh --children"
"Update children status"

Scans child

.protext/

directories, extracts status from markers (or headings fallback), updates parent

## Child Projects

section.

Parent Protext

Meta-projects that aggregate multiple child protexts. Created with

protext init --parent

.

Key features:

• ## Child Projects

  section lists all children with status (active/idle/stale)
• Child status based on PROTEXT.md modification time (< 7 days = active)
• No extraction index (children have their own)

• protext refresh --children

  re-aggregates (explicit user command only)
• One-level hierarchy: parent → children only

Marker extraction: Parent uses

<!-- marker:identity -->

,

<!-- marker:state -->

from children. Falls back to heading-based parsing if markers absent (backward compatible).

Zero auto-execution: Parent never auto-refreshes on load. Always explicit.

Extraction Modes

Configure in

.protext/config.yaml

:

extraction_mode: suggest  # suggest | auto | confirm
token_budget: 2000        # Max extraction tokens per session

• suggest (default): Agent sees "context available: X" but doesn't auto-load
• auto: Keyword triggers load (opt-in, risky for token budget)
• confirm: Agent proposes extraction, user must approve

Index Schema

.protext/index.yaml

:

extractions:
  network:
    source: docs/NETWORK.md
    triggers: [dns, ip, tailscale, mesh, routing]
    summary: "IPs, DNS config, mesh nodes"
    tokens: ~600

  services:
    source: docs/SERVICES.md
    triggers: [docker, container, service, port]
    summary: "Docker services, ports, domains"
    tokens: ~800

  secrets:
    source: docs/SECRETS.md
    triggers: [secret, credential, infisical, auth]
    summary: "Secrets management, auth patterns"
    tokens: ~400

Limits: Max 20 extractions per project.

Scopes

Scopes provide domain-specific orientation. Max 5 per project.

Default scopes:

• ops

  — Infrastructure, deployment, monitoring

• dev

  — Development workflow, code patterns

• security

  — Auth, secrets, vulnerabilities

• project

  — Project-specific context (custom)

Scope file format (

.protext/scopes/ops.md

):

# Scope: Operations

## Focus
Infrastructure management, service health, deployment.

## Key Resources
- [Service config paths]
- [Key infrastructure locations]

## Current Priorities
1. [Priority 1]
2. [Priority 2]

## Cautions
- [Ops-specific warnings]

Handoff Protocol

User-initiated only — handoff is an optional scratchpad for session continuity.

.protext/handoff.md

format:

# Session Handoff
> Updated: YYYY-MM-DDTHH:MM

## Last Session
**Completed:**
- [Task 1]
- [Task 2]

**In Progress:**
- [Task] (stopped at: [point])

**Deferred:**
- [Task] (blocked by: [reason])

## Cautions
- [Warning 1]
- [Warning 2]

## Agent Notes
[Observations that might help next session]

Behavior:

• No auto-capture at session end
• No TTL warnings based on age
• Created only when user runs

  protext handoff capture

• Agents do not automatically update handoff

Progressive Tiers

Beginner

• PROTEXT.md only
• No scopes, extractions, or handoff
• Direct editing

Intermediate

• PROTEXT.md + handoff.md
• Session continuity
• No extraction index

Advanced (Default)

• Full feature set
• Scopes, extractions, token budgets
• Config-driven behavior

Constraints

Limit	Value	Rationale
Max scopes	5	Prevent fragmentation
Max lateral links	5	Keep peer/sibling/reference list concise
Max child links	Unlimited	Structure dictates count
Max extractions	20	Index stays scannable
Token budget	2000	Default per-session limit
Handoff TTL	48h	Legacy, no longer enforced
PROTEXT.md size	~500 tokens	Quick orientation
Hierarchy depth	1 level	Parent → children only

Integration Patterns

With Behavior Files

The platform behavior file (

CLAUDE.md

,

GEMINI.md

,

AGENTS.md

) provides behavioral instructions (stable):

# CLAUDE.md  (or GEMINI.md / AGENTS.md)
## How to Work
- Validate Caddy config before reloading
- Never hardcode secrets

PROTEXT.md provides state orientation (dynamic):

# PROTEXT.md
## Current State
Active: Caddy refactor | Recent: Pi-hole v6 migration

With Memory Systems

Protext complements but doesn't replace:

• memory/ — Long-term learnings, patterns
• PROTEXT.md — Current session orientation

Scripts

Requires Python 3.8+. No external packages needed (yaml parsed with fallback).

• scripts/init_protext.py

  — Bootstrap protext in a project

• scripts/protext_status.py

  — Display current state

Reference Files

Consult these only when deeper detail is needed:

• references/formats.md

  — Read when creating or editing PROTEXT.md, index.yaml, handoff.md, or scope files. Contains complete templates and field guidelines.

• references/commands.md

  — Read when implementing command handling or troubleshooting. Contains full syntax, flags, error messages, and natural language alternatives.