Agent Skills: Context Compression — Level 2 (Intelligent Compression)

Context Compression — Level 2 (Intelligent Compression)

Level 2 replaces Level 1 with priority-aware compression: scoring, semantic summarization for critical/high entries, downstream-aware field masks, budget allocation, and automatic cross-references. Zeus triggers, Mnemosyne executes.

1. Overview

Level 2 adds four capabilities beyond Level 1:

1. Priority Scoring Engine — Deterministic keyword-driven scoring (no LLM) for each subtask_summary across 5 dimensions. Outputs CRITICAL/HIGH/MEDIUM/LOW.
2. Semantic Summarization — Template-generated contextual summaries for CRITICAL/HIGH entries, tailored to the downstream agent pair. MEDIUM/LOW get standard mechanical 1-line compression.
3. Downstream-Aware Compression — Field masks preserve the most relevant fields per (from_agent, to_agent) pair. Themis gets all fields; Mnemosyne gets minimal.
4. Cross-Reference Mechanism — Auto-generated _xref/index.md with entity references for endpoints, tables, migrations, components, and decisions, surviving sprint boundaries.

Budget allocation is priority-greedy. CRITICAL entries are always expanded. Overflow escalates to Zeus.

2. Compression Triggers

Same 7 triggers as Level 1, with Level 2 behavior:

| Trigger | Fires | Level 2 Behavior | |---------|-------|------------------| | C1 Phase Gate | Themis APPROVED | Priority-score subtask_summary → semantic summary (CRITICAL/HIGH) or 1-line (MEDIUM/LOW) → 01-active-context.md | | C2 Phase Gate | Themis APPROVED | IMPL artifact → scored, archived to 02-progress-log.md; .tmp/ deleted | | C3 Phase Gate | Themis APPROVED | REVIEW summary line → 02-progress-log.md; .tmp/ deleted | | C4 Feature Complete | Last phase APPROVED | PLAN reference → 01-active-context.md; .tmp/ deleted | | C5 Sprint Close | @mnemosyne Close sprint | Bulk cleanup + cross-ref archive + flag unresolved | | C6 Explicit | /compress | Per-type compression with priority scoring | | C7 Size-based | 01-active-context.md Completed Phases > 100 lines | Priority-greedy trim: oldest LOW entries first, preserving CRITICAL and HIGH |

Inline Compression Triggers (C8-C11 — Active Session)

These triggers fire DURING an active agent session. They call the Pantheon-native inline compressor (compress-inline.py MCP, "L1"). Scrubbing is automatic in the MCP layer — agents must NOT scrub manually.

| Trigger | Fires | Layer | Action | |---------|-------|-------|--------| | C8 CRITICAL/HIGH subtask_summary | A returned subtask_summary contains CRITICAL/HIGH findings | L1 Inline | execute_code_script("compress-inline.py", args=["compress", "--text", "<content>"]) before the next phase | | C9 Pre-Delegation | About to delegate a large context block to another agent | L1 Inline | Compress the block first to cut tokens | | C10 Context Pressure | Context near limit / platform compaction signal | — (cross-ref) | OpenCode native compaction already handles this. No separate Pantheon mechanism — see §12. | | C11 Phase Boundary / Handoff | Phase boundary or session handoff reached | L1 Inline | Compress completed work before promotion |

3. Priority Scoring Engine

The algorithm is DETERMINISTIC (keyword-driven, no LLM needed). Zeus scores each subtask_summary before compression using 5 dimensions. Total score is weighted sum.

Scoring Dimensions

| Dimension | Weight | Range | Description | |-----------|--------|-------|-------------| | Impact | 0.30 | 0.0–1.0 | How broadly the change affects the system | | Risk | 0.25 | 0.0–1.0 | Likelihood of breakage or subtle bugs | | Novelty | 0.20 | 0.0–1.0 | New pattern, architecture, or files | | Blockers | 0.15 | 0.0–1.0 | Whether this unblocked others or was blocked | | Downstream relevance | 0.10 | 0.0–1.0 | How relevant to the next agent (from agent-pair table) |

Full Keyword Scoring Map

