Compile — Knowledge Compiler

Reads raw

.agents/

What This Skill Does

The knowledge flywheel captures signal reactively (via

$retro

$post-mortem

$forge

$compile

1. Mining unextracted signal from git and

   .agents/

   (existing)
2. Growing learnings via validation, synthesis, and gap detection (existing)
3. Compiling raw artifacts into interlinked wiki articles (core value)
4. Linting the compiled wiki for contradictions, orphans, and gaps
5. Defragging stale and duplicate artifacts (existing)

No vector DB. At personal scale (~100-400 articles), the compiled wiki fits in context windows. The wiki IS the retrieval layer.

Output:

.agents/compiled/

[[backlinks]]

index.md

log.md

Pluggable Compute Backend

Set

AGENTOPS_COMPILE_RUNTIME

ollama

OLLAMA_HOST

http://localhost:11434

openai

OPENAI_API_KEY

When unset,

ao compile

Large-corpus batching

ao compile --batch-size N

--max-batches N

Execution Steps

Step 0: Setup

mkdir -p .agents/compiled

Determine mode from arguments:

• $compile

  — Full cycle: Mine → Grow → Compile → Lint → Defrag

• $compile --compile-only

  — Skip mine/grow, just compile + lint

• $compile --lint-only

  — Only lint the existing compiled wiki

• $compile --defrag-only

  — Only run defrag/cleanup

• $compile --mine-only

  — Only run mine + grow (legacy behavior)

Step 1 — Mine: Extract Signal

Run mechanical extraction. Mine scans git history,

.agents/research/

ao mine --since 26h                    # default: all sources, last 26h
ao mine --since 7d --sources git,agents  # wider window, specific sources

Read

.agents/mine/latest.json

.agents/research/

Fallback (no ao CLI): Use

git log --since="7 days ago" --name-only

.agents/research/*.md

Assign Initial Confidence. For every new learning candidate extracted, assign a confidence score based on evidence strength:

Also assign a scope tag:

project:<name>

language:<lang>

global

project:<current>

Write the confidence and scope into the learning frontmatter:

---
title: "Learning title"
confidence: 0.3
scope: project:agentops
observed_in:
  - session: "YYYY-MM-DD"
    context: "Brief description of observation"
---

Step 2 — Grow: LLM-Driven Synthesis

This is the reasoning phase. Perform each sub-step using tool calls.

Flywheel Health Diagnostic: Compute σ (consistency), ρ (velocity), δ (decay) and report escape velocity status. See

references/flywheel-diagnostics.md

2a. Validate Top Learnings and Adjust Confidence

Select the 5 most recent files from

.agents/learnings/

1. Read the learning file (including its

   confidence

   and

   scope

   frontmatter)
2. If it references a function or file path, verify the code still exists
3. Classify as: validated (matches), stale (changed), or contradicted (opposite)
4. Adjust confidence based on validation result:
   • Validated and still accurate: +0.1 (cap at 0.9)
   • Stale but partially true: no change (mark for review)
   • Contradicted by current code: -0.2 (floor at 0.1, flag for removal)
   • Pattern validated in a new project: +0.15
   • Not referenced in 30+ days: -0.05 (time decay)
   • Not referenced in 90+ days: -0.1 (time decay)

Update the learning file frontmatter with the new confidence score.

Auto-Promotion Rule: After confidence adjustment, check if the learning's confidence is > 0.7. If so, and it is not already in MEMORY.md, promote it:

1. Add the learning's key insight to the relevant MEMORY.md topic file
2. Log:

   "Promoted '<title>' to MEMORY.md (confidence: <score>)"

3. If the same pattern appears in 2+ projects with confidence >= 0.8, promote its scope from

   project:<name>

   to

   global

2b. Rescue Orphaned Research

For each orphaned research file from mine output: read it, summarize the key insight in 2-3 sentences, and propose as a new learning candidate with title and category.

2c. Cross-Domain Synthesis

Group mine findings by theme (e.g., "testing patterns", "CLI conventions"). For themes with 2+ findings, write a synthesized pattern candidate capturing the common principle.

2d. Gap Identification

Compare mine output topics against existing learnings. Topics with no corresponding learning are knowledge gaps. List each with: topic, evidence, suggested learning title.

Step 3 — Compile: Build the Wiki

This is the core phase. The LLM reads all raw

.agents/

3a. Inventory Source Artifacts

Scan all compilable directories:

find .agents/learnings .agents/patterns .agents/research .agents/retros \
     .agents/forge .agents/knowledge -type f -name "*.md" 2>/dev/null | sort

For each file, compute a content hash. Compare against

.agents/compiled/.hashes.json

3b. Extract Topics and Entities

Read each changed source artifact. Extract:

• Topics: major themes (e.g., "testing strategy", "CI pipeline", "knowledge flywheel")
• Entities: specific tools, files, patterns, people referenced
• Relationships: which topics connect to which entities

Group artifacts by topic. Each topic becomes a wiki article.

3c. Compile Articles

For each topic, compile an encyclopedia-style article:

If

AGENTOPS_COMPILE_RUNTIME

If running inline (no runtime set), compile directly:

For each topic group, write a wiki article to

.agents/compiled/<topic-slug>.md

---
title: "<Topic Title>"
compiled: "YYYY-MM-DD"
sources:
  - .agents/learnings/example.md
  - .agents/research/example.md
tags: [topic1, topic2]
---

# <Topic Title>

<2-3 paragraph synthesis of all source artifacts on this topic.
Not a summary — a compiled understanding that connects the dots
across multiple observations.>

## Key Insights

- <Insight 1> — from [[source-article-1]]
- <Insight 2> — from [[source-article-2]]

## Related

- [[other-topic-1]] — <why related>
- [[other-topic-2]] — <why related>

## Sources

- `source1.md` — .agents/learnings/source1.md
- `source2.md` — .agents/research/source2.md

Use

[[backlinks]]

3d. Build Index

Write

.agents/compiled/index.md

# Knowledge Wiki — Index

> Auto-compiled from .agents/ corpus. Last updated: YYYY-MM-DD.
> Articles: N | Sources: N | Topics: N

## By Category

### <Category 1>
- [[article-1]] — one-line summary
- [[article-2]] — one-line summary

3e. Append to Log

Append to

.agents/compiled/log.md

## [YYYY-MM-DD] compile | <N> articles from <M> sources
- New: <list of new articles>
- Updated: <list of updated articles>
- Unchanged: <count> (skipped, hashes match)

3f. Save Hashes

Write

.agents/compiled/.hashes.json

Step 4 — Lint: Wiki Health Check

Scan the compiled wiki for quality issues.

4a. Contradictions — Compare claims across articles. Flag conflicting assertions.

4b. Orphan Pages — Find articles with zero inbound

[[backlinks]]

4c. Missing Cross-References — Find articles discussing same topics but not linking.

4d. Stale Claims — Verify code references still exist.

4e. Coverage Gaps — Flag source artifacts that contributed to zero wiki articles.

4f. Write Lint Report — Write

.agents/compiled/lint-report.md

Step 5 — Defrag: Mechanical Cleanup

Run cleanup to find stale, duplicate, and oscillating artifacts.

ao defrag --prune --dedup --oscillation-sweep

Read

.agents/defrag/latest.json

Fallback:

find .agents/learnings -name "*.md" -mtime +30

Normalization Defect Scan

During defrag, scan the learnings and patterns pool for structural defects:

• PLACEHOLDER → HIGH (empty knowledge pollutes retrieval)
• STACKED_FRONTMATTER → MEDIUM (parsing errors, possible data loss)
• BUNDLED → HIGH (breaks per-learning citation tracking)
• DUPLICATE_HEADING → LOW (cosmetic, may confuse extraction)

Step 6 — Report

Write

.agents/compile/YYYY-MM-DD-report.md

Scheduling / Auto-Trigger

Lightweight defrag (prune + dedup, no mining or compilation) runs automatically at session end via the

compile-session-defrag.sh

For full compilation, invoke

$compile

# Example: external cron entry for nightly compilation
0 3 * * * cd /path/to/repo && AGENTOPS_COMPILE_RUNTIME=ollama bash skills-codex/compile/scripts/compile.sh --force

AgentOps exposes this flow through

ao compile

launchd

cron

systemd

ao compile --force --runtime ollama

bash skills-codex/compile/scripts/compile.sh

ao overnight start

$compile

Interactive Modes

These modes describe the interactive

$compile

--compile-only

--lint-only

--defrag-only

--mine-only

--full

--since 26h

--incremental

--force

Headless Script Flags

For unattended runs,

bash skills-codex/compile/scripts/compile.sh

--sources <dir>

.agents

--output <dir>

.agents/compiled

--incremental

--force

--lint-only

--full

Examples

User says:

$compile

User says:

$compile --compile-only

User says:

$compile --lint-only

User says:

$compile --since 7d

Pre-evolve warmup: Run

$compile

$evolve

Troubleshooting

ao mine

--since

bushido tunnel ollama

OLLAMA_HOST

--incremental

Reference Documents

• references/phases.md — full per-phase procedure (mine → grow → compile → lint → defrag → report)
• references/confidence-scoring.md
• references/flywheel-diagnostics.md
• references/knowledge-synthesis-patterns.md

Local Resources

scripts/

• scripts/validate.sh