by-knowledge

BY Knowledge Graph

Persistent structured memory that turns isolated campaigns into a learning system. Each campaign writes outcomes, top designs, and failure modes into a JSON-backed graph so the next campaign benefits from prior art without re-running compute.

The store is intentionally minimal: append-only JSON files, no server process, no embeddings — keyword overlap is enough for the scale we operate at (hundreds to low thousands of campaigns). Six MCP tools wrap the storage layer so every agent in the BY suite reads and writes through the same contract.

---

When to Use This Skill

Use this skill when:

• ✅ Starting a new campaign — query prior campaigns and scaffold rankings before committing compute
• ✅ Finishing a campaign — record outcomes, top designs, and any failure patterns
• ✅ Diagnosing low pass rates — search for matching failure patterns from prior campaigns
• ✅ Pre-flight parameter selection — call knowledge_get_recommendations to seed defaults
• ✅ Periodic maintenance — run knowledge_consolidate after every 20-30 campaigns
• ✅ Cross-target analysis — compare hit rates of a scaffold across target classes

Don't use this skill for:

• ❌ Storing raw design files — those live in the campaign directory (FASTA, PDB, CIF)
• ❌ Storing every design from a campaign — record the top 10-20 only (selectivity matters)
• ❌ Replacing the research dossier — by-research writes research/research.md; this skill stores the summary
• ❌ Per-job telemetry or compute logs — use by-campaign-manager checkpoints instead
• ❌ Free-form notes that have no entity to attach to — write them to .claude/memory/ directly

The graph is a long-lived asset. Be selective on writes; aggressive on queries.

---

Quick Start

# 1. Query prior art at campaign start
result = mcp__by_knowledge__knowledge_query_similar(
    target_description="TNF-alpha cytokine homotrimer autoimmune",
    modality="VHH",
    top_k=5,
)

# 2. Record outcomes at campaign end (top 10-20 designs, not all of them)
mcp__by_knowledge__knowledge_store_campaign(
    target="TNF-alpha",
    modality="VHH",
    parameters={"scaffold": "caplacizumab", "seeds": 4, "temperature": 0.7},
    outcomes={
        "hit_rate": 0.23,
        "best_ipsae": 0.78,
        "best_iptm": 0.85,
        "screening_pass_rate": 0.18,
    },
    notes="Iter-2 hotspot refinement converged on Y56/R113",
    designs=[
        {"design_id": "tnf_001", "scaffold": "caplacizumab", "ipsae": 0.78, "iptm": 0.85, "status": "PASS"},
        # ... up to ~20 top designs
    ],
)