| Keyword / Pattern | Impact | Risk | Novelty | Category | |-------------------|--------|------|---------|----------| | schema | 1.0 | 1.0 | 0.6 | schema/migration | | migration | 1.0 | 1.0 | 0.4 | schema/migration | | auth | 1.0 | 1.0 | 0.5 | auth/security | | login | 1.0 | 1.0 | 0.4 | auth/security | | permission | 0.8 | 1.0 | 0.5 | auth/security | | role | 0.8 | 0.8 | 0.4 | auth/security | | JWT | 0.8 | 1.0 | 0.4 | auth/security | | OAuth | 0.8 | 1.0 | 0.5 | auth/security | | password | 0.7 | 1.0 | 0.3 | auth/security | | encrypt | 0.7 | 1.0 | 0.5 | auth/security | | token | 0.7 | 0.8 | 0.3 | auth/security | | security | 0.8 | 1.0 | 0.4 | auth/security | | new table | 1.0 | 0.8 | 0.9 | schema/migration | | new column | 0.7 | 0.8 | 0.6 | schema/migration | | index | 0.5 | 0.6 | 0.3 | database | | foreign key | 0.8 | 0.9 | 0.5 | database | | constraint | 0.6 | 0.7 | 0.3 | database | | endpoint | 0.9 | 0.6 | 0.5 | api | | route | 0.8 | 0.5 | 0.4 | api | | API | 0.8 | 0.5 | 0.4 | api | | service | 0.7 | 0.4 | 0.4 | architecture | | new file | 0.6 | 0.3 | 0.8 | structure | | refactor | 0.5 | 0.7 | 0.6 | code-quality | | rename | 0.4 | 0.6 | 0.3 | code-quality | | delete | 0.5 | 0.7 | 0.2 | code-quality | | deprecat | 0.4 | 0.4 | 0.3 | code-quality | | config | 0.5 | 0.6 | 0.3 | infrastructure | | Docker | 0.7 | 0.6 | 0.3 | infrastructure | | deploy | 0.8 | 0.8 | 0.2 | infrastructure | | CSS | 0.2 | 0.1 | 0.2 | style | | style | 0.2 | 0.1 | 0.2 | style | | typo | 0.0 | 0.0 | 0.0 | trivial | | comment | 0.1 | 0.0 | 0.0 | trivial | | README | 0.2 | 0.0 | 0.1 | documentation | | docstring | 0.2 | 0.0 | 0.1 | documentation | | 5+ files | — | — | 0.8 | novelty (file count) | | 10+ files | — | — | 1.0 | novelty (file count) |

Scoring rules:

• For each dimension, find the maximum matching keyword score among all keywords found in the summary.
• If multiple keywords match in the same category, take the max per dimension.
• Novelty bonus: files_changed overrides keyword score — if >5 files, set novelty to 0.8; if >10 files, set to 1.0.
• If no keywords match, default to 0.0 for that dimension.

Downstream Relevance Table

The relevance score is computed from the agent-pair lookup:

| From ↓ → To → | Hermes | Aphrodite | Demeter | Themis | Mnemosyne | Hephaestus | Prometheus | |---------------|--------|-----------|---------|-------|-----------|------------|------------| | Hermes | 1.0 | 0.9 | 0.8 | 0.7 | 0.3 | 0.6 | 0.5 | | Aphrodite | 0.9 | 1.0 | 0.3 | 0.7 | 0.3 | 0.5 | 0.3 | | Demeter | 0.9 | 0.3 | 1.0 | 0.7 | 0.3 | 0.6 | 0.6 | | Themis | 0.8 | 0.8 | 0.8 | 1.0 | 0.5 | 0.8 | 0.8 | | Hephaestus | 0.6 | 0.5 | 0.6 | 0.7 | 0.3 | 1.0 | 0.4 | | Prometheus | 0.6 | 0.4 | 0.6 | 0.7 | 0.3 | 0.4 | 1.0 | | Mnemosyne | 0.3 | 0.3 | 0.3 | 0.5 | 1.0 | 0.3 | 0.3 |

Rows = from agent, Columns = to agent. Score = table[from_agent][to_agent] scaled to 0.0–1.0 (already in range).

When the next-phase agent is unknown, default downstream relevance to 0.5.

Priority Bands

| Band | Score Range | Storage Mode | |------|-------------|--------------| | CRITICAL | ≥ 0.75 | Expanded (3 lines, semantic summary) | | HIGH | 0.50 – 0.74 | Expanded (2 lines) or Standard (1 line) per budget | | MEDIUM | 0.25 – 0.49 | Standard (1 line) | | LOW | < 0.25 | Aggressive (0.5 lines, filename only) |

Scoring Example

subtask_summary:
  summary: "Added JWT auth endpoint with refresh token rotation"
  files_changed: ["backend/routers/auth.py", "backend/services/auth_service.py"]
  status: complete

Keywords found: JWT (auth/security), endpoint (api), token (auth/security)
  → Impact = max(0.8, 0.9, 0.7) = 0.9
  → Risk = max(1.0, 0.6, 0.8) = 1.0
  → Novelty = max(0.4, 0.5, 0.3) = 0.5 | files=2, no bonus
  → Blockers = 0.0 (no blockers mentioned)
  → Downstream = 0.9 (Hermes→Aphrodite)

Score = 0.9×0.30 + 1.0×0.25 + 0.5×0.20 + 0.0×0.15 + 0.9×0.10
     = 0.27 + 0.25 + 0.10 + 0.00 + 0.09
     = 0.71 → HIGH

4. Semantic Summarization

