Run any Skill in Manus with one click

context-compression

Stars10

Forks5

UpdatedJuly 21, 2026 at 23:36

Level 2 — Pantheon-native context compression with priority scoring, semantic summarization, downstream-aware compression, budget allocation, and cross-references

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

ils15

ils15/pantheon-legacy

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

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:

Priority Scoring Engine — Deterministic keyword-driven scoring (no LLM) for each subtask_summary across 5 dimensions. Outputs CRITICAL/HIGH/MEDIUM/LOW.
Semantic Summarization — Template-generated contextual summaries for CRITICAL/HIGH entries, tailored to the downstream agent pair. MEDIUM/LOW get standard mechanical 1-line compression.
Downstream-Aware Compression — Field masks preserve the most relevant fields per (from_agent, to_agent) pair. Themis gets all fields; Mnemosyne gets minimal.
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

Sort all entries by priority_score descending.
CRITICAL entries always get EXPANDED (3 lines each) — non-negotiable.
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).
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:

Write to target file + .tmp suffix (same directory)
fsync() the file descriptor — ensures data flushed to disk
Validate: file > 0 bytes, has a heading (# or ## line)
os.rename(.tmp, target) — POSIX atomic rename on same filesystem
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:

Promote surviving learnings (those not already in /memories/repo/) to atomic facts
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
`_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:

Sort entries by priority_score ascending (lowest first).
Trim LOW entries first (remove entire 0.5-line rows).
If still over budget, trim MEDIUM entries to 0.5 lines each.
Never trim CRITICAL or HIGH.
Trimmed entries are archived to _notes/archive/YYYY-MM-compressed-entries.md.
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

name	context-compression
description	Level 2 — Pantheon-native context compression with priority scoring, semantic summarization, downstream-aware compression, budget allocation, and cross-references
context	fork
globs	["/01-active-context.md","/02-progress-log.md"]
alwaysApply	false

Context Compression — Level 2 (Intelligent Compression)

1. Overview

Level 2 adds four capabilities beyond Level 1:

Priority Scoring Engine — Deterministic keyword-driven scoring (no LLM) for each subtask_summary across 5 dimensions. Outputs CRITICAL/HIGH/MEDIUM/LOW.
Semantic Summarization — Template-generated contextual summaries for CRITICAL/HIGH entries, tailored to the downstream agent pair. MEDIUM/LOW get standard mechanical 1-line compression.
Downstream-Aware Compression — Field masks preserve the most relevant fields per (from_agent, to_agent) pair. Themis gets all fields; Mnemosyne gets minimal.
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)

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

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

Sort all entries by priority_score descending.
CRITICAL entries always get EXPANDED (3 lines each) — non-negotiable.
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).
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:

Write to target file + .tmp suffix (same directory)
fsync() the file descriptor — ensures data flushed to disk
Validate: file > 0 bytes, has a heading (# or ## line)
os.rename(.tmp, target) — POSIX atomic rename on same filesystem
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

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)

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)

Real signature:

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

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:

Promote surviving learnings (those not already in /memories/repo/) to atomic facts
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
`_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:

Sort entries by priority_score ascending (lowest first).
Trim LOW entries first (remove entire 0.5-line rows).
If still over budget, trim MEDIUM entries to 0.5 lines each.
Never trim CRITICAL or HIGH.
Trimmed entries are archived to _notes/archive/YYYY-MM-compressed-entries.md.
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

context-compression

More from this repository

More from this repository

Context Compression — Level 2 (Intelligent Compression)

1. Overview

2. Compression Triggers

Inline Compression Triggers (C8-C11 — Active Session)

3. Priority Scoring Engine

Scoring Dimensions

Full Keyword Scoring Map

Downstream Relevance Table

Priority Bands

Scoring Example

4. Semantic Summarization

Template: CRITICAL (3 lines)

Template: HIGH (2 lines)

Template: MEDIUM (1 line)

Template: LOW (filename only)

Variants Per Agent Pair

5. Downstream-Aware Compression

Available Fields

Field Masks Per Agent Pair

Implementation

6. Budget Allocation Algorithm

Budget

Line Cost Table

Priority-Greedy Algorithm

Example

7. Cross-Reference Mechanism

Cross-Reference File Location

Reference ID Format

Auto-Generation Rules

Cross-Reference Index File Structure

8. ZZ Artifact Format

Location

Format

9. Delegation Flow (Level 2)

Standard Flow (C1 + C2 + C3 fire together)

Safety Preflight

10. Safety Rules — NEVER Compress

Partial Compress — Warnlist

11. Transactional Write Protocol (C1 mitigation)

12. Inline Compression — Active Session Protocol

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

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

Triggers (full table in §2)

Promotion Pipeline (context flow, not a trigger model)

Safety Rules

Agent Responsibilities

13. Security Scrubbing (H1 mitigation)

Layer 1 — Structural (metadata only)

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

14. Concurrency (M1 mitigation)

15. Wisdom Bridge

Injection

Cleanup

16. Rollback (C2 — use git)

17. Idempotency

Content Hash

18. Budget Guardrails

Rules

Carryover Formula

C7 Trim Priority (Size-Based Auto-Trim)

Quick Reference

Context Compression — Level 2 (Intelligent Compression)

1. Overview

2. Compression Triggers

Inline Compression Triggers (C8-C11 — Active Session)

3. Priority Scoring Engine

Scoring Dimensions

Full Keyword Scoring Map

Downstream Relevance Table

Priority Bands

Scoring Example

4. Semantic Summarization

Template: CRITICAL (3 lines)

Template: HIGH (2 lines)

Template: MEDIUM (1 line)

Template: LOW (filename only)

Variants Per Agent Pair