Zeus generates contextual summaries for CRITICAL and HIGH entries using the semantic-summarize prompt template. Each summary costs ~50 input tokens per entry (uses the same model as Zeus). MEDIUM/LOW entries get mechanical 1-line compression without summarization.

Template: CRITICAL (3 lines)

1 sentence: What changed (include API/contract details if relevant to next agent)
1 sentence: Why it matters to the NEXT agent (from downstream table)
1 sentence: Gotcha/decision/trade-off

Template: HIGH (2 lines)

1 sentence: What changed (include API/contract details if relevant to next agent)
1 sentence: Why it matters to the NEXT agent (from downstream table)

Template: MEDIUM (1 line)

[agent] — <summary first sentence, ≤80 chars> — <files>

Template: LOW (filename only)

[agent] — <files>

Variants Per Agent Pair

| Agent Pair | What to Include | |------------|-----------------| | Hermes → Aphrodite | Endpoint path, request/response shape, status codes | | Hermes → Demeter | Model/table names, relationships, foreign keys | | Demeter → Hermes | Table/column names, migration version, data types | | Demeter → Aphrodite | New fields added, field types, defaults | | Aphrodite → Hermes | Component name, data requirements, event handlers | | Aphrodite → Demeter | UI state shape, fields displayed | | Themis → * | Verdict, critical issues count, coverage delta | | * → Themis | Preserve ALL fields (full context for review) | | * → Mnemosyne | Summary, status only (archive: minimal) | | Hephaestus → Hermes | Pipeline inputs/outputs, model endpoints | | Prometheus → Hermes | Deploy target, env vars, config changes |

For MEDIUM and LOW entries, skip variant templates — use standard 1-line or aggressive compression.

5. Downstream-Aware Compression

Each entry type uses a field mask based on (from_agent, to_agent). The field mask determines which subtask_summary fields survive compression.

Available Fields

| Field | Type | Description | |-------|------|-------------| | date | string | YYYY-MM-DD | | agent | string | Agent name | | files | string | Comma-separated file paths | | summary | string | Full summary text | | summary_semantic | string | Generated semantic summary (CRITICAL/HIGH only) | | tests | string | Test status + count | | status | string | complete / partial / escalated | | coverage | string | Coverage percentage | | verdict | string | Themis verdict (APPROVED/NEEDS_REVISION/FAILED) | | critical_issues | int | Count of critical issues found | | blockers | string | Blocker description |

Field Masks Per Agent Pair

| From → To | Fields Preserved | Notes | |-----------|-----------------|-------| | hermes → aphrodite | date, agent, files, summary_semantic, tests, status | Endpoint + schema only | | hermes → demeter | date, agent, files, summary_semantic, tests, status | Models + relationships only | | hermes → * (default) | date, agent, files, summary_semantic, tests, status | | | demeter → hermes | date, agent, files, summary_semantic, tests, status | Tables + migrations only | | demeter → aphrodite | date, agent, files, summary_semantic, tests, status | New fields only | | demeter → * (default) | date, agent, files, summary_semantic, tests, status | | | aphrodite → hermes | date, agent, files, summary_semantic, tests, status | Component + data needs | | aphrodite → demeter | date, agent, files, summary_semantic, tests, status | UI state + fields | | aphrodite → * (default) | date, agent, files, summary_semantic, tests, status | | | themis → * | date, agent, verdict, critical_issues, coverage, files | Review context | | * → themis | date, agent, files, summary (full), tests, status, coverage | Full context | | * → mnemosyne | date, agent, summary (first 60 chars), status | Minimal | | hephaestus → * | date, agent, files, summary_semantic, tests, status | Pipeline + model info | | prometheus → * | date, agent, files, summary_semantic, tests, status | Deploy + config info |

Implementation

Zeus applies the mask before generating the compressed entry:

def apply_mask(entry: dict, from_agent: str, to_agent: str) -> dict:
    mask = FIELD_MASKS.get((from_agent, to_agent), FIELD_MASKS[("*", "*")])
    return {k: v for k, v in entry.items() if k in mask}

6. Budget Allocation Algorithm

Compressed entries live in the ## Completed Phases section of 01-active-context.md. The total budget is managed to prevent unbounded growth.

Budget

TOTAL_BUDGET = 100 lines for ## Completed Phases section
PER_PHASE_BUDGET = TOTAL_BUDGET / estimated_phases (floor 5 lines)

Estimated_phases is the total number of phases planned for the current feature. If unknown, default to 8 phases → PER_PHASE_BUDGET = 12 lines.

Line Cost Table

| Priority | Expanded | Standard | Aggressive | |----------|----------|----------|------------| | CRITICAL | 3 lines | N/A | N/A | | HIGH | 2 lines | 1 line | N/A | | MEDIUM | N/A | 1 line | N/A | | LOW | N/A | N/A | 0.5 lines |

Priority-Greedy Algorithm

1. Sort all entries by priority_score descending.
2. CRITICAL entries always get EXPANDED (3 lines each) — non-negotiable.
3. For remaining budget (TOTAL_BUDGET − sum(CRITICAL×3)):
   • HIGH entries: EXPANDED (2 lines) if budget allows, else STANDARD (1 line).
   • MEDIUM entries: STANDARD (1 line).
   • LOW entries: AGGRESSIVE (0.5 lines, filename only).
4. If at any point CRITICAL entries would exceed TOTAL_BUDGET → escalate to Zeus (see Budget Guardrails, §18).

Example

Feature has 8 phases. TOTAL_BUDGET = 100, PER_PHASE_BUDGET = 12.

Phase 1 submits:
- Entry A: score 0.82 → CRITICAL (3 lines)
- Entry B: score 0.45 → MEDIUM (1 line)
Total: 4 lines (of 12 budget). 8 lines carried to next phase.

Phase 2 submits:
- Entry C: score 0.91 → CRITICAL (3 lines)
- Entry D: score 0.67 → HIGH — budget has 20 remaining lines, so EXPANDED (2 lines)
- Entry E: score 0.21 → LOW (0.5 lines)
Total: 5.5 lines. Cumulative 9.5 of 24 budget.

7. Cross-Reference Mechanism

Auto-generated _xref/index.md provides persistent entity references that survive sprint boundaries and feature completions.

Cross-Reference File Location

.pantheon/memory-bank/_xref/index.md (created if absent; committed like _notes/)

Reference ID Format

| Prefix | Type | Example | Generated When | |--------|------|---------|----------------| | D{NNNN} | Decision | D0001 | REVIEW with decision note | | E{NNNN} | Endpoint | E0001 | CRITICAL entry mentions new endpoint | | M{NNNN} | Migration | M0001 | CRITICAL entry mentions new table/column | | C{NNNN} | Component | C0001 | CRITICAL entry mentions new component |

IDs are monotonic integers pulled from _xref/_next_id.json and incremented.

Auto-Generation Rules

| Condition | Action | |-----------|--------| | CRITICAL entry mentions a new endpoint (keywords: POST, GET, PUT, DELETE, /api/, /v1/, /v2/, endpoint, route) | Add to By Entity table with agent, phase, file reference | | CRITICAL entry mentions new table/column (keywords: new table, new column, migration, ALTER TABLE, CREATE TABLE) | Add to By Entity table with migration reference | | Entry that was previously blocked now completes | Link from blocking entry → unblocking entry in cross-refs | | REVIEW with decision note (## Decision or ADR reference) | Add to Decision Links table |

Cross-Reference Index File Structure

# Cross-Reference Index

## By Feature

| Feature | Phase(s) | Agent(s) | Priority | Summary |
|---------|----------|----------|----------|---------|
| auth-jwt | 1, 2 | Hermes, Aphrodite | HIGH | JWT login + refresh token UI |

## By Entity

| Entity ID | Type | Name | Location | Phase | Agent |
|-----------|------|------|----------|-------|-------|
| E0001 | endpoint | POST /auth/login | backend/routers/auth.py:42 | P1 | Hermes |
| M0001 | migration | add refresh_tokens table | backend/migrations/0012_... | P1 | Demeter |

## Decision Links

| Ref ID | Type | Summary | Links To | Phase |
|--------|------|---------|----------|-------|
| D0001 | ADR | Use refresh token rotation instead of opaque tokens | _notes/ADR-auth-strategy.md | P1 |

8. ZZ Artifact Format

A compressed context artifact ZZ-phase{N}-context.md is generated after each phase and injected into the next phase's agent prompt. It lives in .pantheon/memory-bank/.tmp/.

Location

.pantheon/memory-bank/.tmp/ZZ-phase{N}-context.md

Format

# Phase N → Phase N+1 Context
**From:** @agent_A (Phase N)
**To:** @agent_B (Phase N+1)

## Budget
- Allocated: 12 lines
- Used: 4 lines
- Carried: 8 lines

## Priority Entries

### CRITICAL (expanded)

**Entry:** Auth JWT endpoint
**Agent:** Hermes | **Score:** 0.82
**What changed:** Added POST /auth/login and POST /auth/refresh endpoints with JWT rotation. Access token lives 15 min, refresh token 7 days.
**To next agent:** Aphrodite needs to implement login form and token storage (httpOnly cookies), auto-refresh on 401.
**Gotcha:** Refresh tokens are stored in DB as hashed — no raw token access after issue. Rotate on every use.

**Entry:** Refresh token table
**Agent:** Demeter | **Score:** 0.91
**What changed:** Created `refresh_tokens` table with FK to `users`, hashed token, expires_at, revoked_at.
**To next agent:** Hermes needs the TokenService to call `create_refresh_token()` + `rotate_refresh_token()`.
**Gotcha:** Migration includes a unique composite index on (user_id, token_hash). Two-phase rollout — read-old/write-new first.

### HIGH (2-line)

**Entry:** Login page component
**Agent:** Aphrodite | **Score:** 0.62
**What changed:** Login form with email + password, validation, error display. Hits POST /auth/login.
**To next agent:** Hermes can test the full flow once Aphrodite's form is wired.

### STANDARD (1-line)

| Date | Agent | Summary | Status |
|------|-------|---------|--------|
| 2026-06-20 | Prometheus | Dockerized auth service with nginx | complete |

## Cross-References

| ID | Type | Name | File |
|----|------|------|------|
| E0001 | endpoint | POST /auth/login | backend/routers/auth.py |
| M0001 | migration | refresh_tokens table | backend/migrations/0012_... |

9. Delegation Flow (Level 2)

Zeus receives Themis APPROVED for Phase N
    │
    ├─ [COGNITIVE] Score each subtask_summary (priority scoring engine, no LLM)
    │     5 dimensions: Impact, Risk, Novelty, Blockers, Downstream relevance
    │     → CRITICAL / HIGH / MEDIUM / LOW per entry
    │
    ├─ [COGNITIVE] Determine next phase agents + downstream relevance
    │     Look up (from_agent, to_agent) in agent-pair table
    │
    ├─ [COGNITIVE] Run budget allocation (priority-greedy)
    │     CRITICAL always expanded → HIGH → MEDIUM → LOW
    │     Check overflow: if CRITICAL > budget → escalate
    │
    ├─ [COGNITIVE] Generate semantic summaries (CRITICAL/HIGH only, ~50 tok each)
    │     Template variants per (from_agent, to_agent)
    │
    ├─ [COGNITIVE] Identify cross-references
    │     New endpoints → E{NNNN}, new tables → M{NNNN}, decisions → D{NNNN}
    │
    ├─ DELEGATE @mnemosyne Compress batch (enhanced):
    │     a) Write ZZ-phase{N}-context.md to .tmp/
    │     b) Write compressed entries to 01-active-context.md (priority-aware)
    │        - CRITICAL: expanded (3 lines, semantic summary)
    │        - HIGH: expanded (2 lines) or standard (1 line) per budget
    │        - MEDIUM: standard (1 line)
    │        - LOW: aggressive (0.5 lines)
    │     c) Archive IMPL/REVIEW to 02-progress-log.md
    │     d) Update _xref/index.md
    │        - CRITICAL mentions of endpoints → By Entity
    │        - CRITICAL mentions of tables → By Entity
    │        - Decision notes → Decision Links
    │        - Blocked→unblocked links
    │     e) Increment _xref/_next_id.json
    │
    └─ Zeus injects ZZ-phase{N}-context.md into Phase N+1 agent prompts
         Included in the prompt preamble: "Previous phase context: <ZZ content>"

Standard Flow (C1 + C2 + C3 fire together)

Zeus receives Themis APPROVED for Phase N
    │
    ├─ [COGNITIVE] Score + summarize + budget + cross-refs (as above)
    │
    ├─ @mnemosyne Compress (enhanced):
    │     a) Write ZZ-phase{N}-context.md to .tmp/
    │     b) Priority-aware write to 01-active-context.md
    │     c) Archive IMPL/REVIEW to 02-progress-log.md
    │     d) Update _xref/index.md
    │     e) Increment _xref/_next_id.json
    │
    ├─ @mnemosyne Confirm: "Compression complete: N entries compressed (M CRITICAL, P HIGH), K cross-refs added"
    │
    ├─ [COGNITIVE] Zeus checks: are there pending learnings? (Wisdom Bridge)
    │     If yes → inject into next agent's prompt
    │
    └─ Zeus continues orchestration → dispatches next phase with ZZ artifact

Safety Preflight

Before ANY compression, Zeus MUST run this check:

def can_compress(artifact_type, status, verdict):
    if artifact_type == "subtask_summary":
        return status == "complete"  # NOT in_progress, escalated, blocked
    if artifact_type == "IMPL":
        return True  # Themis APPROVED already verified
    if artifact_type == "REVIEW":
        return verdict == "APPROVED"  # NOT NEEDS_REVISION, FAILED
    if artifact_type == "PLAN":
        return all_phases_complete
    if artifact_type == "DISC":
        return user_approved
    if artifact_type == "ADR":
        return False  # NEVER compress ADRs
    return False

10. Safety Rules — NEVER Compress

Same as Level 1. Never compress the following:

| Artifact / Condition | Action | |----------------------|--------| | subtask_summary with in_progress / escalated / blocked | Skip. Flag to Zeus. | | REVIEW with NEEDS_REVISION / FAILED | Skip. Leave in .tmp/. | | Current active PLAN | Skip. Archive only at feature completion. | | ADR notes (_notes/) — permanent, immutable | NEVER touch. | | Any artifact with active blockers | Skip. Flag to Zeus. |

Partial Compress — Warnlist

| Artifact / Condition | Action | |----------------------|--------| | subtask_summary with status partial | Compress BUT mark status as ⚠️ and score as MEDIUM minimum | | DISC with REQUEST CHANGES | Flag to user, do not archive | | DISC with DISCARD | Delete artifact, do not archive | | Unrecognized .tmp/ artifact | Flag to user, leave in place |

11. Transactional Write Protocol (C1 mitigation)

Same as Level 1. Atomic write prevents corruption from crashes during compression:

1. Write to target file + .tmp suffix (same directory)
2. fsync() the file descriptor — ensures data flushed to disk
3. Validate: file > 0 bytes, has a heading (# or ## line)
4. os.rename(.tmp, target) — POSIX atomic rename on same filesystem
5. If crash during write: stale .tmp cleaned on next startup (>5 min old)

import os

def atomic_write(path: str, content: str):
    tmp_path = path + ".tmp"
    with open(tmp_path, "w") as f:
        f.write(content)
        f.flush()
        os.fsync(f.fileno())
    if os.path.getsize(tmp_path) == 0:
        raise RuntimeError(f"Write validation failed: {tmp_path} is empty")
    os.rename(tmp_path, path)

12. Inline Compression — Active Session Protocol

"Inline compression" (L1) is the Pantheon-native mechanism agents use DURING an active session to shrink working context. It is distinct from "L2" batch promotion — the file-based Memory Bank writes Mnemosyne performs at phase boundaries (see §9). These are NOT a mandatory 3-layer trigger model: agents invoke L1 only; L2 happens automatically at gates.

L1 — Inline Compression (the only agent-triggered step)

Call the compressor via the MCP tool. Scrubbing is AUTOMATIC in the MCP layer — never scrub manually and never embed raw secrets beyond what the tool scrubs:

execute_code_script("compress-inline.py", args=["compress", "--text", "<content>"])

Modes: score (preview priority), compress (scrub + score + compress), stats, batch (multiple files).

L2 — Batch Promotion (automatic, not an agent trigger)

At phase gates / handoffs, Mnemosyne promotes compressed entries into the file-based Memory Bank (01-active-context.md, etc.). Agents do NOT invoke L2 — it runs automatically. Inline compression (L1) and batch promotion (L2) are NOT a mandatory 3-layer trigger model.

Triggers (full table in §2)

• C8: after a CRITICAL/HIGH subtask_summary → L1 compress before next phase.
• C9: before delegating a large context block → L1 compress to cut tokens.
• C10: context pressure → handled by OpenCode native compaction (cross-reference only; no Pantheon mechanism).
• C11: phase boundary / handoff → L1 compress completed work.

Promotion Pipeline (context flow, not a trigger model)

The Flow below shows how compressed context PROMOTES from live session → inline → batch. Agents run L1 only; L2 is automatic at gates:

Agent produces context (subtask_summary, large block, phase work)
    │
    ├─ [L1 INLINE] execute_code_script("compress-inline.py", args=["compress", "--text", "..."])
    │     → scrubbed + scored + compressed output (MCP layer scrubs automatically)
    │
    └─ [L2 PROMOTE] At phase gate / handoff, Mnemosyne promotes compressed
          entries into the file-based Memory Bank (01-active-context.md, etc.)
          → batch promotion, NOT an agent trigger

Safety Rules

| Rule | Description | |------|-------------| | Scrubbing is automatic in the MCP layer | Never run a manual scrub; never embed raw secrets beyond what the tool scrubs | | compress-inline.py always scrubs before scoring | Built-in security — no agent action needed | | Inline compression (L1) is non-destructive to source files | Output is returned; originals untouched |

Agent Responsibilities

Implementation agents (Hermes, Aphrodite, Demeter, Hephaestus, Prometheus):

• After a CRITICAL/HIGH subtask_summary → trigger C8 (L1 compress)
• Before delegating a large context block → trigger C9 (L1 compress)
• At a phase boundary / handoff → trigger C11 (L1 compress)
• Do NOT implement a separate context-pressure mechanism (C10 is OpenCode-native)

13. Security Scrubbing (H1 mitigation)

Scrubbing is automatic — the memory_store MCP server applies Layer 2 regex scrub before persisting content. No manual steps required.

Layer 1 — Structural (metadata only)

Only promote structured metadata. NEVER promote:

• Raw stdout or stderr output
• Test output or command results
• Stack traces or error details
• Environment variables or configuration values

Allowed fields: file paths, status, pass/fail verdicts, phase names, agent names, dates.

Layer 2 — Regex pattern scrub (automatic via MCP layer)

Source of truth: scripts/scrub-secrets.py — the single canonical scrubber. Both memory_mcp_server.py and compress-inline.py load it via importlib (the filename has a hyphen and cannot be imported normally). Do NOT maintain a separate inline pattern list.

Real signature:

def scrub(content: str) -> tuple[str, list[dict]]:
    # returns (scrubbed_text, redactions)
    # each redaction dict: {"type": str, "position": (start, end), "replacement": str}

Secret types covered (see scripts/scrub-secrets.py for the actual patterns): SSH private key, private key, certificate, Bearer token, JWT, GitHub PAT (ghp_), OpenAI key (sk-...), generic api_key/token/secret/password, AWS access key (AKIA), Google API key (AIza), Slack token (xox), Heroku API key (UUID), PostgreSQL/MySQL/Redis connection strings, and .env export statements.

Scrubbing is AUTOMATIC in the MCP layer — memory_store and compress-inline both call scrub() before persistence. Agents never scrub manually.

14. Concurrency (M1 mitigation)

Same as Level 1. Zeus batches parallel phase completions into a single compression call. Lockfile safety net.

Batching rule: When multiple parallel phases complete simultaneously, Zeus collects all subtask_summaries and dispatches a single compression request to Mnemosyne:

@mnemosyne Compress batch (enhanced): [
  { type: subtask, phase: "2a", agent: Hermes, from: Hermes, to: Aphrodite, ... },
  { type: subtask, phase: "2b", agent: Aphrodite, from: Aphrodite, to: Hermes, ... },
  ...
]

Each entry is independently scored and budget-allocated.

Lockfile safety net: A lockfile at .pantheon/memory-bank/.tmp/compress.lock with flock as a safety net for the rare case of overlapping manual /compress and automatic compression.

15. Wisdom Bridge

Same as Level 1. Extraction BEFORE compression, non-blocking failures.

Phase N Themis APPROVED
    │
    ├─ 1. Agent extracts learnings → .pantheon/learnings/<feature>/learnings.md
    ├─ 2. Compression fires (scored + archived)
    └─ 3. Next agent dispatched with ZZ artifact + learnings injected

Extraction is advisory, compression is mandatory. If the agent fails to extract learnings (timeout, error), compression proceeds anyway.

Injection

Zeus reads .pantheon/learnings/<feature>/learnings.md and includes in the next agent's prompt:

## Previous Wave Learnings
<contents of learnings.md>

## Compressed Context (Phase N → Phase N+1)
<contents of ZZ-phase{N}-context.md>

Apply these learnings and context to your implementation.

Cleanup

At feature merge or sprint close:

1. Promote surviving learnings (those not already in /memories/repo/) to atomic facts
2. Delete .pantheon/learnings/<feature>/learnings.md

16. Rollback (C2 — use git)

Same as Level 1.

# View history of compressed file
git log -p .pantheon/memory-bank/01-active-context.md | less

# Restore pre-compression state
git show HEAD~1:.pantheon/memory-bank/01-active-context.md > .pantheon/memory-bank/01-active-context.md

# Or revert specific commit
git revert <commit-sha>

Pre-compression content is always available in git history.

17. Idempotency

Updated for Level 2 with content hashing and cross-ref dedup.

| Target | Idempotency Key | Behavior | |--------|----------------|----------| | 01-active-context.md table row | (date, phase, agent) + content hash of summary | Skip if exact match exists; overwrite if same key but different hash | | 02-progress-log.md section | ### YYYY-MM-DD — <phase>: <agent> | Skip append if heading exists | | 02-progress-log.md REVIEW line | **Review:** in same section | Skip if line exists | | 01-active-context.md Plans row | (date, feature) | Skip if exists | | _xref/index.md | | E{NNNN} reference ID | Skip if ID exists; error if ID already used for different entity | | _xref/_next_id.json | File path | Overwrite with incremented value | | ZZ-phase{N}-context.md | Phase number | Overwrite if same phase (last write wins) | | .tmp/ file deletion | File path | File not found → silent skip |

Content Hash

import hashlib

def entry_hash(entry: dict) -> str:
    canonical = f"{entry['date']}|{entry['phase']}|{entry['agent']}|{entry.get('summary', '')}"
    return hashlib.sha256(canonical.encode()).hexdigest()[:16]

When checking for duplicates, both the idempotency key AND the content hash must match for a skip. Same key but different hash → overwrite (entry was updated).

18. Budget Guardrails

Prevent budget abuse and ensure CRITICAL entries are never lost.

Rules

| Guardrail | Threshold | Action | |-----------|-----------|--------| | CRITICAL floor | CRITICAL entries always expanded | Non-negotiable. Never compress to standard or aggressive. | | Overflow | >5 CRITICAL entries per phase | Flag Zeus: "Phase N has M > 5 CRITICAL entries. Budget risk." | | Exceed budget | CRITICAL entries alone exceed TOTAL_BUDGET (100 lines) | Escalate to Zeus: "CRITICAL entries require N lines but budget is 100. Options: (1) increase budget, (2) increase TOTAL_BUDGET permanently, (3) split phase." | | Carryover | Unused PER_PHASE_BUDGET | 20% of unused budget rolls to next phase (round down). Remaining 80% is released (does not carry forward). | | Ceiling | ## Completed Phases section | Hard cap at 100 lines. Overflows trigger C7 size-based trim on LOW entries first. |

Carryover Formula

carryover = floor(remaining_budget * 0.20)
next_phase_budget = PER_PHASE_BUDGET + carryover

Example: Phase 1 had 12-line budget, used 4 lines. Remaining = 8 lines. Carryover = floor(8 × 0.20) = 1 line. Phase 2 starts with 12 + 1 = 13 lines.

C7 Trim Priority (Size-Based Auto-Trim)

When 01-active-context.md exceeds 100 lines:

1. Sort entries by priority_score ascending (lowest first).
2. Trim LOW entries first (remove entire 0.5-line rows).
3. If still over budget, trim MEDIUM entries to 0.5 lines each.
4. Never trim CRITICAL or HIGH.
5. Trimmed entries are archived to _notes/archive/YYYY-MM-compressed-entries.md.
6. Log: "C7 trim: removed N low-priority entries, archived to _notes/archive/..."

Quick Reference

┌────────────────────────────────────────────────────────────────────┐
│              CONTEXT COMPRESSION — LEVEL 2                         │
│                                                                    │
│  Priority Scoring (deterministic, no LLM):                         │
│    Score = 0.30×Impact + 0.25×Risk + 0.20×Novelty + 0.15×Blockers │
│            + 0.10×Downstream_relevance                             │
│    CRITICAL ≥ 0.75 | HIGH ≥ 0.50 | MEDIUM ≥ 0.25 | LOW < 0.25    │
│                                                                    │
│  Semantic Summarization (CRITICAL/HIGH only):                      │
│    Template per agent pair, ~50 tok each                           │
│    CRITICAL: 3 lines (what + why + gotcha)                         │
│    HIGH: 2 lines (what + why)                                      │
│                                                                    │
│  Downstream-Aware Field Masks:                                     │
│    (from_agent, to_agent) → field set                              │
│    *→Themis: preserve ALL  |  *→Mnemosyne: preserve MINIMAL       │
│                                                                    │
│  Budget Allocation (priority-greedy):                              │
│    TOTAL = 100 lines | PER_PHASE = floor(100 / phases)             │
│    CRITICAL always expanded → HIGH → MEDIUM → LOW                  │
│    20% of unused budget carries to next phase                      │
│                                                                    │
│  Cross-References:                                                 │
│    E{NNNN} endpoints | M{NNNN} migrations | D{NNNN} decisions     │
│    C{NNNN} components | Auto-generated in _xref/index.md          │
│                                                                    │
│  ZZ Artifact:                                                      │
│    .pantheon/memory-bank/.tmp/ZZ-phase{N}-context.md                    │
│    Injected into next phase agent prompt                           │
│                                                                    │
│  Safety: NEVER compress in_progress/escalated/                     │
│    blocked/NEEDS_REVISION/FAILED/ADR                               │
│  Write safety: atomic .tmp + fsync + rename                        │
│  Security: Layer 1 (structural) + Layer 2 (regex)                  │
│  Concurrency: Zeus batches, lockfile as safety net                 │
│  Rollback: git log -p                                              │
│  Idempotent: keyed by (date, phase, agent) + content hash          │
│  Budget guardrails: CRITICAL floor, overflow flag, carryover       │
│  Inline Compression (C8-C11 - Active Session, L1 = Pantheon-native): │
│    C8: CRITICAL/HIGH subtask_summary → compress (L1)                │
│    C9: pre-delegation large block → compress (L1)                   │
│    C10: context pressure → OpenCode native compaction (x-ref only)   │
│    C11: phase boundary / handoff → compress (L1)                    │
│    L1 = compress-inline.py MCP | L2 = batch promotion (Mnemosyne)   │
│    Scrubbing automatic in MCP layer — never scrub manually           │
│                                                                    │
│  Zeus: cognitive scoring + summarization + budget + cross-refs     │
│  Mnemosyne: file I/O (write ZZ, active context, progress log,      │
│              xref index, next_id.json, delete .tmp)                │
└────────────────────────────────────────────────────────────────────┘

References:

• skill: artifact-management — artifact lifecycle
• instructions/agent-return-format.instructions.md — subtask_summary format
• skill: memory-bank — memory bank structure
• skills/wisdom-accumulation/SKILL.md — learning extraction
• skills/memory-bank/SKILL.md — memory bank maintenance
• instructions/backend-standards.instructions.md — zeus scoring reference